Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Referência da API

YouTube Captions API

Obtenha uma chave de API

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

Monte uma requisição

O ID de 11 caracteres da URL do vídeo, não a URL completa.

Deixe em branco para tentar en-orig e depois en, retornando uma faixa. Ou digite de um a 10 códigos diferentes, separados por vírgulas.

Legenda auto
POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
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, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
Resultados na resposta HTTPX-API-Key autenticação

Parâmetros

Enviar source e.. video_id no nível superior. As opções de origem pertencem a params. Campos opcionais podem ser omitidos.

Corpo da requisição

sourcestring / Obrigatório
Preparar para youtube_captions.
video_idstring / Obrigatório
O 11-caracter YouTube vídeo ID, como FUfGcZ092b0. Aceita letras, números, sublinhados e hífens.
Exatamente 11 personagensPredefinição: Não está pronto
Formato aceito^[A-Za-z0-9_-]{11}$
paramsobject / Opcional
Settings para este pedido.
Predefinição: {}
callback_urlstring · nullable / Opcional
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.
Predefinição: Não está pronto

Selecção de legendas

params.languagestring | array / Opcional
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.
Predefinição: en-orig → en
params.autoboolean / Opcional
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.
true ou falsePredefinição: false

Resposta

Realtime retorna status: done. Leia a saída da fonte em results[0]; usage.credits Registra a acusação.

Leia os segmentos para o texto da legenda com start/end vezes em segundos e fullText para texto unido. languageCode e... isAutoGenerated Relate a trilha selecionada.

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
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))

Omita a linguagem do que prefere en-orig e volte para en, devolvendo uma faixa. Com o auto=true, cada código solicitado prefere sua faixa -orig, em seguida, o código simples; explícito -orig e auto=false permanecer exato. languageCode identifica a faixa selecionada, requestedLanguageCode está incluído quando difere.

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.

Auto defaults para false para legendas fornecidas pelo uploader. Defina true para legendas automáticas. O API nunca muda as fontes de legenda.

O API lê as legendas existentes do YouTube; não gera novas transcrições. A resposta padrão contém segmentos normalizados de JSON; Accept pode selecionar texto simples e X-Respond-With: marcação seleciona Markdown. languageName pode ser null; timings de segmento são preservados.

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.

Requisição
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
results[0]
{
  "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"
    }
  ]
}
Todos os campos de resposta
CampoDescrição
sourcestringA fonte API solicitada.
statusstringFeito quando o pedido em tempo real for bem sucedido.
created_atstringTempo de criação de resposta no formato ISO 8601.
usage.creditsnumberCréditos cobrados pelo pedido, baseado no seu plano.
results[0].videoIdstringO vídeo solicitado ID.
results[0].languageCodestringCódigo de faixa de legenda selecionado, como en-orig.
results[0].languageNamestring · nullableO nome da linguagem quando disponível.
results[0].requestedLanguageCodestring · optionalO código solicitado quando difere do languageCode, por exemplo, quando o en-orig foi selecionado.
results[0].isAutoGeneratedbooleanSe as legendas selecionadas foram geradas automaticamente.
results[0].segmentsarraySegmentos de legenda em ordem cronológica.
results[0].segments[].startnumberSegmento começa em segundos.
results[0].segments[].endnumberSegmento termina em segundos.
results[0].segments[].textstringMensagem de legenda.
results[0].fullTextstringTodo o texto se juntou a uma transcrição.
results[0].tracksarray · optionalSó para as linguagens. Faixas disponíveis em ordem de pedido, cada uma tem os campos de trilha única listados acima.
results[0].errorsarray · optionalSó para as linguagens. Linguagens falhadas em ordem de pedido. Vazio quando todas as pistas têm sucesso.
results[0].errors[].languageCodestringO idioma solicitado que falhou.
results[0].errors[].codestringlanguage_unavailable quando a faixa selecionada não existe, retrieval_failed quando não pode ser baixado ou analisado.
results[0].errors[].messagestringDescrição da falha na linguagem.

Os campos acima descrevem a resposta padrão JSON. JSON, texto simples e formatos Markdown.

Async retorna um recibo de trabalho; lote retorna um por VÍDEO ID. Verifique o status de cada trabalho e recupere seus resultados usando os links devolvidos.

Async & ciclo de vida em lote

A submissão devolve um recibo, não resultados. Async cria um trabalho; lote retorna um trabalho separado em queries[] para cada consulta aceita. Rastreie e recupere cada trabalho independentemente.

