Reference · Ads
Make a UGC video ad: presenters, product, voice and captions
Make one UGC ad video as the UGC Ads page makes it: the words — what happens, and what is said, in quotes — and whatever it is made from: presenters (someone from their cast, or a character they bring as pictures), the product (pictures of it), other pictures, a video to look like, a voice for each presenter. Only the words are needed. Every picture, video and recording goes in as a storage key or an https link to the file, brought into their Uploads first. Name what is added in the words by its tag: @Presenter1…, @Product1…, @Image1…, @Video1, @Audio1… (sounds in order). For N ads, call it N times, each with a new Idempotency-Key; takes makes several takes of one ad. A new ad starts as a fresh UGC Ads bar does: no captions and no "AI-generated" label; ask for captions (captionStyle) or the label (aiLabel) when the person wants them, and set the captions' size (captionSize) and place (captionPosition) as the Captions panel does. Video models: GET /api/v1/models (studio "ugc"). The quote gives the page’s notes — the parts a long script is made in, a line that reads like a testimonial, words that will not fit — which are said, not stops. It comes back as a job (kind "ugc") to follow with GET /api/v1/jobs/{jobId}. It is made One shot, the page’s default: the words and pictures go straight to the video model, and a first frame is drawn on the way only where the model can’t take them as they are (a real person in it, a model that takes no references, a lip-sync with no presenter). To check a preview before paying for the video, set pictureFirst (Step by step): only the previews are made, then the job waits for the person’s yes, and POST /api/v1/ugc-ads/{adId}/video makes the video.
- Key needs
create· Make things and spend credits- Price it first
POST /ugc-ads/quote· free- Answers
- A job to follow
curl -X POST https://vessero.com/api/v1/ugc-ads \ -H "Authorization: Bearer $VESSERO_API_KEY" \ -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \ -H "Content-Type: application/json" \ -d '{ "prompt": "@Presenter1 holds @Product1 up to the camera in @Image1 and says: “This serum has fifteen percent vitamin C, and it is light enough to wear under make-up.”", "videoModel": "seedance-2.5", "presenters": [ { "kind": "pictures", "pictureKeys": [ "https://example.com/people/zola.jpg" ], "whoIsIn": { "kind": "no-person" }, "name": "Zola" } ], "productPictureKeys": [ "https://example.com/products/glow-serum.jpg" ], "pictureKeys": [ "https://example.com/sets/sunny-kitchen.jpg" ], "aspect": "9:16", "captionStyle": "word-pop", "confirmCredits": 194, "webhookUrl": "https://example.com/hooks/vessero" }'
{ "object": "job", "id": "ugc.8f1c2d3e-4b5a-4789-8abc-def012345678", "kind": "ugc", "status": "working", "stage": "Queued", "files": [], "credits": 58, "url": "/api/v1/jobs/ugc.8f1c2d3e-4b5a-4789-8abc-def012345678" }
The same body without confirmCredits. It answers the price and your balance, and runs nothing.
Header
- Idempotency-KeystringYour id for this request: 8–64 letters, digits, - or _. A repeat within 10 minutes gets the first answer back and never runs twice. Use the same one for the quote and the run.
- Preferstring
wait=N(up to 60): hold the answer up to N seconds while the job is made, within 80 seconds for the whole call.
Body
- promptstringrequiredThe words: what happens, and what is said in quotes (straight or curly), naming what is added by its tag, e.g. @Presenter1 holds @Product1 up to the camera in a sunny kitchen and says: “This is the only serum I reach for.”
- videoModelstringrequiredThe model that makes the clip: an id from GET /api/v1/models (studio "ugc").
- presenters(object · kind cast | pictures)[] · up to 4Up to 4 people in it, @Presenter1 first: {kind: "cast", castMemberId, voice?}, or {kind: "pictures", pictureKeys, whoIsIn, name?, voice?} for a character they bring.
- voiceobject · kind own | model | library | recordingThe voice when no presenter is added: the person the model draws speaks in it. Default: the video model’s own.
- productPictureKeysstring[] · up to 3Up to 3 pictures of the product.
- pictureKeysstring[] · up to 3Up to 3 other pictures — a place, a prop — named @Image1… in the words.
- lookLikeobjectA video to look like (@Video1): it goes to the model as a reference.
- keystringrequiredThe video: a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first).
- durationSecnumberIts length in seconds, as GET /api/v1/library (tab "uploads") or POST /api/v1/library/use gives it. Default: read from the file.
- whoIsInobject · kind no-person | personrequiredWho is in it, as the person says: {kind: "no-person"}, or {kind: "person", name, agreed} for a real person (named, with their permission).
- pictureModelstring | nullThe model that draws Step by step’s previews, and in one call (One shot) a first frame only where the video model can’t take the pictures as they are: from GET /api/v1/models (studio "ugc", pictureModels). Default: "seedream-5-pro". null never draws one.
- pictureFirstbooleantrue: make it step by step, as Step by step on the UGC Ads page does: only each take’s preview, the picture its video opens on, is made now, for its own price, so the person can check the face, the product and the place before the video is paid for. The quote is then the previews alone, and says what the video costs after. Once the preview is in, the job (kind "ugc") waits with its link; POST /api/v1/ugc-ads/{adId}/video makes the video, or POST /api/v1/ugc-ads/{adId}/picture draws a preview again, each quoted first. Needs a picture model: not with pictureModel null. Default false: One shot, the page’s default too — one call makes the whole video.
- pictureChoicesintegerWith pictureFirst: how many previews each take draws to pick from, 1–3, each priced as one — Previews to pick from on the UGC Ads page. GET /api/v1/jobs/{jobId} lists each with its pictureId; the video starts from the one sent to POST /api/v1/ugc-ads/{adId}/video. Default 1.
- aspectstringThe shape: 9:16, 4:5, 1:1, 16:9. Default 9:16.
9:164:51:116:9 - resolutionstringA size the video model lists, e.g. "1080p". Default 720p.
- durationSecintegerA length the video model makes, in seconds. Default: fitted to the words.
- captionStylestringThe captions, as the Captions menu offers them: none (No captions), auto (Auto), word-pop (Word Pop), impact-slam (Impact Slam), clean-subtitle (Clean Subtitle), editorial-minimal (Editorial), luxury-serif (Luxury Serif), glass-tech (Glass Tech), marker-energy (Marker Energy), retro-collage (Retro Collage). Default none (No captions).
noneautoword-popimpact-slamclean-subtitleeditorial-minimalluxury-serifglass-techmarker-energyretro-collage - captionSizeintegerHow big the captions are, in per cent of the style's own size, as the Captions panel's Size slider sets it: S 60, M 100, L 130, XL 160, or any whole number between. Default 100.
- captionPositionstring | numberWhere the captions sit, as the Captions panel sets it: "top" (under the AI label when it is on), "middle", "bottom" (the default, where captions always sat), or the caption block’s centre as a share of the frame’s height, 0–1, kept inside what the platform leaves clear.
- takesintegerTakes of this one ad, 1–4, each its own video. Default 1.
- aiLabelbooleanThe "AI-generated" label on every frame, top left. Default false: true only if the person asks for it. Without it, they say it was made with AI where they post it.
- confirmCreditsintegerrequiredThe price you agree to, in credits: the
creditsits quote gave. It runs at that price, or at a lower one when that figure was quoted for this Idempotency-Key; above the price now, nothing runs (409price_changed). Left out, nothing runs and the error carries the quote. - webhookUrlstring · httpsAn https address to POST the job to once it is done or has failed — or waits for a yes, as a UGC ad made step by step does once its previews are in — signed (see Webhooks).
Answers
- 202jobStarted: follow the job, or wait for its webhook.
- 200jobA job that ended at once: done, or failed (see error and charged).
- 400confirm_credits_requiredA run that spends needs confirmCredits: the quote is in details.
- 402insufficient_creditsThe account has too few credits for this.
- 409price_changedThe price is above the confirmCredits sent: nothing ran; the new quote is in details.
- 422content_refusedThe content check refused it.
- 429daily_cap_reachedThe key’s daily credit cap would be passed: see Retry-After.