Captions API

Typical render

13 to 40 s

7 s and 42 s clips in our tests

Price

$0.02

per output minute

Input

Up to 15 minutes

500 MB per file

Example#

Send a public link to your video, or the URL of an upload, and a preset. The call waits up to 60 seconds for the render, so a short clip comes back finished.

curl -sS "https://api.reelsdk.com/v1/captions" \
  -H "Authorization: Bearer $REELSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/interview.mp4",
    "style": "karaoke"
  }'

Parameters#

Send a JSON body. Fields we don't recognize are ignored, so check the spelling of optional fields.

Caption styles#

Pass a preset name like bold, karaoke or minimal to style your captions right away. To change how they look, send a style object instead. It starts from the preset you name, or bold, and overrides only the fields you set.

All three presets draw a black outline. Colors accept #RRGGBB, #RGB or one of 15 names: white, black, yellow, gold, orange, red, pink, magenta, purple, blue, cyan, green, lime, gray and grey.

{
  "style": {
    "preset": "bold",
    "font": "Anton",
    "position": "bottom",
    "max_words": 2,
    "highlight_color": "lime"
  }
}

Languages and fonts#

We detect the language from the audio, or you can set language with a code like en or pt-BR to skip detection. Three-letter codes such as jpn work too.

Japanese, Chinese, Korean, Arabic, Hebrew, Thai, Devanagari, Lao and Myanmar text switches to a matching Noto font automatically. Chinese, Japanese and Korean captions break lines between words instead of at spaces, and right-to-left scripts render right to left.

Your own word timings#

If you already have word timings from your own transcriber or an edited transcript, pass them in words and we skip transcription. Each item is a word with start and end in seconds. An end earlier than its start is moved up to the start.

{
  "video_url": "https://example.com/interview.mp4",
  "style": {
    "preset": "karaoke",
    "highlight_color": "#FF5A36"
  },
  "words": [
    { "word": "Ship", "start": 0.12, "end": 0.41 },
    { "word": "it", "start": 0.41, "end": 0.58 },
    { "word": "today.", "start": 0.58, "end": 1.1 }
  ]
}

When we transcribe, send prompt with names and terms so the transcriber spells them right.

Response#

A finished job answers 200 and its outputs hold five file URLs. If the render takes longer than your wait, you get 202 with the same job and a poll_url. See Jobs for waiting and polling.

{
  "job": {
    "id": "job_q33902h8shjtevc5j2cd",
    "op": "captions",
    "status": "succeeded",
    "stage": null,
    "created_at": "2026-10-26T01:15:43.902Z",
    "finished_at": "2026-10-26T01:15:56.165Z",
    "outputs": {
      "video": "https://api.reelsdk.com/f/out/job_q33902h8shjtevc5j2cd/video.mp4",
      "transcript": "https://api.reelsdk.com/f/out/job_q33902h8shjtevc5j2cd/transcript.json",
      "srt": "https://api.reelsdk.com/f/out/job_q33902h8shjtevc5j2cd/captions.srt",
      "vtt": "https://api.reelsdk.com/f/out/job_q33902h8shjtevc5j2cd/captions.vtt",
      "ass": "https://api.reelsdk.com/f/out/job_q33902h8shjtevc5j2cd/captions.ass"
    },
    "result": null,
    "duration_s": 7.2,
    "error": null,
    "usage": {
      "output_seconds": 7.2,
      "audio_seconds": 7.211,
      "tts_characters": 0,
      "images": 0
    },
    "poll_url": "https://api.reelsdk.com/v1/jobs/job_q33902h8shjtevc5j2cd"
  }
}

transcript.json

{
  "text": "Three days by the water, mountains at sunrise, forests by noon, and a lake that held the whole sky.",
  "language": "en",
  "duration_s": 7.2,
  "words": [
    { "word": "Three", "start": 0, "end": 0.44 },
    { "word": "days", "start": 0.44, "end": 0.66 },
    { "word": "by", "start": 0.66, "end": 0.88 },
    { "word": "the", "start": 0.88, "end": 0.98 },
    { "word": "water,", "start": 0.98, "end": 1.32 }
  ]
}

captions.srt

1
00:00:00,000 --> 00:00:05,500
Three days by the water, mountains at
sunrise, forests by noon, and a lake that

2
00:00:05,500 --> 00:00:07,080
held the whole sky.

usage.output_seconds is the length of the captioned video and usage.audio_seconds the speech we transcribed. Output files stay up for 7 days.

Errors#

Validation problems return 400 before a job starts. Problems with the video itself fail the job with 422, and the body carries the job next to the error. The full list is in Errors.

Tips#

• Captions render in about the length of the clip. Clips longer than about a minute can outlast the default 60 s wait, so raise ?wait or use a webhook.
• Your video needs an audio track with speech, unless you send words.
• The srt and vtt files work with YouTube, video players and platforms that take subtitle files, so one job gives you burned-in captions and a subtitle track.
• Use quality: "draft" while you tune a style, then render the final cut with standard or high.

Last updated 26 October 2026