Submeta-se a data.flashdata.dev; ler status de trabalho e resultados de api.flashdata.dev com o mesmo X-API-Key. Os exemplos básicos do API ligados usam Python e cURL.

  1. 1. Salve o trabalho IDs

    Mantenha os campos de solicitação desta fonte ao mudar para Async. Para Batch, coloque cada pedido dentro da matriz de consultas de um objeto JSON. Salve todos os trabalhos devolvidos ID.

    Async pedido e recibo · Batch solicita corpo

  2. 2. Verifique o status

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing: pesquisa com um atraso e respeito Retry-After quando presente. completed: obter resultados. failed: Inspecione job.error.

    Leia job.status, não o status do recibo de submissão.

    Verifique o status de Python e cURL

    Situação do trabalho referência API
  3. 3. Recupere os resultados

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    Após a conclusão, autentique o resultado lido, e depois vá buscar o 302 de armazenamento URL sem sua chave API. Salve o JSON dentro de 24 horas de conclusão.

    Obter resultados · Python e cURL · Formatos de resposta

    Resultado do download da referência API

Pesquisando e buscando resultados existentes não consomem créditos de consulta. Um tempo de votação não cancela o trabalho: mantenha seu ID em vez de enviar duplicado trabalho billable. Códigos de erro e comportamento de repetição.

Webhooks de conclusão

Inscreva-se por consulta

Preparar callback_url no nível superior de um pedido de assincronização, ou dentro de cada consulta em um lote, fora params. Não é necessário nenhum pedido de registro separado. Pedidos Realtime não enviam chamadas de volta.

Use um HTTPS URL público no porto 443. FlashData POSTS uma notificação para cada trabalho chegando completed ou failed; O evento contém links, não o resultado em si.

Reconheça e verifique

Retorne 2xx depois de aceitar o evento. Deduplicar por delivery_id, também enviado como X-Delivery-Id. Redirecionamentos não são seguidos.

Entregas falhadas tentam novamente com retrocesso exponencial, até 8 tenta total e no máximo 24 horas após a conclusão. Continue pesquisando como um retrocesso.

As chamadas não foram assinadas. Confirme o trabalho ID, fonte e status terminal através do Endpoint de status autenticado Antes de processar a notificação. A entrega ID é para deduplicação, não prova de autenticidade.

Exemplo de eventos webhook e campos
Notificação de conclusão ilustrativa
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "youtube_captions",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
      "method": "GET"
    }
  ]
}
CampoDescrição
delivery_idstringIdentificador de entrega estável. Deduplicar notificações usando este valor; também é enviado no cabeçalho X-Delivery-Id.
idstringTrabalho ID.
sourcestringSolicitamos fonte de dados.
statusstringcompleto ou fracassado.
linksarrayStatus e links de resultados. Notificações não incluem conteúdo de resultado ou uma chave API.
links[].relstringauto ou resultados.
links[].hrefstringGestão absoluta API URL, autentice com sua chave API.
links[].methodstringGET.

Contrato completo e restrições URL

Processamento de arquivos Bulk

Envie um vídeo ID por linha e crie o trabalho Bulk com fonte: youtube_captions. Opções compartilhadas se aplicam a cada ID no arquivo.

Opções da fonte: Linguagem, auto. Coloque-os em opções ao criar o trabalho Bulk.

Recupere a coleção completa como um manifesto e comprimida por Gzip NDJSON. Fontes de dados também podem entregar peças de resultado para seu armazenamento na nuvem definindo options.result_storage ao criar o trabalho Bulk. Guarde o manifesto e partes dentro de 24 horas após o trabalho Bulk completo.

Bulk processamento API · Python e cURL · Batch JSON pedidos

Construir um fluxo de trabalho Bulk para esta fonte · Pausa, retoma e recupera

Recuperação de erros

Um vídeo pode ter legendas automáticas, mas nenhuma pista manual, ou falta a sua linguagem solicitada. Verifique a disponibilidade de legendas usando Metadados e escolha o idioma e a origem deliberadamente antes de uma nova submissão.

Verifique os idiomas de legenda disponíveis com metadados. Um novo pedido usa créditos de consulta, mudar uma faixa não modifica um trabalho existente.

Para autenticação, equilíbrio, formatação de pedidos e falhas de taxa, use a referência de erro compartilhado. Um intervalo de submissão ainda pode ter criado um trabalho, verificar o trabalho existente antes de tentar novamente.

Erros e códigos de status · Quando tentar novamente · Limites de taxa

Guia passo-a-passo: Recupere as legendas dos horários

Preços

PlanosTaxas de usopor 1.000 solicitações padrãoAssinaturasIncluindo créditos por período de faturamento
Pague pelo usoUS$ 0,50Sem mensalidadeRecarregue quando precisar
MicroUS$ 0,40US$ 49,00 / Mês1.000 créditos (US$ 50,00 de API uso) incluído
StarterUS$ 0,35US$ 199,00 / Mês4.000 créditos (US$ 200,00 de API uso) incluído
ProUS$ 0,30US$ 499,00 / Mês10.000 créditos (US$ 500,00 de API uso) incluído
ScaleUS$ 0,25US$ 999,00 / Mês20.000 créditos (US$ 1.000,00 de API uso) incluído
BusinessUS$ 0,20US$ 1.999,00 / Mês40.000 créditos (US$ 2.000,00 de API uso) incluído

Um plano por conta. Créditos compartilhados entre os três produtos. O uso coberto pelos créditos incluídos não é cobrado novamente.

Preços atuais e limites do plano