YouTubeTranscriptionsGuide API

Comment télécharger des transcriptions YouTube à grande échelle avec une API

Un guide orienté production pour récupérer en masse le texte des transcriptions YouTube disponibles, gérer les langues et les sous-titres manquants, et préparer les résultats pour la recherche, le résumé ou le RAG.

SocQMis à jour le 19 juillet 202612 min de lecture

Télécharger à la main une transcription YouTube est facile. Construire un workflow fiable pour des centaines ou des milliers de vidéos publiques est un tout autre problème : des vidéos peuvent n’avoir aucun sous-titre, la langue demandée peut être indisponible, le texte généré automatiquement peut contenir des erreurs, et chaque résultat doit rester relié à sa source.

Ce guide montre comment récupérer le texte des transcriptions publiques YouTube disponibles avec la SocQ YouTube Transcripts API, traiter plusieurs URL de vidéos dans une tâche asynchrone et préparer les résultats normalisés pour la recherche, le résumé, l’analyse ou la génération augmentée par récupération (RAG).

Réponse rapide : envoyez des URL de vidéos YouTube publiques et, facultativement, une langue BCP-47 à POST /v1/youtube/transcripts. Conservez le task_id renvoyé, interrogez l’endpoint de la tâche et lisez les enregistrements terminés dans data.results.items. SocQ renvoie le texte brut de la transcription et le contexte de la vidéo lorsque des sous-titres publics exploitables sont disponibles. Il ne génère pas de nouvelle transcription vocale lorsque les sous-titres sont absents.

L’API YouTube officielle permet-elle de télécharger n’importe quelle transcription publique ?

Non. L’API YouTube Data officielle propose des ressources de sous-titres, mais sa méthode de téléchargement est conçue pour les pistes de sous-titres que l’utilisateur authentifié a le droit de gérer. La documentation actuelle de Google indique que captions.download exige une autorisation OAuth et que l’utilisateur doit avoir la permission de modifier la vidéo. La méthode coûte aussi 200 unités de quota par appel.

Cela fonctionne lorsque vous possédez ou gérez la chaîne. Cela ne fournit pas de moyen général de télécharger le texte des sous-titres de vidéos publiques quelconques. Consultez la documentation officielle de Google sur le téléchargement des sous-titres pour connaître les exigences d’autorisation.

Il est utile de distinguer trois cas d’usage :

ExigenceApproche adaptée
Gérer les sous-titres de vidéos que vous possédezAPI YouTube Data avec OAuth
Récupérer le texte de sous-titres déjà disponibles sur des vidéos publiques choisiesUn endpoint de transcription managé tel que SocQ
Transcrire l’audio lorsqu’il n’existe aucun sous-titreUn pipeline distinct de reconnaissance vocale (ASR)

SocQ couvre le deuxième cas. Il récupère le texte de transcription disponible ; il ne prétend pas que chaque vidéo publique possède une transcription et il ne substitue pas discrètement un texte ASR nouvellement généré.

Envoyer une requête de transcription YouTube

L’endpoint accepte une ou plusieurs URL de vidéos publiques. Vous pouvez aussi envoyer une langue préférée, comme en ou zh-CN.

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.youtube.com/watch?v=arj7oStGLkU"
    ],
    "language": "en"
  }'

L’envoi démarre une tâche asynchrone. Conservez le task_id renvoyé ; ne renvoyez pas le même lot simplement parce que le traitement n’est pas immédiat.

Interrogez la tâche jusqu’à ce qu’elle atteigne un état terminal :

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

queued et running sont des états intermédiaires normaux. Une fois la tâche réussie, lisez data.results.items. Si la page de résultats indique has_more: true, demandez la page suivante avec le next_cursor renvoyé.

Comprendre la réponse de transcription

Un enregistrement de transcription normalisé a une forme stable, qui peut être stockée sans analyser une page YouTube :

{
  "id": "arj7oStGLkU",
  "platform": "youtube",
  "resource": "transcripts",
  "type": "transcript",
  "url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "text": "A plain-text transcript snapshot.",
  "language": "en",
  "available_languages": ["en"],
  "format": "plaintext",
  "transcript_source": "auto_generated",
  "author": {
    "id": "UCAuUUnT6oDeKwE6v1NGQxug",
    "username": "TED",
    "name": "TED",
    "url": "https://www.youtube.com/@TED"
  },
  "created_at": "2016-04-06T00:00:00",
  "collected_at": "2026-07-16T08:00:00Z",
  "extra": {
    "duration_seconds": 843
  }
}

