Docs
Queueing answers straight away with an id. Everything after that is one call, repeated.
curl https://api.youtubetotext.ai/v1/api/transcription/<job-id> \
-H "Authorization: Bearer ytt_<your-token>"Every 3 seconds, until state is one of done failed . A short video is usually finished within a few polls; a long one is split into parts and put back together, so it sits in processing and then merging for longer. There is a progress field to show someone while they wait.
| State | What it means |
|---|---|
waiting | Queued. Nothing has started yet. |
preparing | Working out what the video is and which parts to fetch. |
downloading | Pulling the audio. |
converting | Turning the audio into the format the engine takes. |
uploading | Handing the audio to the speech engine. |
processing | Being transcribed. The longest state on a long video. |
merging | Putting the parts of a long video back into one transcript. |
aligning | Timing the cues, for a subtitles job. |
translating | Producing the extra languages you asked for. |
burning | Rendering the captions into the video, for a burn-in job. |
donefinal | Finished. The text, the cues or the video are on the job. |
failedfinal | Stopped. `error` says why, and nothing was charged for it. |
Treat this list as open. A release can add a state, so branch on the two final ones and keep waiting through anything else.
The text is on txt, the cues on srt and webvtt, and a burn-in job puts its video on burned_video_url. Both cue formats are always filled for a subtitles job, so you can ask for one and use the other.
is_preview says the job covered only part of the video, and preview_minutes says how far it got. Extra languages arrive in translations, each with its own state out of pending, translating, burning, done, failed, so a translation can still be running when the transcript is done.
A job that stops with failed puts the reason on error and costs nothing. That failure arrives on the poll, not on the queue call, which answered 200 long before. Errors and status codes has the rest.