Reference · Ads
POST/ugc-ads/quote
Price it: make a UGC video ad: presenters, product, voice and captions
The price for exactly this body, the balance beside it and any notes. Nothing runs and nothing is charged. Run it with POST /api/v1/ugc-ads, the same body, confirmCredits set to credits and the same Idempotency-Key.
- Key needs
create· Make things and spend credits- Runs it
POST /ugc-ads- Answers
- A quote · free
Request
curl -X POST https://vessero.com/api/v1/ugc-ads/quote \ -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" }'
Response200 OK
{ "object": "quote", "credits": 12, "balance": 840, "lines": [ "1 image × 12 (Nano Banana Pro · 4K)" ], "notes": [], "requestId": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec", "run": { "method": "POST", "path": "/api/v1/images", "confirmCredits": 12, "idempotencyKey": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec" } }
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.
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.
Answers
- 200quoteThe price for exactly this body, your balance and any notes. Nothing ran.
- 400invalid_requestA field is missing or not accepted: see details.
- 403feature_unavailableThe studio this needs is switched off for the account right now.
- 429rate_limitedToo many calls this minute: see Retry-After.