Generate UGC video API
Imported API route:
POST /v1/avatar-videos
Generates a UGC video asynchronously. The avatar must already be ready.
For guidance on reusing avatars across videos and directing scenes, see
Generate UGC Video.
This endpoint reserves Sume credits before the video 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.
Polling remains supported through Get avatar video. You can also include webhook_url to receive a completion webhook.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
script | string | Yes | Spoken script for the generated video. |
voice_id | string | No | Optional voice identifier. |
product_image | string | Yes | Product/reference image URL. |
background | string | No | Legacy background prompt. Prefer scene. |
scene.type | string | No | prompt or photo. Controls the first generated reference frame background. |
scene.prompt | string | Required when scene.type is prompt | Scene direction, such as in front of a mirror inside a room. |
scene.image_url | string | Required when scene.type is photo | Scene/background image URL. |
avatar.mode | string | Yes | Use existing. |
avatar.avatar_id | string | Yes | Ready avatar ID. |
resolution | string | No | Optional output resolution. Use 720p when provided. |
ratio | string | No | Output aspect ratio. Defaults to 9:16. |
aspect_ratio | string | No | Alias for ratio. |
title | string | No | Optional video title. |
webhook_url | string | No | HTTPS URL that receives avatar_video.ready or avatar_video.failed when the job reaches a terminal state. |
Request
webhook_url is optional. When provided, Sume sends avatar_video.ready or
avatar_video.failed after the job reaches a terminal state. See
Webhooks for payloads, signatures, and retry behavior.
You can also use a reference image as the scene background:
Response
Use Get avatar video to poll for video_url.