Transcrire une vidéo YouTube

POST https://api.voicecheap.ai/v1/actions/youtube_transcript_create

​

Authentification et autorisations

​

Paramètres

{
  "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

​

Exemples de requêtes

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"}'

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);

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

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "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"
}

{
  "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"
}

{
  "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

​

Récupérer et suivre cette requête

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"}'

{
  "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, 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

​

Erreurs

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["transcription:write"]
  }
}