Skip to content
Log in
Developer API
Get your keyGet a key

Reference · Video

POST/captions

Burn captions into a clip

Caption a clip with speech — the Captions page: the clip is heard (in any language), what is said is set out as lines, and the captions are burned in, in one of eight styles. The first call listens (free; if it says it is still listening, call again with the same arguments in a few seconds) and then quotes the price with the lines heard: show the person both. To fix a misheard word, send the lines back as lines, each with the times it was heard at. Clips up to 5 minutes; styles, colours, sizes, places and the price a minute: GET /api/v1/models (studio "captions"). It comes back as a job (kind "captions") to follow with GET /api/v1/jobs/{jobId}.

Key needs
create · Make things and spend credits
Price it first
POST /captions/quote · free
Answers
A job to follow
Request
curl -X POST https://vessero.com/api/v1/captions \
  -H "Authorization: Bearer $VESSERO_API_KEY" \
  -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "kind": "upload",
      "key": "text"
    },
    "confirmCredits": 1
  }'
Response202 Accepted
{
  "object": "job",
  "id": "captions.8f1c2d3e-4b5a-4789-8abc-def012345678",
  "kind": "captions",
  "status": "working",
  "stage": "Queued",
  "files": [],
  "credits": 58,
  "url": "/api/v1/jobs/captions.8f1c2d3e-4b5a-4789-8abc-def012345678"
}
POST/captions/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

  • sourceobject · kind upload | video | media | cardrequiredThe clip to caption.
  • stylestringThe caption style: 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: word-pop.word-popimpact-slamclean-subtitleeditorial-minimalluxury-serifglass-techmarker-energyretro-collage
  • colourstringThe lit word's colour: style, yellow, lime, cyan, pink, orange; "style" keeps the style's own (the default). Clean Subtitle and Luxury Serif keep theirs.styleyellowlimecyanpinkorange
  • sizestring | numberHow big: S, M (the style's own, the default), L or XL, or a per cent of the style's own, 60–160.
  • positionstring | numberWhere the captions sit: top, middle or bottom (the default) keep to the area the apps leave clear; lowest is the very bottom, below it, where TikTok, Reels and Shorts may lay their own caption over the words. Or the block’s centre as a share of the frame’s height, 0–1.
  • shadowstringThe shadow under the words: default, none, light, medium or strong.defaultnonelightmediumstrong
  • linesobject[] · up to 600The lines to caption, when the person fixed what was heard: every line, in order, each at the times the quote gave it (a fixed word keeps its timing). Leave it out to caption the lines as heard.
    • startnumberrequiredWhen the line starts, in seconds.
    • endnumberrequiredWhen it ends, in seconds.
    • textstringrequiredIts words, with any misheard word fixed.
  • 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 VideoPOST/captions/quote