API-Integration

Ihre erste Transkription

Die Transkription erfolgt im Hintergrund. Beim Erstellen eines Auftrags erhalten Sie sofort eine Antwort. Prüfen Sie den Status, bis das Ergebnis bereitsteht.

1. 1

   Auftrag erstellen

   Senden Sie POST /transcripts mit einer direkten, öffentlichen Medien-URL. Speichern Sie die zurückgegebene id.

2. 2

   Fortschritt prüfen

   Fragen Sie GET /transcripts/{id} alle 15–30 Sekunden ab, bis status den Wert complete oder error hat.

3. 3

   Transkript verwenden

   Lesen Sie JSON aus data oder laden Sie bei SRT- oder VTT-Anfragen die Datei über export_url herunter.

Auftragsstatus

Behandeln Sie jeden anderen Status als noch in Bearbeitung. Weitere Zwischenzustände können hinzukommen.

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage im Header Authorization, genau so, wie er beim Erstellen angezeigt wurde.

Authorization: <your api key>

Fügen Sie kein Bearer-Präfix hinzu.

Neue Schlüssel beginnen mit tp_live_. Der vollständige Schlüssel wird nur einmal angezeigt, beim Erstellen. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen; ein widerrufener Schlüssel funktioniert sofort nicht mehr.

Ein aktives Abonnement und die erforderliche API-Schlüsselberechtigung sind nötig.

Transkript erstellen

Starten Sie einen Transkriptionsauftrag für eine Mediendatei unter einer öffentlichen URL. Sobald der Auftrag in der Warteschlange steht, erhalten Sie eine Antwort mit status: "initializing".

Taption lädt die Datei direkt herunter. Links zu Freigabeseiten, etwa einer Vorschauseite von Google Drive oder Dropbox, funktionieren nicht.

media_urlstringerforderlich

Direkter Downloadlink zu Ihrer Mediendatei.

Maximal 2048 Zeichen

extensionstringerforderlich

Das Format der Mediendatei.

mp3wavm4aaacflacwmaopusmp4

languagestringerforderlich

Die in den Medien gesprochene Sprache als Sprach-Tag. Siehe die Referenz zu Sprachen.

Sprach-Tags ansehen

namestring

Anzeigename des Transkripts. Standardmäßig wird der Dateiname aus `media_url` verwendet. Längere Namen werden auf 200 Zeichen gekürzt.

Maximal 200 Zeichen

export_typestring

Ausgabeformat. Standard ist json, das den geparsten Transkriptinhalt in data zurückgibt. srt und vtt geben einen Dateilink in export_url zurück.

jsonsrtvtt

Standard: json

max_charinteger

Maximale Zeichenanzahl pro Untertitelsegment. Standard ist `16` für Chinesisch, Japanisch, Koreanisch und Kantonesisch sowie `65` für andere Sprachen. Werte außerhalb von 1–200 werden ignoriert; stattdessen gilt der Standardwert.

1–200

Antworten

Transkript abrufen

Rufen Sie den aktuellen Status und das Ergebnis eines Transkripts ab. Fragen Sie alle 15–30 Sekunden ab, solange der Auftrag bearbeitet wird.

Bei json oder ohne angegebenen Exporttyp erscheint das fertige Ergebnis in data. Bei srt oder vtt laden Sie die Datei über export_url herunter.

idstringerforderlich

Die von POST /transcripts zurückgegebene Transkript-ID.Maximal 256 Zeichen

Antworten

Das Transkriptobjekt

Anfragen zum Erstellen und zum Status geben ein JSON-Objekt zurück. Seine Felder beschreiben den Auftrag und, sobald verfügbar, dessen Ergebnis.

idstring

Die Transkript-ID. Verwenden Sie sie mit `GET /transcripts/{id}`.

statusstring

Aktueller Auftragsstatus: `initializing`, `transcribing`, `complete` oder `error`. Behandeln Sie jeden anderen Wert als noch in Bearbeitung.

dataJSON

Geparster JSON-Export, sobald bereit, für json oder ohne export_type; andernfalls eine leere Zeichenfolge.

export_urlstring

Downloadlink für einen srt- oder vtt-Export. Leer, bis das Ergebnis bereitsteht. Bei json oder ohne export_type ist dieses Feld in Statusantworten nicht enthalten.

messagestring

Zusätzliche Angaben zum aktuellen Status. Bei `transcribing` kann dies eine Fortschrittsphase wie `ANALYZING` oder `FINALIZING` sein. Wenn `status` den Wert `error` hat, beschreibt es den Fehler. Für Menschen bestimmt; nicht maschinell auswerten.

error_codestring

Optionaler maschinenlesbarer Code für ein Einreichungslimit.

limitinteger

Das geltende Kontolimit, enthalten in HTTP-429-Antworten.

Fehler und Wiederholungen

Entscheiden Sie anhand des HTTP-Statuscodes über den nächsten Schritt. Das Feld message ist für Menschen bestimmt; sein Wortlaut kann sich ändern.

API-Antworten enthalten einen X-Request-Id-Header. Geben Sie ihn an, wenn Sie sich wegen einer Anfrage an den Support wenden.