Create avatar API
Imported API route:
POST /v1/avatars
Creates a reusable avatar identity and returns an avatar ID immediately. Use the
avatar ID after the avatar is ready to generate UGC videos. For guidance on
choosing between prompt, photo, and props avatars, see
Create Avatar.
Poll Get avatar until the avatar is ready, or
include webhook_url to receive a completion webhook.
This endpoint reserves Sume credits before the avatar job is accepted. If the
API key's workspace or owner account does not have enough credits, the request
returns 402 insufficient_credits and no provider generation is started.
Generation requests are also rate limited per API key. See
Rate limits for the default limits and 429
response shape.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | prompt, photo, or props. |
name | string | Yes | Human-readable avatar name. |
prompt | string | Required for prompt | Avatar description. |
file.type | string | Required for photo | Use url. |
file.url | string | Required for photo | Portrait image URL. |
ethnicity | string | Required for props | Asian, South Asian, Southeast Asian, Black, Hispanic, Middle Eastern, White, or Wasian. |
sex | string | Required for props | male or female. |
age | integer | Required for props | Must be at least 20. |
webhook_url | string | No | HTTPS URL that receives avatar.ready or avatar.failed when the job reaches a terminal state. |
Prompt request
webhook_url is optional. When provided, Sume sends avatar.ready or
avatar.failed after the job reaches a terminal state. See
Webhooks for payloads, signatures, and retry behavior.