Results
Download a finished job as a transcript or as a subtitle file.
Once a job is ready, fetch its text or a subtitle file. Both come from the same words the editor shows, so corrections made in the editor are included.
Choosing a transcript
A job can hold several transcripts: the original, a clean version and translations. Both endpoints below take the same two parameters to pick one.
| Parameter | Notes |
|---|---|
language | A language code, such as en. A clean version has the same code as its source, so this picks the original first, then the oldest. |
transcriptId | An id from transcripts[].id on the job. Use it to pick a clean version. It wins over language. |
Without either, you get the original.
Transcript
GET /jobs/{id}/transcript| Parameter | Values | Notes |
|---|---|---|
format | json (default) or text | Without format, an Accept: text/plain header selects text. |
maxChars | 1 to 1,000,000 | Caps the length, for a chat preview or a log line. |
language, transcriptId | Choose a transcript. |
JSON
Cues with word timings. Times are in seconds.
{
"jobId": "6a5f3c0e9b1d4e2a7c8b9d01",
"transcript": { "id": "6a5f…a1", "language": "nl", "kind": "original", "label": null, "status": "ready" },
"truncated": false,
"cueCount": 412,
"cues": [
{
"index": 1,
"start": 0.64,
"end": 3.2,
"speaker": 0,
"lines": ["Goedemorgen en welkom."],
"words": [
{ "text": "Goedemorgen", "start": 0.64, "end": 1.4 },
{ "text": "en", "start": 1.5, "end": 1.62 },
{ "text": "welkom.", "start": 1.7, "end": 3.2 }
]
}
]
}With maxChars, whole cues are kept, and always at least one. truncated says whether any were left out, and cueCount is always the full count.
Text
One cue per line, with a blank line where the speaker changes.
Goedemorgen en welkom.
Het weer is zonnig.
Dank je wel, Jan.With maxChars, the text is cut near a word boundary, and the response carries an X-Truncated: true header.
Word timings are the speech as detected. Subtitle lead-in never changes them.
Subtitle files
GET /jobs/{id}/subtitlesThe file arrives as an attachment named <job name>_<language>.<extension>.
| Parameter | Values | Notes |
|---|---|---|
format | srt (default), vtt, webvtt, ttml, ass, ebu-stl | |
offsetSeconds | −86,400 to 86,400 | Moves every cue by this many seconds. 36000 starts the first cue at a 10:00:00:00 programme timecode. EBU-STL ignores it, as in the editor. |
language, transcriptId | Choose a transcript. |
format | File | Content type |
|---|---|---|
srt | SubRip | application/x-subrip |
vtt, webvtt | WebVTT | text/vtt |
ttml | TTML | application/ttml+xml |
ass | Advanced SubStation Alpha | text/x-ssa |
ebu-stl | EBU-STL, binary | application/octet-stream |
Lead-in is not applied
If a project has subtitle lead-in, the editor's downloads show each subtitle earlier, but files from this endpoint do not. Otherwise the two files are identical. To shift every cue, use offsetSeconds.
Word, PDF and plain-text document exports are available in the editor only.
While the job is still running
A job that is not ready answers 409, whatever transcript you asked for, so a script that goes straight to /subtitles can simply retry.
code | Meaning | What to do |
|---|---|---|
job_not_ready | The job is still running. The response includes its status. | Keep polling. |
transcript_not_ready | A translation or clean version is still being created. | Keep polling. |
job_failed, transcript_failed | It failed. | Do not retry. |
Other errors are listed in Errors, limits and billing.