Une vidéo peut proposer des sous-titres automatiques en anglais, une piste en espagnol fournie par le créateur, les deux ou aucune. Demander une langue ne crée pas une piste absente de la vidéo. Ce guide montre comment choisir explicitement une piste et l’enregistrer sans la remplacer silencieusement par une autre langue ou un autre type de sous-titres.
Sous-titres automatiques ou fournis par le créateur
FlashData propose deux sources : youtube_transcript sélectionne les sous-titres automatiques par défaut, tandis que youtube_captions sélectionne ceux du créateur. Les deux sources permettent de définir explicitement params.auto : true sélectionne les sous-titres automatiques et false sélectionne ceux fournis par le créateur. Les deux sources récupèrent les sous-titres YouTube existants et renvoient des segments horodatés.
Définissez params.language sur la langue de la piste souhaitée, par exemple en, es ou en-US. Un code régional et un code de langue seul ne sont pas nécessairement interchangeables. Si la langue et le type de sous-titres demandés sont indisponibles, la requête peut échouer ou ne renvoyer aucun texte exploitable. L’API ne traduit pas automatiquement le texte, ne transcrit pas l’audio et ne bascule pas vers un autre type de piste.
Choisir une piste avant d’envoyer la requête
Utilisez Node.js 22 ou une version ultérieure et une clé API associée à un compte disposant de crédits. Choisissez l’ID d’une vidéo que vous êtes autorisé à traiter. Pour un simple export de texte, consultez Récupérer des sous-titres YouTube avec JavaScript.
export FLASHDATA_API_KEY='your-api-key'
export YOUTUBE_VIDEO_ID='your-video-id'
export CAPTION_LANGUAGE='en'
export CAPTION_AUTO='true'
Utilisez CAPTION_AUTO=false pour demander une piste fournie par le créateur. Le script envoie une seule requête. Il ne teste pas toutes les langues et n’envoie pas automatiquement une seconde requête payante si la première échoue.
Récupérer la piste choisie avec ses horodatages
Enregistrez le code suivant dans caption-track.mjs. Le script valide les paramètres, vérifie les erreurs d’outil et les erreurs HTTP, puis conserve la langue et la provenance indiquées dans la réponse.
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
Que faire si la piste demandée est absente ?
Vérifiez l’erreur avant de modifier les paramètres des sous-titres. Une clé invalide, un solde de crédits insuffisant ou un délai dépassé ne prouve pas que la vidéo n’a pas de sous-titres.
Si vous récupérez déjà les métadonnées de la vidéo, consultez
hasTranscriptsettranscriptLanguagespour orienter votre choix. La présence d’une langue n’implique pas que des pistes automatiques et des pistes du créateur existent toutes deux dans cette langue.Si une autre piste convient à votre usage, choisissez-la explicitement et envoyez une requête distincte. Enregistrez la langue demandée, la langue renvoyée et la valeur de
isAutoGeneratedavec le texte.Si votre workflow exige cette piste précise, marquez la vidéo comme indisponible et passez aux autres. Répéter la même requête ne créera pas les sous-titres manquants.
Conserver la langue et les horodatages avec le texte
Les segments contiennent start, end et text ; les temps sont exprimés en secondes. Conservez l’ID de la vidéo et la langue lorsque vous découpez la transcription pour la recherche. Un lien vidéo horodaté permet de vérifier le contexte d’origine. Ne présentez pas un segment de sous-titres comme une transcription créée par votre application.
Les sous-titres automatiques peuvent contenir des erreurs de reconnaissance. Pour des résumés ou des citations, permettez au lecteur de consulter le segment et la vidéo d’origine. La disponibilité d’une piste et l’exactitude de son texte sont deux choses distinctes.
Comparez les API Transcript et Captions, ou découvrez les API YouTube Data.