Untertitel in ein YouTube-Video einfügen

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

​

Authentifizierung und Berechtigungen

​

Parameter

{
  "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}$"
    },
    "srtContent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2097152
    },
    "detectedLanguage": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "subtitleLayout": {
      "type": "object",
      "properties": {
        "maxLinesPerCaption": {
          "anyOf": [
            {
              "type": "number",
              "const": 1
            },
            {
              "type": "number",
              "const": 2
            },
            {
              "type": "number",
              "const": 3
            }
          ]
        },
        "maxCharactersPerLine": {
          "type": "integer",
          "minimum": 24,
          "maximum": 64
        }
      },
      "required": ["maxLinesPerCaption", "maxCharactersPerLine"],
      "additionalProperties": false
    },
    "subtitleStyle": {
      "type": "object",
      "properties": {
        "fontFamily": {
          "type": "string",
          "enum": ["sans", "serif", "mono"]
        },
        "fontSize": {
          "type": "string",
          "enum": ["small", "medium", "large"]
        },
        "textColor": {
          "type": "string",
          "enum": ["white", "yellow", "cyan"]
        },
        "backgroundStyle": {
          "type": "string",
          "enum": ["outline", "box", "shadow"]
        },
        "position": {
          "type": "string",
          "enum": ["bottom", "middle"]
        }
      },
      "required": ["fontFamily", "fontSize", "textColor", "backgroundStyle", "position"],
      "additionalProperties": false
    }
  },
  "required": ["youtubeUrl", "srtContent"],
  "additionalProperties": false
}

​

Idempotenz

​

Anfragebeispiele

curl --request POST 'https://api.voicecheap.ai/v1/actions/subtitles_burn_youtube' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"youtubeUrl":"https://www.youtube.com/watch?v=abcdefghijk","srtContent":"1\n00:00:00,000 --> 00:00:01,500\nHello world.\n","detectedLanguage":"english","subtitleLayout":{"maxLinesPerCaption":2,"maxCharactersPerLine":42},"subtitleStyle":{"fontFamily":"sans","fontSize":"medium","textColor":"white","backgroundStyle":"outline","position":"bottom"},"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'

const input = {
  youtubeUrl: 'https://www.youtube.com/watch?v=abcdefghijk',
  srtContent: '1\n00:00:00,000 --> 00:00:01,500\nHello world.\n',
  detectedLanguage: 'english',
  subtitleLayout: {
    maxLinesPerCaption: 2,
    maxCharactersPerLine: 42,
  },
  subtitleStyle: {
    fontFamily: 'sans',
    fontSize: 'medium',
    textColor: 'white',
    backgroundStyle: 'outline',
    position: 'bottom',
  },
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/subtitles_burn_youtube', {
  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_burn_youtube",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"youtubeUrl": "https://www.youtube.com/watch?v=abcdefghijk", "srtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n", "detectedLanguage": "english", "subtitleLayout": {"maxLinesPerCaption": 2, "maxCharactersPerLine": 42}, "subtitleStyle": {"fontFamily": "sans", "fontSize": "medium", "textColor": "white", "backgroundStyle": "outline", "position": "bottom"}, "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_burn_youtube",
    "createdAt": 1792152000000,
    "fileName": "voicecheap-subtitles_burn_youtube-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
    "byteLength": 225,
    "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_burn_youtube",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}

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

{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_burn_youtube",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
      "operation": "subtitles_burn_youtube",
      "createdAt": 1792152000000,
      "fileName": "voicecheap-subtitles_burn_youtube-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
      "byteLength": 225,
      "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.
• Geben Sie eine öffentliche HTTPS-URL eines YouTube-Videos und gültiges SRT in srtContent an. Obwohl das Aktionsschema srtContent als optional kennzeichnet, validiert der aktuelle YouTube-Renderer den Wert ausnahmslos und gibt bei fehlender Angabe 400 SRT_EMPTY zurück. Dieser Handler generiert YouTube-Untertitel nicht automatisch.
• Das importierte YouTube-Video darf nicht länger als 2 Stunden und die zusammengesetzte Datei nicht größer als 300 MiB sein. Die Importauflösung richtet sich nach dem Tarif des Akteurs.
• 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.
• Teilt das tägliche Kontingent zum Hinzufügen von Untertiteln mit subtitles_burn. Ein Rendervorgang verbraucht eine Generierung, auch wenn SRT bereitgestellt wurde.
• Es wird kein zuvor hochgeladener fileKey verwendet. Das gerenderte Video wird separat gespeichert; sein gespeicherter Verlauf zum Einbrennen von Untertiteln kann die temporäre Download-URL erneuern.

​

Nutzung

​

Fehler

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