Traduire des sous-titres

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

​

Authentification et autorisations

​

Paramètres

{
  "type": "object",
  "properties": {
    "subtitleContent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2097152
    },
    "fileName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[^/\\\\\\r\\n\\0]+$"
    },
    "format": {
      "type": "string",
      "enum": ["srt", "vtt"]
    },
    "sourceLanguage": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "targetLanguage": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "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": ["subtitleContent", "targetLanguage"],
  "additionalProperties": false
}

​

Idempotence

​

Exemples de requêtes

curl --request POST 'https://api.voicecheap.ai/v1/actions/subtitles_translate' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"subtitleContent":"1\n00:00:00,000 --> 00:00:01,500\nHello world.\n","fileName":"interview.srt","format":"srt","sourceLanguage":"english","targetLanguage":"french","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'

const input = {
  subtitleContent: '1\n00:00:00,000 --> 00:00:01,500\nHello world.\n',
  fileName: 'interview.srt',
  format: 'srt',
  sourceLanguage: 'english',
  targetLanguage: 'french',
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/subtitles_translate', {
  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/subtitles_translate",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"subtitleContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n", "fileName": "interview.srt", "format": "srt", "sourceLanguage": "english", "targetLanguage": "french", "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": "subtitles_translate",
    "createdAt": 1792152000000,
    "fileName": "voicecheap-subtitles_translate-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
    "byteLength": 365,
    "contentType": "application/json; charset=utf-8",
    "status": "completed",
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "getAction": "subtitles_result_get",
    "downloadAction": "subtitles_result_download",
    "listAction": "subtitles_result_list"
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_translate",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_translate",
    "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":"subtitles_translate"}'

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_translate",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
      "operation": "subtitles_translate",
      "createdAt": 1792152000000,
      "fileName": "voicecheap-subtitles_translate-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
      "byteLength": 365,
      "contentType": "application/json; charset=utf-8",
      "status": "completed",
      "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
      "getAction": "subtitles_result_get",
      "downloadAction": "subtitles_result_download",
      "listAction": "subtitles_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.
• Fournissez un texte SRT ou VTT en UTF-8 de 2 MiB au maximum. format peut valoir srt ou vtt ; s’il est omis, format est déduit du contenu ou du nom de fichier. targetLanguage est obligatoire ; sourceLanguage utilise la détection automatique par défaut.
• La sortie conserve le minutage des blocs sources et le format SRT/VTT sélectionné. characterCount compte les caractères du texte des blocs sources, et non les octets de sortie. Le fileName normalisé décrit le fichier de sous-titres, et non le JSON enregistré qui l’englobe.
• 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.
• L’enregistrement de l’historique des traductions de sous-titres est effectué au mieux ; utilisez le résultat d’intégration enregistré pour récupérer le contenu complet. Cette action ne consomme pas de source média envoyée.

​

Utilisation

​

Erreurs

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