Sign in

v1

latestOpenAPI 3.1.02026-07-2665164286.3 KB
Avatars

Create Avatar

Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.

post/v3/avatars

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

OR
OR

Response

Successful response

Example response

{
  "data": {
    "avatar_item": {
      "id": "lk_abc123",
      "name": "Business Suit",
      "group_id": "ag_abc123",
      "preview_image_url": "https://files.heygen.ai/look/business_preview.jpg",
      "preview_video_url": "https://files.heygen.ai/look/business_preview.mp4",
      "gender": "female",
      "tags": [
        "business",
        "formal"
      ],
      "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "supported_api_engines": [
        "avatar_v",
        "avatar_iv",
        "avatar_iii"
      ],
      "image_width": 1920,
      "image_height": 1080,
      "error": {
        "code": "training_failed",
        "message": "Footage duration must be between 15s and 600s"
      }
    },
    "avatar_group": {
      "id": "ag_abc123",
      "name": "Anna",
      "preview_image_url": "https://files.heygen.ai/avatar/anna_preview.jpg",
      "preview_video_url": "https://files.heygen.ai/avatar/anna_preview.mp4",
      "gender": "female",
      "created_at": 1711929600,
      "looks_count": 3,
      "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "consent_status": "approved",
      "error": {
        "code": "training_failed",
        "message": "Footage duration must be between 15s and 600s"
      }
    }
  }
}