REST API
Plain HTTP. Plain JSON.
No SDK. No client library. Five endpoints, three steps to subtitle a video. Works with curl, fetch, requests, net/http, or anything else that speaks HTTP.
Quickstart
Three requests. One subtitled video.
Presign, upload, poll. That's the whole API. Whisper does the heavy lifting in the background; you get a status update every step of the way.
# 1. Get a presigned upload URL
PRESIGN=$(curl -s -X POST https://brains.subtitlesking.com/presign \
-H "X-API-KEY: $SK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"clip.mp4"}')
URL=$(echo $PRESIGN | jq -r .uploadURL)
# 2. Upload your video
RESULT=$(curl -s -X POST "$URL" -F "file=@clip.mp4")
TOKEN=$(echo $RESULT | jq -r .authToken)
# 3. Poll for status
curl -s -X POST https://brains.subtitlesking.com/queue \
-H "Content-Type: application/json" \
-d "{\"authToken\":\"$TOKEN\"}"Endpoints
Five endpoints. That's the whole surface.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /presign | X-API-KEY | Returns a one-time presigned upload URL. Send the filename, get back a URL that lets you upload exactly one file. |
| POST | /upload | Presigned token (query) | Receives the multipart file upload. Returns video_id and an 8-digit auth_token. |
| POST | /queue | None | Pass an auth_token; get back current status, plus transcript_url and download_url when ready. |
| GET | /transcript | Presigned token (query) | Streams the SRT transcript. Available once status >= srt_generated. |
| GET | /download | Presigned token (query) | Streams the burned video. Available once status = subtitles_burned. |
Status states
Watch the pipeline live.
Poll /queue every 30 seconds and you'll see the status walk through each stage. The transcript is ready before the burned video.
newQueued for processing.compressingffmpeg downscaling for fast Whisper passes.compressedCompression done.generating_srtWhisper transcribing.srt_generatedTranscript ready — transcript_url populated in /queue response.burning_subtitlesffmpeg burning subtitles into the video.subtitles_burnedDone — download_url populated in /queue response.error_*Pipeline failed at the indicated step.
Auth
One header on /presign. Tokens for the rest.
API key
Send X-API-KEY with /presign. The default key works against the public free tier; higher limits require a Pro key (waitlist).
Presigned tokens
Upload, transcript, and download URLs are time-limited presigned links. Upload tokens are single-use; download tokens are valid for 24 hours.