AI Avatars

GET /v1/avatars

Avatars usable with the AI avatar generator, which renders a presenter speaking your script.

Your workspace's own photo avatars are always returned first, marked custom: true. The stock library runs to thousands, so search with q rather than paging through it.

Query parameters

Parameter	Type	Default	Description
q	string	-	Search by name
gender	string	-	Filter by gender label
page	number	1	Page number
limit	number	50	Results per page, max 100

Example

curl "https://api.vidocu.ai/v1/avatars?q=anna&limit=5" \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "avatars": [
    {
      "avatarId": "Anna_public_3_20240108",
      "name": "Anna",
      "previewImageUrl": "https://files.heygen.ai/...",
      "previewVideoUrl": "https://files.heygen.ai/...",
      "defaultVoiceId": "21m00Tcm4TlvDq8ikWAM",
      "gender": "female",
      "custom": false
    }
  ],
  "customCount": 0,
  "pagination": { "total": 3, "page": 1, "limit": 5, "totalPages": 1 }
}

pagination counts the stock library only. Custom avatars are returned in full on page 1 and aren't paginated - a workspace has a handful, and hiding them behind page 2 of a stock list would be surprising.

Get one avatar

GET /v1/avatars/:id

curl https://api.vidocu.ai/v1/avatars/Anna_public_3_20240108 \
  -H "Authorization: Bearer vdo_live_your_key_here"

Your workspace's own avatars are checked first, so a custom avatar wins if it shares an ID with a stock one. Returns 404 if neither has it.

Create a photo avatar

POST /v1/avatars

Build an avatar from a photo. Requires an Enterprise plan and the avatars:write scope.

curl -X POST https://api.vidocu.ai/v1/avatars \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl": "https://example.com/headshot.jpg", "name": "Dana"}'

Response 201 Created

{
  "avatarId": "abc123...",
  "name": "Dana",
  "previewImageUrl": "https://files.heygen.ai/...",
  "custom": true
}

The image is fetched by our servers, so it must be publicly reachable - internal and private addresses are refused. The avatar is saved to your workspace immediately, so it shows up in the list above without any further step.

Using an avatar

Pass avatarId to the ai-avatar-generator tool via Execute Tool. Avatar rendering is one of the most expensive operations - check the rate with GET /v1/usage/credits before committing to a long script.

Errors

Status	Code	Cause
401	authentication_error	Invalid or missing API key
403	insufficient_scope	Token lacks avatars:read