Skip to main content

Overview

UGC Studio makes user-generated-style ads: an AI avatar speaks your script to camera (voice and lip movement come from the video model, no voiceId needed), holding your product, showing your app, wearing your outfits or presenting a before and after. The voiceover format is the exception: a narrator voice reads the script over silent scenes of the avatar. Each format has its own endpoint, POST /v1/project/create/ugc-studio/{format}, and takes its own assets at the top of the body: Get avatar IDs from GET /v1/avatar/list and voice IDs from GET /v1/voice/list. media takes IDs of images or videos in your media library (add them with Upload Media or Import Media from URL); an ID that is not in your library, or not COMPLETED yet, answers 400. Image fields take HTTPS URLs. Every create call answers with the projectId. Poll GET /v1/project/{projectId} or pass a webhook to get the finished video.
The older POST /v1/project/create/ugc-ads, which names the format inside a ugcStudio object, still works but is deprecated. Use the per-format endpoints for new integrations.

Product in Hand

The avatar shows and uses your product. Wrap the words where the product should appear in [product] … [/product]. Your media, if any, plays as B-roll.

App Demo

The avatar talks about your app while a screen recording covers the frame, with the avatar in a corner card. Send the recording (or screenshots) as media, or let Hooked record your site from appUrl. showcaseAfterSeconds sets when the screencast enters.
To show your own recording instead, send it as media and leave out appUrl:

Outfit / Fashion

The avatar wears your outfits, one look per clip. Each photo in outfitImageKeys is dressed on the avatar and filmed; wrap the words for each look in [look 1] … [/look], [look 2] … [/look].
Already have outfit videos? Send them as media instead of outfitImageKeys (photos in media alone answer 400).

Before / After

A transformation ad: the before and the after enter on the lines that name them. Send your own photos as beforeImageKey and afterImageKey, or leave both out and they are generated from the avatar.

Voiceover

Nobody talks to camera: the narrator voiceId reads the script over silent scenes of the avatar. With productImageKey, one scene shows the product alone.

Shared fields

Every format also takes script, avatarId, name, language, aspectRatio, caption, content, musicId, webhook and metadata. All formats but voiceover take videoStyle; app demo and fashion also take the picture-in-picture adSettings (bRollType, avatarPresentation, removeAvatarBackground). Each format’s reference page lists exactly which fields it reads.
Managed teams pay 7 credits plus 100 per started 15 seconds of speech (estimated from the script, about 2.5 words per second), plus what the format generates on top (product, before/after or dressed images, outfit videos). The voiceover format is priced by its narration and generated scenes instead. The estimate is charged when the project is created and refunded if the project fails.Teams in bring-your-own-keys mode are not charged credits for generation, but need their own OpenRouter and Gemini keys in Settings → AI keys, plus Bria when the avatar background is removed in a picture-in-picture format. The voiceover format needs OpenRouter and ElevenLabs instead. Without them the call answers 402 with code: "missing_credentials" and the missingProviders list, before anything is created or charged. To retry a create call after a timeout or 5xx, send it with an Idempotency-Key: the same key never creates or charges twice.

Tips for UGC Studio

Be authentic: Write scripts that sound natural and conversational, not salesy
Hook in 2 seconds: Start with attention-grabbing words like “Stop scrolling!” or “POV:“
Use 9:16 format: Vertical videos perform better on TikTok, Reels, and Shorts
Keep it short: 15-30 seconds works best for social media ads

Effective Script Formulas

Handling the Webhook Response

Webhooks are signed: check the Hooked-Signature header as shown in Webhooks.