Media requirements

Prepare a source video the API can download and caption.

Video limits

Property	Limit
Source formats	MP4, MOV, WebM
Maximum file size	500 MiB (524,288,000 bytes)
Maximum duration	600 seconds
Maximum dimensions	Long edge ≤ 1920 pixels and short edge ≤ 1080 pixels
Audio	An audio track containing speech is required unless srt is provided
Output	MP4 video, SRT subtitles, JSON transcript

Both 1920 × 1080 landscape and 1080 × 1920 portrait videos are supported. A square video must fit within 1080 × 1080. Odd pixel dimensions may be rounded down by one pixel during encoding.

The API inspects the video automatically. Videos longer than 600 seconds fail validation; the API does not trim them. Credits are reserved for the actual duration rounded up to a whole second before caption preparation starts.

Use an existing SRT file

Include the file’s text in the optional srt JSON field of POST /v1/subtitles. This skips ElevenLabs transcription entirely, so the video may have no audio. The language field is ignored when srt is present.

{
  "video_url": "https://your-cdn.example/video.mp4",
  "preset": "highlight",
  "srt": "1\n00:00:00,000 --> 00:00:02,000\nHello world!\n\n2\n00:00:02,000 --> 00:00:04,000\nYour own captions.\n"
}

To read a local file into the request safely, use jq --rawfile:

jq -n --arg video_url "$VIDEO_URL" --rawfile srt captions.srt \
  '{video_url: $video_url, srt: $srt, preset: "highlight"}' |
  curl --fail-with-body "$CAPTIONCRAFT_API_URL/v1/subtitles" \
    -H "Authorization: Bearer $CAPTIONCRAFT_API_KEY" \
    -H "Content-Type: application/json" --data-binary @-

Use numbered, non-empty cues separated by blank lines, ordered by start time, with HH:MM:SS,mmm --> HH:MM:SS,mmm timestamps. UTF-8 text, a BOM, multiline captions, and LF or CRLF line endings are accepted. The SRT limit is 256 KiB UTF-8 and 8192 words; the full JSON body may be up to 512 KiB. Supply file contents, not a URL or base64 data. Empty or malformed SRT returns 400 INVALID_REQUEST.

Cue times must fit within the source video. A job whose cues extend beyond the inspected duration fails with INVALID_SRT and releases its reserved credits. The SRT download preserves the supplied file contents. Rendered captions keep cue boundaries, with wrapping and splitting determined by the selected preset. Basic SRT formatting tags are removed from rendered text in favor of the preset’s styling. Since SRT has no word timings, animated captions and the JSON transcript use word timings estimated evenly within each cue.

Billing remains based on the video duration, rounded up to whole seconds.

Direct HTTPS URLs

The API downloads video_url from the processing server. The URL must:

• Use HTTPS on the standard port, with a public hostname.
• Return the video directly with HTTP 200 and no redirect.
• Be reachable without cookies or additional authorization headers.
• Contain no embedded username/password or URL fragment.
• Remain valid while the job is waiting and downloading.

Signed object-storage URLs are supported when they meet these requirements. Account for queue time when choosing their expiration.

URLs for local networks, localhost, private addresses, and custom ports are rejected. A YouTube page, a cloud-drive sharing page, or a login page is not a direct media URL.

Uploads

There is no public upload endpoint in this release. Upload your media to your own object storage, then provide its direct HTTPS URL.

Transcript format

The downloaded JSON transcript contains the full text and individual words:

{
  "text": "Make every word count.",
  "timestamp_unit": "seconds",
  "words": [
    { "text": "Make", "start": 0.12, "end": 0.4 },
    { "text": "every", "start": 0.42, "end": 0.75 },
    { "text": "word", "start": 0.78, "end": 1.08 },
    { "text": "count.", "start": 1.1, "end": 1.5 }
  ]
}

Times are measured in seconds, not milliseconds, from the start of the source video. The example timestamps above are illustrative.