Skip to main content
POST
Incrustez des sous-titres dans une vidéo envoyée. Fournissez un SRT existant ou laissez VoiceCheap transcrire la vidéo. Enregistre l’URL de la vidéo produite et son historique de sous-titrage. 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}$.
​
object
Objet JSON. Consultez le schéma d’entrée complet pour connaître ses champs imbriqués.
​
string
Valeur textuelle.Longueur minimale: 1. Longueur maximale: 2097152.
​
string
Valeur textuelle.Longueur minimale: 2. Longueur maximale: 60.
​
object
Objet JSON. Consultez le schéma d’entrée complet pour connaître ses champs imbriqués.
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 d’un résultat de sous-titres rendus enregistré. Son JSON complet contient srt, sourceSrt, subtitledVideoUrl et, éventuellement, detectedLanguage.

​
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.
  • La source doit contenir de la vidéo, ne pas dépasser 300 MiB et durer au plus 2 heures. Fournissez un SRT existant dans srtContent ou omettez ce champ pour générer les sous-titres à partir d’un flux audio. Sans SRT fourni, la source doit également contenir de l’audio.
  • subtitleStyle est un objet complet : fontFamily sans/serif/mono, fontSize small/medium/large, textColor white/yellow/cyan, backgroundStyle outline/box/shadow et position bottom/middle. subtitleLayout exige les deux champs de disposition pris en charge.
  • 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.
  • subtitles_burn et subtitles_burn_youtube partagent le quota de l’outil d’ajout de sous-titres. Le rendu avec des sous-titres fournis consomme tout de même une génération. Le rendu crée une vidéo de sortie distincte et tente d’enregistrer une entrée d’historique d’incrustation des sous-titres, sans garantie de réussite.
  • L’opération renvoie uniquement les quatre champs de sous-titres et de sortie dans son JSON enregistré. Pour actualiser l’URL de lecture de la vidéo, utilisez subtitles_burn_history_list/get et subtitles_burn_download.

​
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