Retrieve an avatar

GET

/v1/avatars/{avatar_id}

const url = 'https://example.com/v1/avatars/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/v1/avatars/example \
  --header 'Authorization: Bearer <token>'

Return a single avatar by id.

Authorizations

ApiKey

Parameters

Path Parameters

avatar_id

required

Avatar Id

av_… prefixed ULID.

string

av_… prefixed ULID.

Responses

200

Successful Response

application/json

Avatar

Public Avatar resource returned by GET /v1/avatars and GET /v1/avatars/{id}.

object

created_at

required

string format: date-time

required

av_… prefixed ULID.

string

is_demo

required

True for platform built-in avatars (e.g. av_demo).

boolean

name

required

string

object

string

default: avatar

Allowed value: avatar

runtime_type

required

Runtime that serves this avatar (e.g. mock, gaussian).

string

status

required

AvatarStatus

Lifecycle of a custom avatar.

ready — usable for sessions. processing — being fitted / converted. failed — fitting failed; will not be usable without re-upload.

string

Allowed values: ready processing failed

Example

{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "av_demo",
  "is_demo": true,
  "name": "Demo (Mock)",
  "object": "avatar",
  "runtime_type": "mock",
  "status": "ready"
}

401

Missing or invalid API key.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}

404

No avatar with that id.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}

422

Request body or parameters failed validation.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}