Skip to main content
POST
Transcrivez une piste audio envoyée en mots horodatés pour modifier les sous-titres. Cette opération ne permet ni le rendu de vidéos animées ni les sessions d’édition locales dans le navigateur. Elle renvoie une référence compacte vers le résultat enregistré ; utilisez son getAction ou downloadAction pour récupérer le résultat complet.

​
Authentification et autorisations

​
string
requis
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: subtitles: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

​
string
requis
Un fileKey vous appartenant renvoyé par un envoi finalisé ou une importation de média. Chaque génération consomme sa source envoyée.Longueur minimale: 1. Longueur maximale: 1024.
​
string
Valeur textuelle.Longueur minimale: 1. Longueur maximale: 255. Motif: ^[^/\\\r\n\0]+$.
​
array
Liste de valeurs. Consultez le schéma d’entrée complet pour connaître la structure de ses éléments.Nombre maximal d’éléments: 100.
​
string
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.

​
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.

​
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 des mots des sous-titres. Le JSON complet contient words, durationSeconds et éventuellement detectedLanguage. Chaque mot possède text, startMs, endMs et speakerId, qui peut valoir null.

​
Champs du résultat

​
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.
HTTP 200

​
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 le fileKey d’un envoi ou d’un import finalisé qui vous appartient et considérez-le comme à usage unique. Dès que le traitement média commence, le nettoyage supprime la source après une réussite ou un échec de traitement. Un refus lors de la validation ou en raison du quota avant le traitement peut la laisser intacte. Réutilisez le requestId d’origine pour récupérer la génération acceptée avant d’en lancer une autre.
  • Envoyez uniquement la piste audio extraite : WAV, MP3, M4A, AAC, OGG, Opus ou FLAC, de 250 MiB au maximum. Un fichier contenant un flux vidéo est rejeté même si son nom porte une extension audio.
  • Beginner accepte jusqu’à 30 minutes ; Starter, Creator, Pro, Scale et Enterprise acceptent jusqu’à 60 minutes, avec une tolérance de 2 secondes pour le conteneur.
  • Quota quotidien de transcription de sous-titres : Beginner 10, Starter 15, Creator 30, Pro 60, Scale 100 et Enterprise 100 ; partagé avec l’outil de sous-titrage web.
  • Les décalages des mots sont en millisecondes ; durationSeconds est en secondes. Le serveur renvoie des mots horodatés, et non une vidéo animée rendue. La modification et le rendu des sous-titres en local dans le navigateur ne relèvent pas de cette action.
  • La transcription des sous-titres ne dispose pas d’une famille d’actions distincte pour l’historique web. Utilisez subtitles_result_list/get/download pour récupérer l’intégralité de sa sortie d’intégration.

​
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