Skip to main content

Avatars

Create and manage interactive avatars for conversational agents. Supports three tiers: client-rendered stylized 3D (VRM), and GPU-rendered Tier 2/3 avatars served by a dedicated rendering container.

All endpoints require authentication via X-API-Key header and the appropriate scope.

Avatar Object​

{
  "_id": "avt_abc123",
  "name": "Support Agent",
  "description": "Friendly customer support avatar",
  "tier": "stylized_3d",
  "renderStyle": "vrm",
  "preprocessed": true,
  "status": "ready",
  "resources": {
    "cpu": "100m",
    "memory": "256Mi"
  },
  "config": {
    "resolution": "512x512",
    "frameRate": 30,
    "idleMotion": true
  },
  "sourceModel": "https://cdn.strongly.ai/avatars/support-agent.vrm",
  "renderingEndpoint": null,
  "userId": "user_456",
  "organizationId": "org_xyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

GET /api/v1/avatars​

List the avatars you may use, newest first.

Scope: avatars:read

Query Parameters

ParameterTypeRequiredDescription
namestringNoOnly the avatar with exactly this name
limitintegerNoResults per page
cursorstringNometa.nextCursor of the previous page

Response 200 OK

{
  "data": [
    {
      "_id": "avt_abc123",
      "name": "Support Agent",
      "tier": "stylized_3d",
      "status": "ready",
      "userId": "user_456",
      "organizationId": "org_xyz",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "nextCursor": null, "requestId": "req_abc123" }
}

GET /api/v1/avatars/:id​

Get a single avatar by ID.

Scope: avatars:read

Path Parameters

ParameterTypeRequiredDescription
idstringYesAvatar ID

Response 200 OK

Returns the full Avatar object.

POST /api/v1/avatars​

Create a new avatar. Default resource allocation is derived from tier: stylized 3D gets a small CPU pod; Tier 2/3 gets a GPU pod with nvidia-a10.

Scope: avatars:write

Request Body

{
  "name": "Support Agent",
  "tier": "stylized_3d",
  "description": "Friendly customer support avatar",
  "resources": {
    "cpu": "100m",
    "memory": "256Mi"
  },
  "config": {
    "resolution": "512x512",
    "frameRate": 30,
    "idleMotion": true
  }
}
FieldTypeRequiredDescription
namestringYesAvatar display name
tierstringYesAvatar tier (e.g. stylized_3d); drives default resources
descriptionstringNoAvatar description
resourcesobjectNoOverride { cpu, memory, gpu, gpuType, useSpot, spotFallback }; defaults vary by tier. useSpot runs a GPU avatar on spot capacity (a reclaim drops a live call); spotFallback (default true) falls back to on-demand when no spot is available
config.resolutionstringNoRender resolution (default 512x512)
config.frameRateintegerNoRender frame rate (default 30)
config.idleMotionbooleanNoEnable idle motion (default true)

Response 201 Created

{
  "data": {
    "_id": "avt_abc123",
    "name": "Support Agent",
    "description": "Friendly customer support avatar",
    "tier": "stylized_3d",
    "renderStyle": "vrm",
    "preprocessed": false,
    "status": "preprocessing",
    "resources": { "cpu": "100m", "memory": "256Mi" },
    "config": { "resolution": "512x512", "frameRate": 30, "idleMotion": true },
    "userId": "user_456",
    "organizationId": "org_xyz",
    "createdAt": "2025-02-01T14:22:00Z",
    "updatedAt": "2025-02-01T14:22:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

PATCH /api/v1/avatars/:id​

Update an existing avatar. Only name, description, config, and resources may be modified.

Scope: avatars:write

Path Parameters

ParameterTypeRequiredDescription
idstringYesAvatar ID

Request Body

{
  "name": "Updated Support Agent",
  "description": "Updated description",
  "config": { "resolution": "1024x1024", "frameRate": 60 },
  "resources": { "cpu": "200m", "memory": "512Mi" }
}
FieldTypeRequiredDescription
namestringNoNew avatar name
descriptionstringNoNew description
configobjectNoNew render config
resourcesobjectNoNew resource allocation

Response 200 OK

{
  "data": {
    "_id": "avt_abc123"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

DELETE /api/v1/avatars/:id​

Delete an avatar.

Scope: avatars:write

Path Parameters

ParameterTypeRequiredDescription
idstringYesAvatar ID

Response 204 No Content

Returned when the avatar is already gone. No response body.

Response 202 Accepted

Returned while the avatar's GPU rendering pod is being torn down. The avatar reads status deleting until it is removed.

{
  "data": {
    "status": "deleting"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

POST /api/v1/avatars/:id/preview​

Generate a preview for an avatar. For Tier 1 (stylized_3d) the client renders the VRM model directly -- the response just returns the source model URL. For Tier 2/3 the call proxies to the avatar's rendering container, which must already be deployed.

Scope: avatars:write

Path Parameters

ParameterTypeRequiredDescription
idstringYesAvatar ID

Response 200 OK (Tier 1 -- stylized_3d)

{
  "data": {
    "avatarId": "avt_abc123",
    "previewUrl": "https://cdn.strongly.ai/avatars/support-agent.vrm",
    "tier": "stylized_3d",
    "renderStyle": "vrm",
    "message": "Tier 1 avatars render client-side. Use the VRM model URL directly."
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Response 200 OK (Tier 2/3)

{
  "data": {
    "avatarId": "avt_abc123",
    "previewUrl": "https://renders.strongly.ai/preview/abc123.mp4",
    "status": "completed"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Error 503 Service Unavailable

Returned when the avatar's rendering container is not deployed or unreachable.

{
  "type": "urn:strongly:problem:service-unavailable",
  "title": "service-unavailable",
  "status": 503,
  "detail": "Avatar rendering container not deployed. Deploy the avatar first.",
  "code": "service-unavailable",
  "requestId": "req_abc123"
}

PUT /api/v1/avatars/:id/source​

Upload the asset an avatar renders from, as multipart/form-data (field file): a VRM or glTF model for tier 1, a portrait image for tiers 2 and 3. The first upload moves the avatar to its next state.

Scope: avatars:write

ParameterTypeRequiredDescription
idstringYesAvatar id

Response 200 OK: { url, key, bucket, size, field }; field is sourceModel or sourceImage.