Skip to main content
POST
Create a captioned video
Requires subtitles:write. Submit a direct HTTPS video URL and poll the returned status_url every five seconds. Choose any of the 16 presets and optionally override typography, layout, background, outline, shadow, and applicable highlight colors through style. Omitted fields inherit the preset, including fields within nested objects. Caption styles explains all controls and preset-specific behavior.
Creating a job reserves max_duration_seconds. This limit does not trim the video. Successful jobs are billed for actual duration rounded up; failed and canceled jobs release the reservation.
See Quickstart for a full submission and download example, and Media requirements for accepted sources.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Reuse with the same input to retry safely. Different input with the same key returns 409.

Required string length: 8 - 128
Pattern: ^[A-Za-z0-9._:-]{8,128}$

Body

application/json
video_url
string<uri>
required

Direct HTTPS MP4, MOV, or WebM URL. No redirects or extra auth headers. Maximum 500 MiB; must remain valid until downloaded.

Maximum string length: 4096
Example:

"https://your-cdn.example/video.mp4"

preset
enum<string>
default:classic

Caption preset. Omitted style properties use this preset's defaults.

Available options:
classic,
highlight,
smash,
box,
push,
elegant,
ogre,
outline,
paper-ink,
action,
prompter,
storytelling,
karaoke,
glow,
thin&bold,
background
language
string

Optional lowercase two- or three-letter language code supported by transcription. Omit for automatic language detection. Does not translate.

Pattern: ^[a-z]{2,3}$
Example:

"en"

max_duration_seconds
integer
default:60

Hard duration limit and initial prepaid reservation. Does not trim the video. Actual duration must fit this limit.

Required range: 1 <= x <= 600
style
object

Optional caption style overrides. Omitted fields (including nested fields) inherit the selected preset. GET /v1/presets lists defaults, supported controls and preset-specific behavior.

Response

Accepted; poll status_url every five seconds

id
string
required
status
string
required
status_url
string<uri>
required
replayed
boolean