Les champs les plus importants en aval sont :

  • text : la transcription sélectionnée, en texte brut.
  • language : la langue réellement renvoyée, qui peut différer de la préférence.
  • available_languages : les langues de transcription non vides trouvées pour la vidéo.
  • transcript_source : la classification de la source des sous-titres lorsqu’elle est connue.
  • id, url, title et author : le contexte de la source, pour la traçabilité.
  • created_at et collected_at : les dates de publication et de collecte.
  • extra.duration_seconds : utile pour les contrôles de qualité et les estimations de charge.

La réponse est volontairement en texte brut. Elle ne contient pas d’horodatages de segments fiables ni d’étiquettes de locuteurs. N’inventez pas d’horaires précis de citation et ne convertissez pas la réponse en SRT comme si des données d’horodatage existaient.

Récupérer les transcriptions dans la bonne langue

La langue de la requête est une préférence, pas une garantie. Un workflow de production doit toujours router d’après la valeur renvoyée dans language.

Par exemple, si vous demandez en :

  1. Une piste en anglais peut être sélectionnée.
  2. Une piste compatible de la langue de base peut être sélectionnée.
  3. Une autre piste disponible peut être renvoyée comme solution de repli.
  4. Aucun enregistrement ne peut être produit s’il n’existe aucune transcription publique exploitable.

Stockez language et available_languages avec chaque transcription. Si une couverture linguistique exacte est obligatoire, rejetez ou examinez les résultats de repli au lieu de les injecter directement dans une traduction, une recherche ou un LLM.

Conservez aussi transcript_source. Les sous-titres générés automatiquement peuvent être précieux à grande échelle, mais YouTube précise qu’un son de mauvaise qualité, des langues non prises en charge, de longs silences, des locuteurs qui se chevauchent et la présence de plusieurs langues peuvent empêcher les sous-titres automatiques ou en réduire la qualité. Consultez les conseils de dépannage de YouTube sur les sous-titres automatiques.

Traiter des transcriptions YouTube en masse

Le traitement en masse doit être conçu comme un pipeline de données, pas comme une boucle qui suppose que chaque URL réussit.

Video URLs
   ↓
Validate and deduplicate
   ↓
Submit transcript batches
   ↓
Persist task IDs
   ↓
Poll with backoff
   ↓
Read every result page
   ↓
Validate language and source
   ↓
Store, chunk, index, or export

Appliquez ces pratiques :

  1. Normalisez les URL avant l’envoi. Ramenez les URL de lecture, de partage et d’intégration en double au même ID de vidéo.
  2. Gardez les lots récupérables. Stockez chaque lot, ses URL d’entrée, son ID de tâche, son heure d’envoi et son état terminal.
  3. Interrogez avec un délai croissant. Évitez une boucle d’interrogation serrée. Augmentez le délai tant qu’une tâche reste en file d’attente ou en cours d’exécution.
  4. Considérez un résultat partiel comme normal. Une tâche réussie peut contenir moins d’enregistrements que d’URL envoyées, car certaines vidéos n’ont pas de sous-titres exploitables.
  5. Paginez jusqu’au bout. Continuez jusqu’à ce que has_more soit faux.
  6. Rendez les écritures idempotentes. Faites un upsert par ID de vidéo et langue de transcription afin que les nouvelles tentatives ne créent pas de doublons.
  7. Enregistrez l’heure de collecte. Une transcription est un instantané ; les sous-titres peuvent être modifiés ou supprimés par la suite.

Voici un schéma minimal d’interrogation en Node.js :

const headers = {
  Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
  "Content-Type": "application/json"
};

const submitted = await fetch(
  "https://api.socq.ai/v1/youtube/transcripts",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      urls: [
        "https://www.youtube.com/watch?v=arj7oStGLkU",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      ],
      language: "en"
    })
  }
).then(response => response.json());

