API overview
Create subtitles from your own systems with the Subtitle AI Job API.
The Job API lets a script, a watch folder or another system turn media into subtitles without opening the web app. You create a job, upload the media, wait until it is ready, then download the transcript or a subtitle file.
Every job is an ordinary project in your organization. Your team sees it in the project list, and anyone can open it in the editor to review it. Their edits show up in later API responses.
At a glance
| Base URL | https://app.subtitle.ai/api/v1 |
| Authentication | Authorization: Bearer sk_live_… with an API key |
| Rate limit | 120 requests per minute for each key |
| Format | JSON, except transcript text and subtitle file downloads |
| Caching | Responses are never cached |
How it works
- An organization owner or admin creates an API key. It is shown once.
POST /jobswith the file's name, type, size and duration. You get a job id and an upload URL.PUTthe file to the upload URL. The upload starts transcription.GET /jobs/{id}untilstatusisready.GET /jobs/{id}/subtitlesfor a subtitle file, or/transcriptfor the text.
The quickstart walks through all of it with working code.
Endpoints
| Method and path | Purpose |
|---|---|
POST /jobs | Create a job and get an upload URL. |
GET /jobs/{id} | Job status, media details and the list of transcripts. |
GET /jobs/{id}/transcript | The transcript as JSON cues or plain text. |
GET /jobs/{id}/subtitles | The transcript as a subtitle file. |
OpenAPI
The machine-readable contract is an OpenAPI 3.1 file: download openapi.yaml. Use it to generate a client or to import the API into Postman or Insomnia.
Not available yet
These are not part of the API today:
- Starting translations and clean versions. You can read them, but you create them in the editor.
- Word, PDF and plain-text document exports.
- Webhooks. Poll the job instead.
- Keys limited to read-only or submit-only access. Every key has full access to its organization.
- Importing media from a URL (
sourceUrl). Upload the file instead.
Errors, limits and billing explains what to expect when something goes wrong, and what a job costs.