Un vídeo puede tener capciones automáticas inglesas, una pista española proporcionada por su subidor, tanto o ninguno. Pedir un idioma no crea una pista que el vídeo no tiene. Esta guía hace explícita la opción de captura y muestra cómo guardar la pista seleccionada sin sustituir silenciosamente otra fuente de idioma o de capción.
Subtítulos automáticos y subtítulos proporcionados por subidores
FlashData expone dos fuentes convenientes: youtube_transcript predeterminados a las subtítulos automáticos, mientras youtube_captions predeterminados para subidor-provided captions. Ambos soportan un explícito params.auto valor: true selecciona las tapas automáticas y false selecciona subidor-provided captions. Ambos recuperan las subtítulos YouTube existentes y los segmentos de tiempo de retorno.
Set params.language a la pista que necesita, por ejemplo en, es o en-US. Un código regional y un código sólo para el lenguaje no son promesas intercambiables. Si la fuente de idioma y la fuente de la capción solicitada no están disponibles, la solicitud puede fallar o no tener texto usable. El API no traduce automáticamente, genera discurso a texto, o retrocede entre fuentes de pista.
Elija una pista antes de enviar la solicitud
Use Node.js 22 o más tarde y un Clave API con créditos disponibles. Establecer un vídeo ID se le permite procesar. Para el flujo de trabajo básico de exportación de texto, vea Obtener YouTube subtítulos con JavaScript.
export FLASHDATA_API_KEY='your-api-key'
export YOUTUBE_VIDEO_ID='your-video-id'
export CAPTION_LANGUAGE='en'
export CAPTION_AUTO='true'
Uso CAPTION_AUTO=false para pedir una pista proporcionada por el cargador. El script envía exactamente una solicitud. No prueba cada idioma o emite una segunda solicitud pagada automáticamente cuando el primero falla.
Trae la pista elegida y mantenga los horarios
Guardar el siguiente código como caption-track.mjsvalida la opción de entrada, comprueba los errores de nivel de herramientas, así como los fallos de HTTP, y preserva la información de idioma y fuente notificada en la respuesta.
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
Qué hacer cuando la pista solicitada no esté
Comprueba el error antes de cambiar la configuración de la capción. Una clave inválida, créditos insuficientes o un timeout no es evidencia de que el vídeo carece de subtítulos.
Si ya buscas metadatos de vídeo, inspecciona
hasTranscriptsytranscriptLanguagescomo señales útiles. Un lenguaje reportado no garantiza que existan tanto pistas automáticas como suministradas por subscriptores en ese idioma.Si una pista alternativa es aceptable para su caso de uso, elija deliberadamente y haga una solicitud separada. Grabar el idioma solicitado y devuelto y
isAutoGeneratedvalor con el texto.Si su flujo de trabajo requiere la pista exacta, marque el artículo no disponible y continúe con otros vídeos. Repetidamente el envío de la misma solicitud no creará subtítulos perdidos.
Mantenga el lenguaje y la procedencia de los tiempos con su texto
Los segmentos contienen start, end y text; los tiempos se miden en segundos. Mantenga el vídeo ID y el idioma al dividir una transcripción en pedazos de búsqueda. Un enlace de vídeo con imágenes temporales puede ayudar a un lector a verificar el contexto original. Evite tratar un segmento de la capción como una nueva transcripción que su aplicación produjo.
Las subtítulos automáticos pueden contener errores de reconocimiento. Si utiliza el texto para resúmenes o citas, proporciona una manera de inspeccionar el segmento y el vídeo originales. La disponibilidad y la precisión son preguntas separadas: recuperar una pista no garantiza que su redacción sea correcta.
Comparen el Transcript API y Cápsulas API, o explorar API de datos YouTube.