Make picture ads from a template, a product or a brief

Make picture ads from a product, as Ads Studio does, one of three ways: template (a ready-made ad style applied to the product’s picture — leave templateId out to list the templates, free), recreate (an ad they like, remade with their product), or brief (up to 8 concepts at once from a written brief). The product’s picture goes in as a storage key (POST /api/v1/library/use with a product gives one) or an https link to it. The ads are made inside the call, so the answer waits until they are, and comes with their links; the job to check again later is kind "picture-ads" with the Idempotency-Key as its id.

Key needs: create · Make things and spend credits
Price it first: POST /picture-ads/quote · free
Answers: A job to follow

Request

curl -X POST https://vessero.com/api/v1/picture-ads \
  -H "Authorization: Bearer $VESSERO_API_KEY" \
  -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \
  -H "Content-Type: application/json" \
  -d '{
    "way": "template",
    "confirmCredits": 1
  }'

Response202 Accepted

{
  "object": "job",
  "id": "picture-ads.8f1c2d3e-4b5a-4789-8abc-def012345678",
  "kind": "picture-ads",
  "status": "working",
  "stage": "Queued",
  "files": [],
  "credits": 58,
  "url": "/api/v1/jobs/picture-ads.8f1c2d3e-4b5a-4789-8abc-def012345678"
}

POST/picture-ads/quoteFree

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.
Preferstringwait=N (up to 60): hold the answer up to N seconds while the job is made, within 80 seconds for the whole call.

Body

waystringrequiredtemplate, recreate or brief.templaterecreatebrief
templateIdstringTemplate: which template. Leave it out to get the list (free; nothing runs).
productKeystringThe product’s picture: 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). Needed for template and recreate; optional for a brief.
castMemberIdstringTemplate: someone from their cast as the model in the ad (GET /api/v1/cast).
adKeystringRecreate: the ad they like, a picture: 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).
promptstringTemplate: words to add (optional). Recreate: what to change — their product in, and anything else (needed).
resolutionstringTemplate or recreate: 2k (the default) or 4k.2k4k
aspectRatiostringTemplate: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9 (default auto, the template’s own). Brief: 1:1, 4:5, 5:4, 3:4, 4:3, 2:3, 3:2, 9:16, 16:9, 21:9, 1:2, 2:1 (default 9:16).
briefstringBrief: what the ads sell, and to whom (needed).
nichestringBrief: the niche.
audiencestringBrief: who the ads are for.
languagestringBrief: the language of the ads’ words. Default English.
conceptsintegerBrief: how many concepts, 1–8. Default 4.
confirmCreditsintegerrequiredThe price you agree to, in credits: the credits its 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 (409 price_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, 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.

Next in AdsPOST/picture-ads/quotePrice it: make picture ads from a template, a product or a brief