Guides

How to Choose Languages and Caption Tracks in a Transcript API

Published 2026-11-14 · TextFrom

A video can have more than one caption track. One track may be provided by its creator, another may be automatically generated, and a particular regional language code may be available when a broader code is not. If your application simply asks for “a transcript,” it can receive text that is technically valid but unsuitable for the person or workflow that requested it.

A safer approach is to express language preferences explicitly and inspect the returned track. This guide uses the TextFrom request format to illustrate that approach. It starts with existing captions: requesting an existing subtitle track is not the same as generating a new transcript from audio. Translation is a separate, optional step, covered in section 4.

1. Distinguish language from location and script

A language code can include a regional or script distinction. For example, en-US identifies a regional English variant, while en is a broader language code. Similarly, a workflow may care whether Chinese text is in simplified or traditional script. The exact tracks available depend on the individual video; do not assume that a video with one code also has a different one.

This difference affects user experience. If someone explicitly requests en-US, silently returning another track can make the result harder to evaluate. On the other hand, some applications are happy to accept a broader English track as a fallback. The important thing is that the caller makes the choice.

An issue in an open-source transcript library illustrates the problem: a user asked for a general language code while a manually created regional track was available. The library maintainer explained that automatically preferring one regional track over another would be a choice the caller should control. That discussion is an example, not a measurement of how frequently the issue occurs across services.

2. Send an ordered list of acceptable languages

lang is a comma-separated preference list. The API tries the entries in the order provided. In this example, en-US is first and en is second:

export TEXTFROM_API_KEY='YOUR_API_KEY'

curl -G 'https://api.textfrom.dev/v1/youtube/videos/VIDEO_ID/transcript' \
  -H "Authorization: Bearer $TEXTFROM_API_KEY" \
  --data-urlencode 'lang=en-US,en' \
  --data-urlencode 'kind=manual,auto' \
  --data-urlencode 'format=json'

Replace VIDEO_ID with an authorized video ID and set the key in your local environment. Never include your actual key in a published example. TextFrom does not substitute a language outside the caller's list. For a workflow that needs only one exact language code, send that code rather than a long preference list.

This contract is useful because it makes a product decision visible. A research app may accept both codes, while an editing tool may require a specific track. Neither choice is universally correct.

3. Know which caption track was delivered

The kind parameter can request manual or automatically generated captions. The example uses manual,auto, indicating that both are acceptable. The response identifies the actual choice in data.delivered.lang and data.delivered.kind; data.delivered.source is native for an existing track.

Here is a shortened real response for a public sample video (one segment shown; the request ID is elided):

{
  "data": {
    "requested": {"lang": ["en-US", "en"], "kind": ["manual", "auto"], "format": "json"},
    "delivered": {"lang": "en", "kind": "manual", "source": "native"},
    "segments": [
      {"start": 1.2, "end": 3.36, "text": "All right, so here we are, in front of the elephants"}
    ]
  },
  "meta": {
    "request_id": "…",
    "service": "youtube.transcript",
    "operation": "transcript",
    "billable": true,
    "units": 1
  }
}

The result is acceptable for the example request because en was explicitly listed. It also tells your application that the track was creator-provided (manual); an automatically generated one would say auto. If your task requires a creator-provided track, request the appropriate kind and handle the case where that kind is unavailable. Automatic captions can contain mistakes, and neither the API nor the track label proves that a transcript is accurate enough for legal, medical, or other high-stakes use.

If the source cannot identify the track type, preserve unknown rather than assuming that it was manually edited. A misleading quality label can be worse than no label at all.

4. Keep translation separate from the track you found

The fact that a video has English captions does not mean it has Spanish captions. If you want text in another language, ask for it explicitly with translate, and the response will say it is a translation:

curl -G 'https://api.textfrom.dev/v1/youtube/videos/VIDEO_ID/transcript' \
  -H "Authorization: Bearer $TEXTFROM_API_KEY" \
  --data-urlencode 'lang=en' \
  --data-urlencode 'translate=es'

TextFrom first fetches the existing track from lang, then runs a free machine translation into the target language. What to expect:

• data.delivered becomes {"lang": "es", "kind": "<original kind>", "source": "translated", "translated_from": "en", "segmentation": "merged"}. Check source before treating the text as human-written.
• segmentation: "merged" means the caption lines were merged into blocks of roughly 240 characters before translation, so segments are coarser than the original lines. Do not use them for word-level timing.
• It is machine translation: quality varies, and Chinese output can mix simplified and traditional characters, and it should not be used for legal, medical or other high-stakes text without review.
• Each translated request counts as one request plus one translation from a separate monthly translation allowance (100 per month on the free plan). Videos longer than about 10 minutes return translation_too_long; ask for the original language or a shorter video.
• If the track is already in the target language it is returned as is, and if translation fails you get an error, never the original text passed off as a translation.

Treat the steps separately in your own code: find the track you are permitted to use, record the actual language and kind, translate only when the user has chosen it, and keep the source language next to the translated result.

5. Treat an unavailable language as a decision point

The language_not_available error includes the video's tracks in error.details.available, each with lang and kind. When this happens, show a clear message or return the available choices to the application. If the user permits another language, send a new request with an explicit preference. Do not retry the identical request indefinitely and do not relabel source-language text as the requested language.

A temporary network or upstream error is a different category. For a 503 response, inspect error.retryable and any Retry-After header. Use a bounded retry policy and surface a useful result if the service cannot complete the request. A provider's empty response should not automatically be described as proof that a creator disabled captions.

6. Use track discovery when you need a choice

The tracks endpoint (GET /v1/youtube/videos/{id}/tracks) lists the caption tracks a video has, and transcript returns the text of the one you choose. Each track has a language code and a kind (manual, auto or unknown) and, where known, whether it can be translated. Unknown information stays unknown: do not assume every video reports every track type.

For an end user, the practical sequence is simple: choose the intended language and track policy, request the text, then display what was actually delivered. That makes the API's behavior auditable and reduces surprises in downstream search, AI, or editing workflows.

Next steps

Start with the TextFrom quickstart. Test one authorized video with one explicit language, then try a language that is not available and confirm that your application handles the result gracefully. Add fallback languages only when the user or your product requirements actually permit them.

Sources: TextFrom quickstart; language-code discussion; YouTube caption-track listing. Accessed 2026-11-14 PT.