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",
  "preprocessed": false,
  "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 avatars accessible to the authenticated user (filtered by org/owner via the multi-tenancy access query).

Scope: avatars:read

Response 200 OK

{
  "avatars": [
    {
      "_id": "avt_abc123",
      "name": "Support Agent",
      "tier": "stylized_3d",
      "status": "ready",
      "userId": "user_456",
      "organizationId": "org_xyz",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

---

GET /api/v1/avatars/:id

Get a single avatar by ID.

Scope: avatars:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Avatar 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
  }
}

Field	Type	Required	Description
name	string	Yes	Avatar display name
tier	string	Yes	Avatar tier (e.g. stylized_3d); drives default resources
description	string	No	Avatar description
resources	object	No	Override { cpu, memory, gpu, gpuType }; defaults vary by tier
config.resolution	string	No	Render resolution (default 512x512)
config.frameRate	integer	No	Render frame rate (default 30)
config.idleMotion	boolean	No	Enable idle motion (default true)

Response 201 Created

{
  "_id": "avt_abc123",
  "name": "Support Agent",
  "description": "Friendly customer support avatar",
  "tier": "stylized_3d",
  "preprocessed": false,
  "status": "creating",
  "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"
}

---

PUT /api/v1/avatars/:id

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

Scope: avatars:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Avatar ID

Request Body

{
  "name": "Updated Support Agent",
  "description": "Updated description",
  "config": { "resolution": "1024x1024", "frameRate": 60 },
  "resources": { "cpu": "200m", "memory": "512Mi" }
}

Field	Type	Required	Description
name	string	No	New avatar name
description	string	No	New description
config	object	No	New render config
resources	object	No	New resource allocation

Response 200 OK

{
  "_id": "avt_abc123",
  "name": "Updated Support Agent",
  "description": "Updated description",
  "config": { "resolution": "1024x1024", "frameRate": 60 },
  "resources": { "cpu": "200m", "memory": "512Mi" },
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

DELETE /api/v1/avatars/:id

Delete an avatar.

Scope: avatars:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Avatar ID

Response 200 OK

{
  "_id": "avt_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

Parameter	Type	Required	Description
id	string	Yes	Avatar ID

Response 200 OK (Tier 1 — stylized_3d)

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

Response 200 OK (Tier 2/3)

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

Error 503 Service Unavailable

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

{
  "error": "Avatar rendering container not deployed. Deploy the avatar first."
}