YouTube transcript API for transcripts, subtitles and captions

Developer docs has the quickstart in curl, Python and Node, every endpoint with its parameters and response fields, what each job state means, and the errors. This page stays a summary on purpose.

Every endpoint requires a bearer token. Generate one on your API page and send it in the Authorization header.

Authorization: Bearer ytt_<your-token>

curl -X POST https://api.youtubetotext.ai/v1/api/transcribe \
  -H "Authorization: Bearer ytt_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "verbatim": false }'

curl https://api.youtubetotext.ai/v1/api/transcription/<id> \
  -H "Authorization: Bearer ytt_<your-token>"

When the state is "done", read the result field that matches the endpoint you called (see below). The same id works across all endpoints.

• POST/v1/api/transcribe

  Queue one video and get a job id back.

  Body: language_code, url*, verbatim

  Parameters and response

• GET/v1/api/transcription/{id}

  Read a job: its state while it runs, its text when it is done.

  Parameters and response

• POST/v1/api/subtitles

  Queue one video and get SRT and WebVTT cues back.

  Body: format, language_code, target_languages, url*, verbatim

  Parameters and response

• POST/v1/api/burn-subtitles

  Queue one video and get a video with the captions rendered into it.

  Body: background, font_size, language_code, quality, target_languages, url*, verbatim

  Parameters and response

Every endpoint above is described in openapi.json (OpenAPI 3.1). Import it into Postman, Insomnia or Bruno, or point a generator at it for a typed client in your own language. It is generated from the API and checked in with every release, so it stays in step with what the endpoints accept.

curl -O https://youtubetotext.ai/openapi.json

1. POST to the matching endpoint with the YouTube URL → store the returned id.
2. Poll GET /v1/api/transcription/{id} every 2 to 3 seconds. Show state and progress (0 to 100) in your UI.
3. When state is "done", read the result field for the mode you used:
   • transcribe → txt
   • subtitles → srt or webvtt
   • burn-subtitles → burned_video_url
4. If state is "failed", show error.

• 401: the token is missing, malformed or revoked. Send Authorization: Bearer ytt_<your-token>. Create or replace the token at /account/api/.
• 404: no job or batch with that id on your account. Check the id came from a queue call made with the same token.
• 422: the body did not validate. `detail` is an array, one entry per field, each naming the field in `loc`.
• 429: too many requests. Back off and retry. Polling every 2 to 3 seconds stays well under it.

• verbatim: true keeps filler words and exact phrasing. The default trims them.
• A bad URL, a private video or an empty minute balance is not an HTTP error. The POST still answers 200 with an id; the job then ends with state: "failed" and a human-readable error. Only a malformed request answers before queueing: a missing url or an unknown value gives 422 with a detail array, one entry per field. A missing or invalid token answers 401.
• The same id works across all endpoints. The job started by POST /transcribe is fetched by the same GET /transcription/{id}.

Running into issues? Or do you have a question or a feature idea? Reach us through the contact page and we'll get back to you.