Generate UGC Video

Generate a UGC video when you already have a ready avatar and want that avatar to speak a script in a product or campaign scene. Video generation is asynchronous: the create request returns a video ID immediately, then the final video_url is available after the video reaches ready.

Use Generate UGC video API for the complete request and response reference.

UGC usage model

Videos always use an existing ready avatar. Create the avatar once, store the avatar ID, then reuse it across videos by changing the script, product image, scene, title, or output ratio.

Use case	How to model it
One avatar, many products	Reuse the same `avatar.avatar_id` and change `product_image` plus `script`.
One campaign, many scenes	Reuse the avatar and change `scene` for each creative variant.
Many presenters	Create separate avatars first, then generate each video with the matching avatar ID.
User-generated content workflows	Let users create or select an avatar, then generate videos from that saved avatar.

Required inputs

Each video needs a spoken script, a product or reference image, and a ready avatar ID.

The avatar must already be ready. If the avatar is still processing, poll Get avatar before starting video generation.

Direct the scene

Use scene.type: "prompt" when you want Sume to generate a background from text.

Use scene.type: "photo" when you have a specific background or reference image URL.

Track completion

Poll Get avatar video until the video is ready, or include webhook_url to receive avatar_video.ready or avatar_video.failed. When the video is ready, the response includes video_url.

Create or select a ready avatar

Use an avatar ID from Create Avatar or from your saved avatar library.
Send the video request

Provide the script, product image URL, avatar.mode: "existing", and avatar.avatar_id.
Poll or listen for a webhook

Wait for ready before showing, downloading, or publishing the video.