Auto Subtitle

Auto Subtitle transcribes a clip and burns word-timed captions into it. It is the only caption model that also returns word-level timings and a transcript.

Family captions · model auto-subtitle · catalog model-catalog@2026-10-06.v5 · pricing customer-pricing@2026-11-05.v15.

Endpoint

POST https://api.roasos.com/v1/captions/auto-subtitle

Send your API key as a bearer token. The key needs the scope api:write. Every paid request also needs an Idempotency-Key header.

The envelope fields quote_only, quote_id, webhook_url and wait_timeout_seconds behave the same on each model endpoint. Refer to Jobs and Quotes and credits.

Caption an ad in the punchy word-by-word style, and get the timings back so you can edit against them. Use this one when you will work with the words later; use VEED Subtitles when the render is the deliverable.

The price is $0.03 for each minute of the source clip, rounded up. There are no multipliers. The source must be 480 seconds or shorter.

Pricing

The unit is one source_minute. Pricing key: auto-subtitle.

Request	Credits
`30s_source`	1
`60s_source`	1
`120s_source`	1

The credits come from the roasOS pricing table. No other field changes the price. To get the exact price of your request, send it with quote_only: true first.

Modes

subtitle

Provider endpoints: fal-ai/workflow-utilities/auto-subtitle.

Request fields

Field	Type	Required	Default	Rule
`audio_url`	string	no	—	https URL; ≤ 4,096 characters
`background_color`	enum	no	—	`white`, `black`, `red`, `green`, `blue`, `yellow`, `orange`, `purple`, `pink`, `brown`, `gray`, `cyan`, `magenta`, `none`, `transparent`
`enable_animation`	boolean	no	—	—
`font_color`	enum	no	—	`white`, `black`, `red`, `green`, `blue`, `yellow`, `orange`, `purple`, `pink`, `brown`, `gray`, `cyan`, `magenta`
`font_name`	string	no	—	≥ 1 character; ≤ 64 characters
`font_size`	integer	no	—	20–150
`font_weight`	enum	no	—	`normal`, `bold`, `black`
`language`	string	no	—	≥ 2 characters; ≤ 35 characters
`position`	enum	no	—	`top`, `center`, `bottom`
`quote_id`	string	no	—	UUID
`quote_only`	boolean	no	`false`	—
`stroke_color`	enum	no	—	`white`, `black`, `red`, `green`, `blue`, `yellow`, `orange`, `purple`, `pink`, `brown`, `gray`, `cyan`, `magenta`
`stroke_width`	integer	no	—	0–10
`video_url`	string	no	—	https URL; ≤ 4,096 characters
`wait_timeout_seconds`	integer	no	`0`	0–60
`webhook_url`	string	no	—	https URL; ≤ 4,096 characters
`words_per_subtitle`	integer	no	—	1–12
`y_offset`	integer	no	—	-200–200

The schema is strict. A field that is not in this table gets 400 unsupported_option. The field names are the roasOS role names. One role has one name in every family.

Media

This endpoint accepts these media roles:

video_url — the source video
audio_url — the driving audio track

Role	Items	Maximum size	Content types	Duration
`video_url`	≤ 1	100 MB	`video/mp4`	0–480 s

Every other role is refused: avatar_id, elements, product_id, product_images, references, reference_images, image_url, end_image_url, scene_id, scene_image, video_urls, audio_urls, voice_id. A refused role gets 400 unsupported_option.

Each media URL must be an immutable object on https://cdn.roasos.com that your workspace owns. Any other URL gets 400 reference_media_not_workspace_owned. Refer to Reference media and uploads to learn how to put a file there.

Prompt

None. This model takes no prompt.

Every styling control is optional and none of them changes the price. words_per_subtitle is the one that changes the feel most: 1 for single-word display, 2 to 3 for short phrases, 8 to 12 for full sentences.

Not exposed

These catalog entries describe omitted inputs, pinned values and source constraints. They do not imply that the provider accepts every listed field.

background_opacity — not accepted by this public endpoint.
highlight_color — not accepted by this public endpoint.

Result

The result kind is video. Always present: url.

{
  "data": {
    "id": "gen_…",
    "kind": "video",
    "model": "auto-subtitle",
    "status": "completed",
    "result": {
      "url": "https://cdn.roasos.com/workspaces/ws_01/result"
    }
  }
}

The files are immutable objects on https://cdn.roasos.com. A result URL is a valid media input for your next request.

Example

The three steps are always the same: quote, run, poll.

# 1. Quote. Nothing is spent.
curl -X POST https://api.roasos.com/v1/captions/auto-subtitle \
  -H "Authorization: Bearer roasos_sk_live_..." \
  -H "Idempotency-Key: 0f1c9e2a-auto-subtitle-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_only":true,"video_url":"https://cdn.roasos.com/workspaces/ws_01/uploads/video_url.mp4"}'
# 200 { "data": { "kind": "quote", "quote_id": "q_7Hk...", "credits": 1, "expires_at": "...",
#        "confirmation": { "model": "auto-subtitle", "example": "30s_source" } } }

# 2. Run. Same body, same Idempotency-Key, quote_id in place of quote_only.
curl -X POST https://api.roasos.com/v1/captions/auto-subtitle \
  -H "Authorization: Bearer roasos_sk_live_..." \
  -H "Idempotency-Key: 0f1c9e2a-auto-subtitle-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q_7Hk...","video_url":"https://cdn.roasos.com/workspaces/ws_01/uploads/video_url.mp4"}'
# 201 { "data": { "id": "gen_...", "status": "queued", "credits_reserved": 1 } }

# 3. Poll, then read the result.
curl https://api.roasos.com/v1/jobs/gen_.../status -H "Authorization: Bearer roasos_sk_live_..."
curl https://api.roasos.com/v1/jobs/gen_.../result -H "Authorization: Bearer roasos_sk_live_..."

Today

The endpoint is POST /v1/captions/auto-subtitle.

It is live.