SubtoVTT
Sign in

Convert subtitles — endpoint reference

Subtitle conversion API reference: POST /api/v1/convert, every parameter, and code examples for Python, Node.js, PHP, Go, Ruby, Rust, JavaScript and cURL. v1 · stable

The core of the subtitle conversion API.

POST /api/v1/convert
Content-Type: multipart/form-data

Required fields

Field Type Description
file file Subtitle file, ≤ 5 MB. Extensions: .srt .vtt .ass .sbv .sub .stl
from string Source format: srt | vtt | ass | sbv | sub | stl
to string Target format: srt | vtt | ass | txt | sbv | sub | stl

Optional parameters

Parameter Type Default Notes
shift_ms int — Shift all timestamps in ms. Range −30000..30000. Negative = earlier.
frame_rate_from / frame_rate_to float — Source/target frame rate (e.g. 23.976, 25) for frame-rate rescale
casing string none none | upper | lower | title
max_line_length int — Wrap lines longer than N chars. Range 1..200
max_lines int — Maximum lines per cue. Range 1..10
merge_short_lines bool false Merge adjacent short lines into one cue
encoding string utf-8 utf-8 | utf-16 | latin-1
sub_fps float 25 Assumed FPS for .sub input timing
stl_fps float 25 Assumed FPS for .stl input timing
speed_percent int — Speed up/slow down timing. Range 1..1000
remove_duplicates bool false Drop near-identical consecutive cues
dup_similarity int 80 Similarity threshold for dedupe. Range 0..100
dup_proximity_ms int 500 Max time gap for cues to be considered duplicates. Range 0..5000
split_start_ms / split_end_ms int — Keep only cues inside the time range
clean_sdh bool false Strip SDH/CC text like [sound] and (applause)
remove_watermarks bool false Remove watermark/branding lines
fix_all_caps bool false Normalize ALL-CAPS cues to sentence case
position string — none | top | middle | bottom | remove — manages {\anN} positioning markers
two_point_t1 / t1p / t2 / t2p int — Two-point linear resync: original → should-be timestamps (ms)

Code examples

All examples use https://api.example.com and <key>. Replace both with your values.

Basic: SRT → VTT

cURL

curl -X POST https://api.example.com/api/v1/convert \
  -H "Authorization: Bearer <key>" \
  -F "[email protected]" \
  -F "from=srt" \
  -F "to=vtt" \
  -o movie.vtt

Full, runnable examples live on their own pages so you can grab the script for your stack:

Examples by language

  • Python — requests, reads response headers, writes output to file
  • Node.js — native fetch + FormData
  • PHP — cURL + CURLFile
  • Go — net/http + multipart
  • Ruby — net/http, manual multipart boundary
  • Rust — reqwest blocking
  • JavaScript (browser) — fetch + FormData + download
  • cURL — one-liner for bash, CI, cron

Examples by conversion

VTT → SRT with frame-rate rescale

curl -X POST https://api.example.com/api/v1/convert \
  -H "Authorization: Bearer <key>" \
  -F "[email protected]" \
  -F "from=vtt" \
  -F "to=srt" \
  -F "frame_rate_from=23.976" \
  -F "frame_rate_to=25" \
  -o movie.srt

Useful when captions timed for 23.976 fps content need to line up with 25 fps masters.

Cleanup pipeline

Clean SDH text, fix casing, wrap long lines, cap line count, merge short cues, and dedupe — all in one call:

curl -X POST https://api.example.com/api/v1/convert \
  -H "Authorization: Bearer <key>" \
  -F "[email protected]" \
  -F "from=vtt" \
  -F "to=vtt" \
  -F "casing=title" \
  -F "max_line_length=42" \
  -F "max_lines=2" \
  -F "merge_short_lines=true" \
  -F "clean_sdh=true" \
  -F "remove_duplicates=true" \
  -o captions-clean.vtt

Shift all timestamps

curl -X POST https://api.example.com/api/v1/convert \
  -H "Authorization: Bearer <key>" \
  -F "[email protected]" \
  -F "from=srt" \
  -F "to=srt" \
  -F "shift_ms=1500" \
  -o movie-delayed.srt

Positive delays subtitles, negative brings them earlier. For non-linear drift, use the two-point resync params (two_point_t1, t1p, t2, t2p).

Response & headers

A successful conversion (200) returns the subtitle text as an attachment:

Content-Disposition: attachment; filename="movie.vtt"
Content-Type: text/vtt
Header Meaning
X-Cue-Count Number of subtitle cues in the output
X-Avg-Cps Average characters per second across cues — a readability signal

The filename reflects the target format (e.g. movie.vtt, movie.srt). Save the body directly to a file and you're done.

Next

↑ Back to top