let task;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  task = await fetch(
    `https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
    { headers }
  ).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));

if (task.data.status !== "succeeded") {
  throw new Error(`Transcript task ended with ${task.data.status}`);
}

const transcripts = task.data.results.items;

Avant toute mise en production, ajoutez des contrôles de statut HTTP, des nouvelles tentatives bornées, la pagination par curseur, une journalisation structurée et l’annulation.

Gérer les sous-titres manquants et les résultats partiels

Un résultat manquant ne signifie pas automatiquement que tout le lot a échoué. Les causes courantes sont les suivantes :

  • Le créateur n’a pas fourni de sous-titres et les sous-titres automatiques sont indisponibles.
  • Les sous-titres sont encore en cours de traitement pour une vidéo récemment publiée.
  • La langue parlée n’est pas prise en charge ou n’a pas été reconnue.
  • La qualité audio est mauvaise, les voix se chevauchent ou la vidéo contient plusieurs langues.
  • La vidéo est privée, supprimée, restreinte ou indisponible dans l’environnement de collecte.
  • La langue demandée est absente et aucune solution de repli exploitable n’est disponible.

Classez les échecs au lieu de les réessayer indéfiniment :

Type d’échecAction recommandée
Aucun sous-titre exploitableMarquer comme indisponible ; éventuellement, router vers un workflow ASR distinct
Langue demandée absenteExaminer available_languages ou accepter une solution de repli contrôlée
Erreur temporaire de tâche ou de réseauRéessayer avec un délai exponentiel et une limite
Vidéo privée, supprimée ou restreinteArrêter les nouvelles tentatives et consigner la raison
Transcription vide ou suspecteMettre en quarantaine pour validation

Ne présentez pas une sortie ASR comme un sous-titre YouTube sans en indiquer la source. La distinction compte pour les revues de précision et les citations.

Exporter les données de transcription en toute sécurité

Les résultats en texte brut peuvent être exportés en TXT, JSON ou CSV.

Pour le TXT, écrivez le champ text et conservez un enregistrement de métadonnées séparé. Pour le JSON, conservez l’objet normalisé complet. Pour le CSV, utilisez une ligne par vidéo avec des champs tels que id, url, title, language, transcript_source, text et collected_at.

Le SRT et le VTT exigent des segments horodatés. Comme l’endpoint de transcription SocQ renvoie du texte brut et non des segments, un export fidèle de sous-titres horodatés ne peut pas être produit à partir de cette seule réponse.

Pour des archives interrogeables, ne stockez pas uniquement le corps de la transcription. Conservez l’ID de la vidéo, l’URL canonique, le titre, la chaîne, la langue, la source, la date de publication et la date de collecte sur chaque enregistrement dérivé.

Préparer les transcriptions pour la recherche et le RAG

Les transcriptions brutes sont généralement trop volumineuses et trop bruitées pour être envoyées à un modèle en un seul bloc. Un meilleur workflow est le suivant :

  1. Normaliser les espaces sans réécrire la source.
  2. Détecter les textes anormalement courts ou vides.
  3. Découper le texte en segments sémantiques qui se chevauchent.
  4. Associer les métadonnées de la source à chaque segment.
  5. Créer des embeddings.
  6. Stocker les segments dans un index de recherche ou vectoriel.
  7. Renvoyer l’URL de la vidéo et les métadonnées de la transcription avec chaque réponse.

Un enregistrement de segment utile ressemble à ceci :

{
  "video_id": "arj7oStGLkU",
  "video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "language": "en",
  "transcript_source": "auto_generated",
  "chunk_index": 12,
  "text": "The transcript text for this chunk...",
  "collected_at": "2026-07-16T08:00:00Z"
}

Comme la réponse source ne contient pas d’horodatages de segments, citez la vidéo plutôt que d’affirmer une plage horaire exacte. Si des citations au niveau du temps sont essentielles, choisissez une source qui fournit des segments vérifiés ou ajoutez une étape d’alignement distincte.

Choisir la bonne API YouTube avant de récupérer les transcriptions

La collecte de transcriptions est souvent la dernière étape d’un workflow de découverte plus large :

Cela réduit les requêtes de transcription inutiles et garde le jeu de données final lié à des critères de découverte explicites.

Maintenir un jeu de transcriptions à jour

Une archive de transcriptions doit avoir une politique d’actualisation explicite. Les sous-titres peuvent être corrigés après la publication, de nouvelles pistes de langue peuvent apparaître, et une vidéo auparavant disponible peut être supprimée ou restreinte. Tout récupérer de nouveau chaque jour est un gaspillage, mais traiter la première réponse comme définitive peut laisser un index de recherche avec un texte périmé ou impossible à retracer.

Choisissez un intervalle d’actualisation selon le cas d’usage :

  • Pour un jeu de données de recherche ponctuel, stockez l’heure de collecte et évitez les actualisations automatiques, sauf si l’analyse l’exige.
  • Pour une archive de chaîne interrogeable, revisitez plus fréquemment les vidéos récentes, car les sous-titres sont souvent modifiés peu après la publication.
  • Pour les workflows de conformité ou de citation, revalidez la source avant de publier une citation ou de prendre une décision à fort enjeu.
  • Pour les systèmes RAG durables, conservez un hash du contenu afin qu’une transcription inchangée ne déclenche pas un nouveau découpage et un nouveau calcul d’embeddings inutiles.

Lorsqu’une transcription actualisée change, créez une nouvelle version ou conservez une trace d’audit plutôt que d’écraser discrètement l’unique copie. Stockez au minimum l’ID de la vidéo, la langue de la transcription, la source des sous-titres, l’heure de collecte, le hash du texte et la version du pipeline. Si une vidéo cesse de produire un résultat, marquez l’enregistrement existant comme indisponible à la dernière vérification ; ne supposez pas que la transcription historique a toujours été invalide.

Checklist de production

Avant de lancer une tâche à gros volume, vérifiez que :

  • Les entrées sont des URL de vidéos YouTube publiques.
  • Les URL ont été normalisées et dédupliquées.
  • Les ID de tâche et les entrées d’origine sont conservés.
  • L’interrogation utilise un délai et des nouvelles tentatives bornées.
  • La pagination par curseur continue jusqu’à ce que has_more soit faux.
  • Les résultats manquants sont traités séparément des échecs de tâche.
  • La langue renvoyée est validée.
  • Les sous-titres générés automatiquement sont signalés.
  • Chaque segment ou export conserve les métadonnées de la source.
  • Votre usage du contenu respecte les droits applicables, les attentes en matière de vie privée et les conditions des plateformes.

Questions fréquentes (FAQ)

Existe-t-il une API officielle de transcription YouTube ?

YouTube dispose d’une Captions API officielle, mais le téléchargement d’une piste de sous-titres exige OAuth et la permission de modifier la vidéo. Ce n’est pas une API de transcription générale pour des vidéos publiques quelconques.

Peut-on télécharger une transcription YouTube sans OAuth ?

La SocQ YouTube Transcripts API utilise une clé API SocQ plutôt qu’une autorisation OAuth YouTube. Elle récupère le texte de transcription disponible à partir d’URL de vidéos publiques choisies.

SocQ peut-il générer une transcription lorsqu’une vidéo n’a pas de sous-titres ?

Non. L’endpoint renvoie le texte de transcription public disponible. Une vidéo sans sous-titres exploitables peut ne produire aucun résultat. Utilisez un workflow de reconnaissance vocale distinct et clairement signalé si vous avez besoin d’une solution de repli ASR.

Peut-on demander une langue précise ?

Oui. Vous pouvez envoyer une langue BCP-47 facultative, comme en ou zh-CN, mais la langue réellement renvoyée peut différer. Vérifiez toujours language et available_languages.

La réponse inclut-elle des horodatages et des étiquettes de locuteurs ?

Non. Le format de réponse est du texte brut normalisé et ne fournit ni horodatages de segments ni étiquettes de locuteurs garanties.

Peut-on récupérer plusieurs transcriptions en une seule requête ?

Oui. Envoyez plusieurs URL de vidéos publiques dans urls, conservez l’ID de tâche et lisez chaque page de résultats terminée une fois la tâche asynchrone réussie.

Combien coûte la YouTube Transcripts API ?

La documentation actuelle de l’endpoint indique 0,5 crédit par résultat de transcription normalisé. Consultez la page en direct de l’endpoint avant d’estimer une charge de production, car les tarifs peuvent changer.

YOUTUBE API

Tester le workflow avec une URL publique YouTube

Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.

Découvrir les API YouTube