> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Transcrire une vidéo YouTube
> Récupérez ou générez une transcription YouTube avec des segments horodatés, du texte brut et des sous-titres SRT. Enregistre l’historique des transcriptions. Renvoie une référence compacte vers le résultat enregistré ; utilisez son getAction ou downloadAction pour récupérer le résultat complet.
Récupérez ou générez une transcription YouTube avec des segments horodatés, du texte brut et des sous-titres SRT. Enregistre l’historique des transcriptions. Renvoie une référence compacte vers le résultat enregistré ; utilisez son getAction ou downloadAction pour récupérer le résultat complet.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/youtube_transcript_create
```
## Authentification et autorisations
Envoyez une clé API VoiceCheap dans cet en-tête. Authorization: Bearer avec la même clé API est également accepté. Les jetons d’accès OAuth sont
acceptés uniquement par MCP, pas par cet endpoint REST.
Autorisations requises: `transcription:write`.
Un abonnement payant actif est requis. Les autorisations ne modifient ni les rôles dans l’équipe, ni la propriété des ressources, ni les crédits média, ni les limites du forfait.
## Paramètres
Valeur textuelle.
Longueur maximale: 2048. Format: "uri".
Facultatif au niveau du transport : le serveur injecte un identifiant avant la validation si ce champ est omis. Fournissez votre propre UUID v4 stable pour récupérer le résultat en toute sécurité si la réponse est perdue.
Format: "uuid". Motif: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`.
Le JSON Schema ci-dessous conserve les noms de champs exacts, les types imbriqués, les valeurs par défaut, les limites et les valeurs acceptées exposés par la découverte. Les règles supplémentaires entre champs figurent dans les notes de l’opération.
```json theme={null}
{
"type": "object",
"properties": {
"youtubeUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"requestId": {
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
"type": "string",
"format": "uuid",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
}
},
"required": ["youtubeUrl"],
"additionalProperties": false
}
```
## Idempotence
Utilisez un UUID v4 dans requestId ou dans l’en-tête HTTP Idempotency-Key pour chaque mutation. Après une erreur réseau, réutilisez le même identifiant avec des arguments identiques. Si les deux sont fournis, ils doivent correspondre. Rejouer une requête enregistrée ne répète pas l’opération et ne décompte pas un nouvel appel mensuel. Les requêtes en échec ou interrompues ne sont pas relancées automatiquement.
Toute mutation peut renvoyer HTTP 202 lorsqu’une nouvelle tentative retrouve la même requête encore en cours, même si sa première exécution est habituellement synchrone. Si l’exécution est terminée mais que resultStored vaut false, une nouvelle tentative renvoie HTTP 200 avec l’état de la requête enregistrée, au lieu du résultat d’origine. Récupérez le résultat avec l’action d’historique, de résultat ou de téléchargement de son domaine.
## Exemples de requêtes
Remplacez les exemples d’identifiants de ressources et de clés média par des valeurs renvoyées pour votre compte. Conservez le même identifiant de requête lorsque vous réessayez la même mutation.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/youtube_transcript_create' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"youtubeUrl":"https://www.youtube.com/watch?v=abcdefghijk","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'
```
```javascript JavaScript theme={null}
const input = {
youtubeUrl: 'https://www.youtube.com/watch?v=abcdefghijk',
requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/youtube_transcript_create', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/youtube_transcript_create",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"youtubeUrl": "https://www.youtube.com/watch?v=abcdefghijk", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## Réponse
Cette opération renvoie HTTP 202 pendant son exécution. Conservez requestId et interrogez action\_request\_get avec cet identifiant et le nom de l’opération d’origine. Les états de suivi sont running, completed, failed et interrupted. Un résultat terminé peut renvoyer vers une tâche média distincte ; poursuivez avec l’action de statut ou de résultat propre à l’opération.
Référence enregistrée de transcription YouTube. Le JSON complet contient les métadonnées vidéo, les segments horodatés, text, srt, createdAt et éventuellement language ; un libellé de source peut être conservé pour les sous-titres natifs YouTube.
```json HTTP 202 theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 200 theme={null}
{
"data": {
"resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
"operation": "youtube_transcript_create",
"createdAt": 1792152000000,
"fileName": "voicecheap-youtube_transcript_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
"byteLength": 461,
"contentType": "application/json; charset=utf-8",
"status": "completed",
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"getAction": "transcription_result_get",
"downloadAction": "transcription_result_download",
"listAction": "transcription_result_list"
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_transcript_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_transcript_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
## Champs du résultat
| Champ | Description |
| - | - |
| `data.resultId` | UUID de la sortie enregistrée appartenant à l’acteur. Utilisez-le avec getAction ou downloadAction ; il est distinct de requestId et de tout historyId. |
| `data.operation` | Action de génération ayant produit ce JSON enregistré. |
| `data.createdAt` | Horodatage Unix en millisecondes de la préparation du résultat enregistré. |
| `data.fileName` | Nom de fichier suggéré pour un export JSON. |
| `data.byteLength` | Octets UTF-8 de la sortie sérialisée complète, et non des métadonnées condensées. |
| `data.contentType` | application/json; charset=utf-8. |
| `data.status` | completed lorsque la génération réussit. L’historique des résultats peut aussi présenter des entrées de récupération au statut pending. |
| `data.requestId` | UUID de la requête d’action d’origine, s’il a été enregistré. |
| `data.getAction` | Action de récupération d’un résultat vous appartenant ; includeContent vaut false par défaut et doit valoir true pour obtenir la sortie structurée complète. |
| `data.downloadAction` | Action d’export authentifiée renvoyant le JSON complet sous forme de chaîne de contenu. |
| `data.listAction` | Action de liste des résultats enregistrés qui vous appartiennent pour ce domaine d’autorisation. |
## Récupérer et suivre cette requête
Utilisez le même identifiant, même après une perte de connexion. Si resultStored vaut false, récupérez le résultat avec l’action d’historique, de résultat ou de téléchargement correspondante. Ne lancez jamais une seconde génération uniquement pour vérifier l’avancement.
```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab","operation":"youtube_transcript_create"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_transcript_create",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
"operation": "youtube_transcript_create",
"createdAt": 1792152000000,
"fileName": "voicecheap-youtube_transcript_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
"byteLength": 461,
"contentType": "application/json; charset=utf-8",
"status": "completed",
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"getAction": "transcription_result_get",
"downloadAction": "transcription_result_download",
"listAction": "transcription_result_list"
}
}
}
```
## Notes de l’opération
* Nécessite un abonnement payant et l’autorisation de l’action. L’offre personnelle d’outils de l’acteur est vérifiée de nouveau à l’exécution ; les outils enregistrés et les références d’envoi appartiennent à cet acteur, y compris lorsque l’identifiant d’accès est associé à une équipe.
* Une action réussie consomme un appel mensuel API/MCP partagé. Beginner autorise 500 appels/mois, Starter 5,000 et Creator 25,000 ; Pro, Scale et Enterprise n’ont pas de plafond mensuel. Les limites par minute restent applicables : respectivement 30, 60, 120, 180, 300 et 600. Les quotas de génération des outils sont distincts.
* Utilisez un requestId au format UUID v4, ou un en-tête Idempotency-Key identique, et conservez la même action, le même identifiant et les mêmes arguments lors des nouvelles tentatives. La restitution d’un résultat en cache ne consomme pas d’appel mensuel supplémentaire.
* Cette action est asynchrone. Le résultat initial du transport est une requête running avec pollAction ; interrogez régulièrement action\_request\_get avec cette opération et le requestId d’origine. Le résultat de l’opération terminée présenté ici est une référence compacte à une sortie enregistrée, et non le corps généré.
* Le résultat complet est enregistré dans un stockage chiffré sous la propriété de l’utilisateur authentifié, indépendamment du cache de suivi des actions à durée limitée. Appelez le champ getAction renvoyé avec resultId et includeContent: true pour obtenir le JSON structuré, ou downloadAction avec resultId pour obtenir le texte JSON. listAction permet de retrouver le résultat lorsque seule la requête d’origine est connue.
* Le JSON enregistré est limité à 32 MiB. Les métadonnées n’exposent jamais sa clé de chiffrement de stockage ni une URL de téléchargement de transcription sans authentification.
* Une génération réussie consomme une unité du quota personnel de l’outil. Une génération échouée libère normalement sa réservation d’outil. Si l’enregistrement de la sortie est incertain, vérifiez la même requête et l’historique des résultats enregistrés avant de relancer une génération ; le serveur conserve la réservation pour éviter une consommation en double.
* Les forfaits supérieurs sans plafond mensuel d’intégration restent soumis aux quotas quotidiens propres à chaque outil et aux limites média ci-dessous. Ces actions autonomes consomment leur quota d’outil plutôt que des minutes de doublage ou des caractères de synthèse vocale.
* Utilisez une URL HTTPS publique de YouTube sur youtube.com, [www.youtube.com](http://www.youtube.com), m.youtube.com, music.youtube.com ou youtu.be, sans identifiants de connexion intégrés ni port explicite. La vidéo doit durer au plus 2 heures.
* Quota quotidien par outil : Beginner 5, Starter 15, Creator 30, Pro 60, Scale 100 et Enterprise 100 générations réussies. Il est partagé avec l’outil web correspondant et utilise la fenêtre de réinitialisation des outils du compte.
* Une limite supplémentaire de 12 tentatives de transcription YouTube par jour s’applique à chaque offre, y compris aux tentatives échouées. Elle peut être inférieure au quota de générations réussies. Le parcours d’intégration utilise la limite partagée d’intégration par minute.
* Le JSON d’intégration enregistré est capturé avant la tentative ultérieure d’enregistrement de l’historique de transcription YouTube, effectuée sans garantie de réussite. transcriptId ne fait donc pas partie de cette sortie complète persistée ; recherchez l’historique de l’outil web avec youtube\_transcript\_history\_list si nécessaire.
* Aucune source envoyée au préalable n’est utilisée. Le résultat complet contient les champs startSeconds/endSeconds des segments de transcription en secondes, tandis que createdAt est en millisecondes.
## Utilisation
Chaque invocation réussie consomme un appel du quota mensuel API/MCP. Les crédits média et les quotas de génération propres à l’opération s’appliquent également.
## Erreurs
| Statut HTTP | Code | Signification ou solution |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Des identifiants ont été fournis dans un paramètre de requête access\_token ou api\_key. Envoyez les identifiants dans les en-têtes. |
| 400 | `DURATION_TOO_LONG` | La vidéo YouTube dépasse 7,200 secondes. |
| 400 | `DURATION_UNKNOWN` | Impossible de déterminer une durée positive pour la vidéo YouTube. |
| 400 | `IDEMPOTENCY_CONFLICT` | Les ID de requête de l’en-tête et du corps diffèrent. |
| 400 | `INVALID_REQUEST_ID` | requestId ou Idempotency-Key n’est pas un UUID v4. |
| 400 | `INVALID_YOUTUBE_URL` | L’URL YouTube HTTPS n’identifie pas une vidéo prise en charge. |
| 400 | `VALIDATION_ERROR` | Les arguments ne respectent pas le schéma de l’action, ou un argument inconnu a été fourni. |
| 400 | `VIDEO_AGE_RESTRICTED` | La vidéo YouTube est soumise à une restriction d’âge. |
| 400 | `VIDEO_PRIVATE` | La vidéo YouTube est privée. |
| 400 | `VIDEO_REGION_BLOCKED` | La vidéo YouTube est bloquée dans la région du serveur. |
| 400 | `VIDEO_UNAVAILABLE` | La vidéo YouTube est indisponible. |
| 401 | `API_KEY_EXPIRED` | La clé API a expiré. |
| 401 | `INVALID_API_KEY` | Fournissez une clé API valide et non expirée. |
| 401 | `INVALID_CREDENTIAL` | L’en-tête Authorization est mal formé ou entre en conflit avec x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Aucun identifiant d’authentification utilisable n’a été fourni dans les en-têtes, ou il dépassait 4096 caractères. |
| 401 | `USER_NOT_FOUND` | Le compte associé à l’identifiant d’accès n’existe plus. |
| 403 | `ACCOUNT_UNAVAILABLE` | Le compte à l’origine de l’action ou le compte de facturation est indisponible ou en cours de suppression. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | L’utilisateur associé aux identifiants d’authentification appartient à plusieurs équipes, ce qui rend le contexte de facturation ambigu. |
| 403 | `INSUFFICIENT_SCOPE` | La clé API ou la connexion MCP ne dispose pas de l’autorisation requise pour cette action. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Les limites d’intégration du compte n’ont pas pu être vérifiées. |
| 403 | `PAID_SUBSCRIPTION_REQUIRED` | L’acteur authentifié ne dispose plus d’un abonnement payant au moment de l’exécution de cette action d’outil. |
| 403 | `SUBSCRIPTION_REQUIRED` | Utilisez un abonnement payant actif. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Le compte du propriétaire effectif de l’équipe est introuvable. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Ce compte a déjà 10 actions d’intégration en cours. Suivez une requête existante avant d’en démarrer une autre. |
| 409 | `IDEMPOTENCY_CONFLICT` | Réutilisez un identifiant uniquement avec la même opération et les mêmes arguments. |
| 410 | `TOOL_RESULT_ACCOUNT_UNAVAILABLE` | Le compte de l’acteur est en cours de suppression ou n’existe plus ; un résultat durable ne peut donc pas être enregistré. |
| 413 | `TOOL_RESULT_TOO_LARGE` | Le JSON complet généré dépasse 32 MiB et ne peut pas être enregistré comme résultat d’intégration. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Les appels utilisés et en attente ont atteint le quota mensuel partagé API/MCP. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Le compte a atteint sa limite d’intégration par minute ; consultez retryAfterSeconds. |
| 429 | `YOUTUBE_TRANSCRIPT_TOOL_ATTEMPT_LIMIT_REACHED` | La limite distincte de 12 tentatives de transcription YouTube par jour est épuisée. |
| 429 | `YOUTUBE_TRANSCRIPT_TOOL_DAILY_LIMIT_REACHED` | Le quota quotidien de réussites de l’outil de transcription YouTube est épuisé. |
| 500 | `INTERNAL_ERROR` | L’outil d’origine ou l’enregistrement du résultat a échoué en interne. Consultez la requête enregistrée et l’historique des résultats avant de relancer une génération. |
| 502 | `INTERNAL_ERROR` | La génération ou l’enregistrement du résultat a échoué. Vérifiez la requête d’origine et l’historique des résultats enregistrés avant de lancer une autre génération. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | L’action a été exécutée, mais l’enregistrement du résultat de la requête n’a pas pu être confirmé. Interrogez la même action avec le même requestId et examinez l’historique de la ressource avant de lancer une autre écriture. |
| 503 | `INTERNAL_ERROR` | Le résultat de la génération ou de l’enregistrement du résultat sauvegardé est incertain ou temporairement indisponible ; utilisez la récupération authentifiée du résultat avant de relancer une génération. |
| 503 | `SERVER_RESTARTING` | Le serveur redémarre. Réessayez dans un instant en conservant le même identifiant de requête pour une mutation. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["transcription:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.