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` `.ssa` `.sbv` `.sub` `.stl` `.lrc` `.smi` `.ttml` `.dfxp` `.itt`
`from`	string	Source format: `srt` \| `vtt` \| `ass` \| `ssa` \| `sbv` \| `sub` \| `stl` \| `lrc` \| `smi` \| `ttml` \| `dfxp` \| `itt`
`to`	string	Target format: `srt` \| `vtt` \| `ass` \| `ssa` \| `txt` \| `sbv` \| `sub` \| `stl` \| `lrc` \| `smi` \| `ttml` \| `dfxp` \| `itt`

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 "file=@movie.srt" \
  -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 "file=@movie.vtt" \
  -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 "file=@captions.vtt" \
  -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 "file=@movie.srt" \
  -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