Skip to content
Protoface

Create a custom avatar from an image

POST
/v1/avatars
 
curl --request POST \
  --url https://example.com/v1/avatars \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form image=example \
  --form 'name=Custom Avatar' \
  --form runtime_type=avtr1

Upload a portrait image to build a custom avatar. Returns the avatar in processing; poll GET /v1/avatars/{id} until it is ready (or failed). multipart/form-data: image (PNG/JPEG), name, and optional runtime_type (default avtr1).

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type multipart/form-data
Body_create_avatar
object
image
required

Portrait image (PNG or JPEG).

string
name

Display name for the avatar.

string
default: Custom Avatar
runtime_type

Build stack. Default avtr1.

string
default: avtr1

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Successful Response

Media type application/json
Avatar

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

object
created_at
required
string format: date-time
id
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

Section titled “401 ”

Missing or invalid API key.

Media type 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
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

Section titled “422 ”

Unsupported image or stack.

Media type 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
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"
  }
}