Visual API

Endpoints that serve images and recordings. All of them return binary content and are safe to use directly as src attributes — responses carry a Cache-Control max-age and the engine caches the generated images in its own resource storage.

Visual Assets

Thumbnails are composed server-side from the agent’s avatar and environment and delivered in the requested image format.

Format and Size

Format is selected by the file extension of the last path segment. Supported values are png (default when no extension is given) and webp; any other extension is rejected with 400 Bad Request.

Because refs may themselves contain dots (an agent ref can end with a revision, e.g. ama.0), only a known format suffix is interpreted as a format — a numeric suffix stays part of the ref.

The optional width query parameter (in pixels) resizes the result. It must be within the deployment’s configured maximum, otherwise 400 Bad Request is returned. Thumbnails are composed with a 3:4 aspect ratio.

GET /api/visual/agent/{agentRef}[.{format}]

Thumbnail of an agent, composed from the avatar and environment of its visualProperties. Use this whenever the thumbnail field of the Agent object is not set.

Path Parameters

Parameter Type Description

agentRef

String

Agent ref, optionally revision-qualified (acme-support.5).

format

String

Optional extension appended to the ref: png (default) or webp.

Query Parameters

Parameter Required Type Description

width

No

Integer

Target width in pixels. Must be between 1 and the deployment maximum.

noEnvironment

No

Boolean

When true the avatar is rendered without its environment background. Default false.

Response

image/png or image/webp. Responds 404 when the agent has no avatar configured. Agents whose avatarRef starts with live-avatar: are served from the external avatar provider, equivalent to the live-avatar endpoint below.

GET /api/visual/project/{idOrRef}

Logo of a project. Falls back to the platform’s default project logo location when the project has no explicit logo URL.

Path Parameters

Parameter Type Description

idOrRef

String

Project UUID or ref. The format is auto-detected.

Query Parameters

Parameter Required Type Description

width

No

Integer

Target width in pixels; the logo is resized and re-encoded. Must be between 1 and the deployment maximum. Without it the stored image is returned unchanged.

Response

image/jpeg. Responds 404 when no logo is available for the project.

GET /api/visual/live-avatar/{avatarId}[.{format}]

Preview image of an externally rendered (LiveAvatar) avatar.

Path Parameters

Parameter Type Description

avatarId

String

Avatar identifier at the external provider.

format

String

Optional extension: png (default) or webp.

Query Parameters

Parameter Required Type Description

projectId

Yes

UUID

Project whose provider credentials are used to fetch the preview.

width

No

Integer

Target width in pixels.

Response

image/png or image/webp. Responds 404 when the project has no live-avatar credentials configured.

Session Recordings

Recordings exist only for sessions of projects where recording is enabled. Requesting a recording that was never produced responds 404.

GET /api/recording/session/{sessionId}.ts

The recorded session as an MPEG transport stream — the native recording format.

Path Parameters

Parameter Type Description

sessionId

UUID

Session whose recording is requested.

Response

video/mp2t, streamed from resource storage. Takes no query parameters.

GET /api/recording/session/{sessionId}.mp4

The same recording remuxed to MP4 on the fly, which is what browsers and mobile players expect.

Path Parameters

Parameter Type Description

sessionId

UUID

Session whose recording is requested.

Response

video/mp4, streamed. The stream is fragmented (frag_keyframe+empty_moov) so playback can start before the whole file has been transferred. Takes no query parameters.