# FlashData YouTube Captions API

Recupere as legendas YouTube como texto com data e uma transcrição completa. Legendas fornecidas pelo carregador são selecionadas por padrão.

Referência canônica: https://flashdata.dev/pt/docs/sources/youtube_captions
Revisado: 2026-10-23

Ponto final: POST https://data.flashdata.dev/v1/queries/realtime
Autenticação: X-API-Key: YOUR_API_KEY
Modos: [Realtime](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md)

Precisou de permissão de origem: youtube_captions

Substitua YOUR_API_KEY por uma chave API que tem essa permissão de fonte e créditos disponíveis. Execute pedidos no seu servidor ou host de agente.

[Configurar autenticação](https://flashdata.dev/pt/docs/guides/headers-and-authentication/reference.md)

[Recupere as legendas dos horários](https://flashdata.dev/pt/docs/guides/timestamped-captions-recipe/reference.md)

<a id="quickstart"></a>

## Envie um pedido

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_captions",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": False,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_captions",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": false
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parâmetros

<a id="parameters-group-0"></a>

### Corpo da requisição

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Sim | — | Preparar para youtube_captions.  |
| <a id="parameter-video_id"></a> video_id | string | Sim | Não está pronto | O 11-caracter YouTube vídeo ID, como FUfGcZ092b0. Aceita letras, números, sublinhados e hífens. Comprimento mínimo: 11. Comprimento máximo: 11. Padrão: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Não | {} | Settings para este pedido.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Não | Não está pronto | Async e apenas lote. HTTPS conclusão URL na porta 443, até caracteres 2,048. Sem credenciais de usuário ou fragmento URL. Omit, use null ou uma string vazia para nenhuma notificação. Em um lote, coloque isso em cada consulta, fora dos parâmetros.  |

<a id="parameters-group-1"></a>

### Selecção de legendas

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | Não | en-orig → en | Omita para o inglês (en-orig, então en). Com auto=true, cada código tenta sua faixa de origem primeiro, depois o código solicitado. Códigos de origem explícitos e auto=false permanecem exatos. Arrays pedem 1–10 línguas distintas. Omita preferir en-orig e volte para en, devolvendo uma pista. Com auto=true, cada código tenta sua faixa de origem primeiro, depois o código solicitado; códigos de origem explícitos e auto=false permanecem exatos. Arrays de 1–10 Códigos distintos tentam cada idioma solicitado e retornam faixas e erros por idioma em ordem de solicitação. languageCode identifica a faixa selecionada; requestedLanguageCode está incluído quando difere do código solicitado. |
| <a id="parameter-params-auto"></a> params.auto | boolean | Não | false | true seleciona legendas geradas por YouTube; false seleciona legendas fornecidas por uploaders. Isso seleciona a origem da legenda, não a detecção de linguagem ou nova transcrição.  |

<a id="response"></a>

## Leia o resultado

Salve a resposta JSON bem sucedida como response.json. Guarde isso como read-response.py e execute python read-response.py. Ele usa apenas a biblioteca padrão do Python e não faz nenhum novo pedido.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Exemplo de resposta

Exemplo gravado; campos e conta depende da fonte e entrada solicitada.
```json
{
  "source": "youtube_captions",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 1.36,
          "end": 3.04,
          "text": "[♪♪♪]"
        },
        {
          "start": 18.64,
          "end": 21.880000000000003,
          "text": "♪ We're no strangers to love ♪"
        },
        {
          "start": 22.64,
          "end": 26.96,
          "text": "♪ You know the rules\nand so do I ♪"
        },
        {
          "start": 27.04,
          "end": 31.04,
          "text": "♪ A full commitment's\nwhat I'm thinking of ♪"
        },
        {
          "start": 31.12,
          "end": 35.08,
          "text": "♪ You wouldn't get this\nfrom any other guy ♪"
        },
        {
          "start": 35.16,
          "end": 39.52,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 40.52,
          "end": 42.92,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 43,
          "end": 45.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 45.2,
          "end": 47.080000000000005,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 47.32,
          "end": 51.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 51.48,
          "end": 53.48,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 53.6,
          "end": 55.52,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 55.72,
          "end": 59.36,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 60.8,
          "end": 64.8,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 64.88,
          "end": 69.03999999999999,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 69.12,
          "end": 72.96000000000001,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 73.36,
          "end": 77.2,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 77.4,
          "end": 82.04,
          "text": "♪ And if you ask me\nhow I'm feeling ♪"
        },
        {
          "start": 82.4,
          "end": 85.24000000000001,
          "text": "♪ Don't tell me\nyou're too blind to see ♪"
        },
        {
          "start": 85.32,
          "end": 87.27999999999999,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 87.36,
          "end": 89.32,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 89.44,
          "end": 93.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 93.8,
          "end": 95.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 95.76,
          "end": 98,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 98.08,
          "end": 102.04,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 102.2,
          "end": 104.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 104.28,
          "end": 106.36,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 106.48,
          "end": 110.08,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 110.76,
          "end": 112.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 112.8,
          "end": 114.68,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 114.96,
          "end": 118.76,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 119.84,
          "end": 122.96,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 123.72,
          "end": 127.36,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 128.48,
          "end": 130.11999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 130.24,
          "end": 131.56,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 132.48,
          "end": 134.23999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 134.36,
          "end": 135.92000000000002,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 136.76,
          "end": 141.07999999999998,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 141.2,
          "end": 145.2,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 145.28,
          "end": 149.12,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 149.52,
          "end": 153.20000000000002,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 153.36,
          "end": 158.04000000000002,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 158.64,
          "end": 161.32,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 161.4,
          "end": 163.36,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 163.44,
          "end": 165.64,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 165.72,
          "end": 169.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 169.8,
          "end": 171.64,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 171.8,
          "end": 173.96,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 174.04,
          "end": 177.6,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 178.2,
          "end": 180.24,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 180.32,
          "end": 182.44,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 182.52,
          "end": 186.64,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 186.72,
          "end": 188.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 188.84,
          "end": 190.72,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 190.84,
          "end": 195.2,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 195.28,
          "end": 197.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 197.2,
          "end": 199.24,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 199.4,
          "end": 203.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 203.36,
          "end": 205.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 205.68,
          "end": 207.84,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 207.92,
          "end": 211.32,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        }
      ],
      "fullText": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules\nand so do I ♪ ♪ A full commitment's\nwhat I'm thinking of ♪ ♪ You wouldn't get this\nfrom any other guy ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ And if you ask me\nhow I'm feeling ♪ ♪ Don't tell me\nyou're too blind to see ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ (Ooh, give you up) ♪ ♪ (Ooh, give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪"
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:46.290Z"
}
```

## Múltiplos idiomas

Envie uma lista de idiomas para receber faixas e erros por idioma. Este exemplo mostra inglês disponível e espanhol indisponível.

```json
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": false,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Uploader-provided subtitles not available for language: es"
    }
  ]
}
```

## Campos de resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| source | string | A fonte API solicitada. |
| status | string | Feito quando o pedido em tempo real for bem sucedido. |
| created_at | string | Tempo de criação de resposta no formato ISO 8601. |
| usage.credits | number | Créditos cobrados pelo pedido, baseado no seu plano. |
| results[0].videoId | string | O vídeo solicitado ID. |
| results[0].languageCode | string | Código de faixa de legenda selecionado, como en-orig. |
| results[0].languageName | string · nullable | O nome da linguagem quando disponível. |
| results[0].requestedLanguageCode | string · optional | O código solicitado quando difere do languageCode, por exemplo, quando o en-orig foi selecionado. |
| results[0].isAutoGenerated | boolean | Se as legendas selecionadas foram geradas automaticamente. |
| results[0].segments | array | Segmentos de legenda em ordem cronológica. |
| results[0].segments[].start | number | Segmento começa em segundos. |
| results[0].segments[].end | number | Segmento termina em segundos. |
| results[0].segments[].text | string | Mensagem de legenda. |
| results[0].fullText | string | Todo o texto se juntou a uma transcrição. |
| results[0].tracks | array · optional | Só para as linguagens. Faixas disponíveis em ordem de pedido, cada uma tem os campos de trilha única listados acima. |
| results[0].errors | array · optional | Só para as linguagens. Linguagens falhadas em ordem de pedido. Vazio quando todas as pistas têm sucesso. |
| results[0].errors[].languageCode | string | O idioma solicitado que falhou. |
| results[0].errors[].code | string | language_unavailable quando a faixa selecionada não existe, retrieval_failed quando não pode ser baixado ou analisado. |
| results[0].errors[].message | string | Descrição da falha na linguagem. |

- O API lê legendas já disponíveis no YouTube. Não gera novas transcrições ou se encaixam entre legendas automáticas e fornecidas pelo uploader.
- Uma linguagem de cordas mantém a resposta de uma única faixa. Um array, mesmo ["en"], retorna faixas e erros em vez de languageCode de nível superior, segmentos e fullText. Cada faixa inclui esses campos. Auto se aplica a cada idioma.
- Para listas de idiomas, consulte errors para identificar as faixas que falharam. Se nenhuma faixa for obtida, a solicitação falha e os créditos reservados são devolvidos. Uma falha na extração do vídeo ou o fim do prazo também faz a solicitação falhar.
- Disponível em tempo real, sincronia, lote e massa. Bulk exportações ficar JSONL com um registro por vídeo, incluindo suas faixas e erros. Accept e X-Respond-With se aplicam como de costume.

## Formatos de resposta

Respostas usam JSON por padrão. Escolha outro formato com esses cabeçalhos opcionais.

- Accept: application/json (padrão) ou text/plain. Texto simples apresenta os mesmos campos em um layout legível e indentado.
- X-Respond-With: markdown. Deixe de lado os campos originais. Markdown funciona com qualquer formato de resposta.

Markdown está disponível para consultas em tempo real e resultados completos.

Os campos abaixo descrevem a resposta padrão JSON.

[Requisito e formatação de resposta exemplos](https://flashdata.dev/pt/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Conceitos básicos da API

O construtor de pedidos e exemplos acima usam os parâmetros desta fonte. Use os exemplos Python e cURL abaixo para submissão compartilhada, status e passos de resultado. Um corpo Batch é um objeto JSON contendo consultas, cada item retorna seu próprio trabalho ID.

- [Async pedido e recibo](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Verifique o status do trabalho](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Recupere resultados completados](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON pedidos](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch)
- [API de processamento Bulk](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md)
- [Construir um fluxo de trabalho Bulk para esta fonte](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md?source=youtube_captions#playground)
- [Cliente OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notificações de conclusão

- [Receba e verifique os hooks de conclusão](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Solução de problemas

- [Erros e códigos de status](https://flashdata.dev/pt/docs/errors/reference.md#status-codes)
- [Quando tentar novamente](https://flashdata.dev/pt/docs/errors/reference.md#retries)

## APIs relacionadas

- [YouTube Transcript API](https://flashdata.dev/pt/docs/sources/youtube_transcript/reference.md)
- [YouTube Video Metadata API](https://flashdata.dev/pt/docs/sources/youtube_metadata/reference.md)
