Um vídeo pode ter legendas automáticas inglesas, uma faixa espanhola fornecida pelo upload, ambos, ou nenhum dos dois. Pedir uma linguagem não cria uma faixa que o vídeo não tenha. Este guia torna a escolha da legenda explícita e mostra como salvar a faixa selecionada sem substituir silenciosamente outra língua ou fonte da legenda.
Legendas automáticas e legendas fornecidas pelo uploader
FlashData expõe duas fontes convenientes: youtube_transcript padrão para legendas automáticas, enquanto youtube_captions O padrão é a legenda fornecida pelo uploader. Ambos apoiam um explícito params.auto Valor: true seleciona legendas automáticas e false seleciona legendas fornecidas pelo uploader. Ambos recuperam as legendas YouTube existentes e retornam segmentos com data de retorno.
Preparar params.language para a pista que você precisa, por exemplo en, es ou en-US. Um código regional e um código somente para linguagem não são promessas intercambiáveis. Se o idioma e a fonte de legenda não estiverem disponíveis, o pedido pode falhar ou não ter nenhum texto utilizável. O API não traduz automaticamente, gera discurso-texto, ou cai de volta entre as fontes da pista.
Escolha uma faixa antes de enviar o pedido
Use Node.js 22 ou mais tarde e um API chave Com créditos disponíveis. Defina um vídeo ID que você pode processar. Para o fluxo básico de exportação de texto, veja Obter YouTube legendas com JavaScript.
export FLASHDATA_API_KEY='your-api-key'
export YOUTUBE_VIDEO_ID='your-video-id'
export CAPTION_LANGUAGE='en'
export CAPTION_AUTO='true'
Use CAPTION_AUTO=false para pedir uma faixa fornecida pelo uploader. O roteiro envia exatamente um pedido. Ele não tenta cada idioma ou emitir um segundo pedido pago automaticamente quando o primeiro falha.
Pegue a faixa escolhida e mantenha as datas
Guarde o seguinte código como caption-track.mjs. Ele valida a escolha de entrada, verifica erros de nível de ferramenta, bem como falhas HTTP, e preserva a língua e informação de origem relatada na resposta.
import { writeFile } from "node:fs/promises";
const key = process.env.FLASHDATA_API_KEY;
const videoId = process.env.YOUTUBE_VIDEO_ID;
const language = process.env.CAPTION_LANGUAGE ?? "en";
const autoSetting = process.env.CAPTION_AUTO ?? "true";
if (!key || !/^[A-Za-z0-9_-]{11}$/.test(videoId ?? "")) {
throw new Error("Set FLASHDATA_API_KEY and an 11-character YOUTUBE_VIDEO_ID.");
}
if (!["true", "false"].includes(autoSetting)) {
throw new Error("CAPTION_AUTO must be true or false.");
}
if (!/^[A-Za-z0-9-]{1,35}$/.test(language)) {
throw new Error("Use a caption language code such as en or en-US.");
}
const auto = autoSetting === "true";
const source = auto ? "youtube_transcript" : "youtube_captions";
const response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
method: "POST",
headers: { "Content-Type": "application/json", "X-API-Key": key },
body: JSON.stringify({ source, video_id: videoId, params: { language, auto } }),
signal: AbortSignal.timeout(60000),
});
const payload = await response.json();
if (!response.ok || payload.error || payload.status !== "done") {
console.error(JSON.stringify({ httpStatus: response.status,
requestId: response.headers.get("x-request-id"),
detail: payload.detail ?? payload.message ?? payload.error }, null, 2));
throw new Error("Caption request failed. Inspect the error before trying another track.");
}
const track = payload.results?.[0];
if (!Array.isArray(track?.segments) || !track.segments.some(s => s.text?.trim())) {
throw new Error("No usable caption segments were returned for this selection.");
}
const saved = {
requested: { videoId, language, auto },
returned: { videoId: track.videoId, languageCode: track.languageCode,
isAutoGenerated: track.isAutoGenerated, segments: track.segments },
};
await writeFile("caption-track.json", JSON.stringify(saved, null, 2));
await writeFile("caption-track.txt", track.fullText || track.segments.map(s => s.text).join("\n"));
console.log(`Saved ${track.segments.length} segments from ${track.languageCode}`);
node caption-track.mjs
O que fazer quando a pista solicitada está faltando?
Verifique o erro antes de mudar as configurações de legenda. Uma chave inválida, créditos insuficientes ou um intervalo não é evidência de que o vídeo não tem legendas.
Se você já buscar metadados de vídeo, inspecione
hasTranscriptse..transcriptLanguagescomo sinais úteis. Uma linguagem relatada não garante que faixas automáticas e fornecidas por carregadores existam nessa língua.Se uma pista alternativa é aceitável para o seu caso de uso, escolha-a deliberadamente e faça um pedido separado. Grave o idioma solicitado e devolvido e
isAutoGeneratedValorize com o texto.Se seu fluxo de trabalho requer a faixa exata, marque o item indisponível e continue com outros vídeos. Repetidamente enviar o mesmo pedido não criará legendas perdidas.
Mantenha a linguagem e a origem da hora com seu texto
Segmentos contêm start, end e.. text; Os tempos são medidos em segundos. Mantenha o vídeo ID e linguagem ao dividir uma transcrição em pedaços de busca. Um link de vídeo cronometrado pode ajudar um leitor a verificar o contexto original. Evite tratar um segmento de legenda como uma nova transcrição que sua aplicação produziu.
Legendas automáticas podem conter erros de reconhecimento. Se você usar o texto para resumos ou citações, fornecer uma maneira de inspecionar o segmento original e vídeo. Disponibilidade e precisão são perguntas separadas: recuperar uma pista com sucesso não garante que sua redação esteja correta.
Compare o Transcrição API e.. Legendas API, ou explorar o YouTube APIs de dados.