Turn a script into a narrated, captioned video

A narrated, captioned video from a script of 20–3,000 characters (about three minutes at most): a narrator from GET /api/v1/voices or the person’s own voiceover, a look, a caption style, a pace and a shape (9:16, 16:9, 1:1) — the Story page’s run. Priced by length: the narration by the script’s characters, the composing by how long the story runs, then the render — the quote says each part. Looks and caption styles: GET /api/v1/models (studio "story"). It comes back as a job (kind "story") to follow with GET /api/v1/jobs/{jobId}. Longer scripts are not taken yet.

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

Request

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

Response202 Accepted

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

POST/stories/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

scriptstringrequiredThe words the narrator reads, as they are to be heard.
voiceIdstringThe narrator: a voice id from GET /api/v1/voices. Give this or voiceoverMediaId.
voiceoverMediaIdstringTheir own voiceover instead of a narrator: the id of a voiceover take (POST /api/v1/voiceovers returns it) or a recording in their library. The story runs as long as it, and no narration is charged.
pacestringHow fast the narrator reads: slow, normal (the default) or fast. A slower read runs longer and costs more to compose.slownormalfast
lookstringA look id from GET /api/v1/models (studio "story"). Default: "bold-tiktok".bold-tiktokeditorial-serifios-glassmagazinewhiteboardmr-beastpodcast-clipnews-broadcastsports-highlightbeauty-luxurygaming-neonfinance-protech-explainerkids-explainerwellness
captionStylestringA caption style id from GET /api/v1/models (studio "story"), or "auto" to follow the look (the default).autoimpact-slameditorial-minimalluxury-serifglass-techmarker-energyretro-collageword-popclean-subtitle
aspectRatiostringThe shape: 9:16 (the default), 16:9 or 1:1.9:1616:91:1
directionstringA line of direction for the visuals, e.g. "keep it calm, mostly typography".
titlestringWhat the story is called in their library.
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/stories/quotePrice it: turn a script into a narrated, captioned video