Untertitel übersetzen

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

​

Authentifizierung und Berechtigungen

​

Parameter

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

​

Idempotenz

​

Anfragebeispiele

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)

​

Antwort

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

​

Ergebnisfelder

​

Diese Anfrage wiederherstellen und abfragen

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

​

Hinweise zur Operation

• Erfordert ein kostenpflichtiges Abonnement und die Aktionsberechtigung. Der persönliche Tooltarif des handelnden Kontos wird bei der Ausführung erneut geprüft; gespeicherte Tools und Uploadreferenzen gehören diesem Konto, auch wenn die Zugangsdaten einem Team zugeordnet sind.
• Eine erfolgreiche Aktion verbraucht einen gemeinsamen monatlichen API/MCP-Aufruf. Beginner erlaubt 500, Starter 5,000 und Creator 25,000 Aufrufe/Monat; Pro, Scale und Enterprise haben keine monatliche Obergrenze. Limits pro Minute gelten weiterhin: jeweils 30, 60, 120, 180, 300 und 600. Generierungskontingente der Werkzeuge sind davon getrennt.
• Verwenden Sie eine UUID v4 als requestId oder einen identischen Idempotency-Key-Header und behalten Sie bei erneuten Versuchen dieselbe Aktion, ID und dieselben Argumente bei. Eine zwischengespeicherte Wiederholung verbraucht keinen weiteren monatlichen Aufruf.
• Dies ist eine asynchrone Aktion. Das erste Transportergebnis ist eine Anfrage im Status running mit pollAction; fragen Sie action_request_get mit diesem Vorgang und der ursprünglichen requestId regelmäßig ab. Das hier gezeigte Ergebnis des abgeschlossenen Vorgangs ist eine kompakte Referenz auf die gespeicherte Ausgabe, kein generierter Body.
• Die vollständige Ausgabe wird unabhängig vom begrenzten Cache für die Aktionsabfrage mit authentifizierter Eigentümerschaft in einem verschlüsselten Speicher gesichert. Rufen Sie das zurückgegebene getAction mit resultId und includeContent: true für strukturiertes JSON oder downloadAction mit resultId für JSON-Text auf. listAction bietet einen Wiederherstellungsweg, wenn nur die ursprüngliche Anfrage bekannt ist.
• Das gespeicherte JSON ist auf 32 MiB begrenzt. Die Metadaten legen niemals seinen Speicherverschlüsselungsschlüssel oder eine nicht authentifizierte Download-URL für das Transkript offen.
• Eine erfolgreiche Generierung rechnet eine Einheit des persönlichen Werkzeugkontingents ab. Eine fehlgeschlagene Generierung gibt ihre Werkzeugreservierung normalerweise frei. Wenn die dauerhafte Speicherung der Ausgabe ungewiss ist, prüfen Sie dieselbe Anfrage und den Verlauf gespeicherter Ergebnisse, bevor Sie erneut generieren; der Server behält die Reservierung bei, um eine doppelte Nutzung zu verhindern.
• Höhere Tarife ohne monatliche Integrationsobergrenze unterliegen weiterhin den unten aufgeführten werkzeugspezifischen Tageskontingenten und Medienlimits. Diese eigenständigen Aktionen verwenden ihr Werkzeugkontingent statt Synchronisationsminuten oder TTS-Zeichen.
• Übergeben Sie UTF-8-SRT- oder VTT-Text mit bis zu 2 MiB. format kann srt oder vtt sein; bei Weglassen wird format aus Inhalt oder Dateiname abgeleitet. targetLanguage ist erforderlich; sourceLanguage verwendet standardmäßig die automatische Erkennung.
• Die Ausgabe behält die Zeitsteuerung der Ausgangsuntertitel und das gewählte SRT/VTT-Format bei. characterCount zählt die Zeichen im Ausgangstext der Untertiteleinträge, keine Ausgabebytes. Der normalisierte fileName beschreibt die Untertiteldatei und nicht das äußere gespeicherte JSON.
• Tägliches Kontingent pro Tool: Beginner 5, Starter 15, Creator 30, Pro 60, Scale 100 und Enterprise 100 erfolgreiche Generierungen. Es wird mit dem entsprechenden Web-Tool geteilt und verwendet das Zurücksetzungsfenster des Konto-Tools.
• Das Speichern des Untertitelübersetzungsverlaufs erfolgt nach bestem Bemühen; verwenden Sie das gespeicherte Integrationsergebnis, um den vollständigen Inhalt wiederherzustellen. Diese Aktion verbraucht keine hochgeladene Medienquelle.

​

Nutzung

​

Fehler

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