Ein Videolink genügt für den ersten Request
Sende die URL mit deinem API-Schlüssel an POST /v1/transcriptions. Das geht mit Python oder jedem anderen HTTP-Client. Mit wait=60 bleibt der Request bis zu 60 Sekunden offen. Alle Felder und Statuscodes findest du in der API-Referenz.
Erstelle den Schlüssel im Dashboard und verwende ihn auf deinem Server oder in einem Script. Speichere die ID, sobald die API die Transkription angelegt hat. Reicht die Wartezeit nicht aus, läuft die Verarbeitung weiter. Lies den Status mit GET /v1/transcriptions/:id ab, statt denselben Auftrag neu anzulegen.
Dein Client sollte queued, fetching und transcribing von den abschließenden Zuständen unterscheiden. Bei completed kannst du das Transkript abrufen. Bei failed behandelst du den Fehler. Eine langsame Verbindung oder ein nicht verfügbares Video darf in deiner App nicht wie ein erfolgreiches, aber leeres Transkript aussehen.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'An transcript_source erkennst du die Textquelle
Die Antwort nennt die Quelle und bei YouTube-Untertiteln auch die Art der Spur. billed_minutes enthält die aufgerundete Videolänge. Die Referenz zum Transkriptionsobjekt beschreibt die Felder.
Speichere transcript_source und caption_kind, wenn die Herkunft für deine Anwendung wichtig ist. Untertitel vom Creator behalten ihren veröffentlichten Wortlaut, liefern aber keine Wort-Zeitstempel. Automatisch erzeugte YouTube-Untertitel enthalten Wortanfänge. Bei Speech-to-Text bekommst du Anfang, Ende und confidence pro Wort. Fordere diese zusätzlichen Daten nur bei Bedarf mit include=words an.
Die Segmente enthalten Text sowie Anfang und Ende in Sekunden. Damit kannst du Textstellen mit der Wiedergabe verknüpfen oder einem Assistenten genau die gesuchte Passage geben. Das JSON-Beispiel zeigt die Struktur der Antwort; der Beispieltext ist kein Zitat aus dem verlinkten Video.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}Untertitel abrufen oder das Audio neu transkribieren
source=auto ist voreingestellt. Mit captions verlangst du ausschließlich Untertitel. Fehlt eine passende Spur, bekommst du no_captions und zahlst nichts. Mit stt nutzt du immer die Tonspur. Die Doku zur Quellenwahl erklärt das Zusammenspiel mit Sprache und Sprecherzuordnung.
Brauchst du den veröffentlichten Untertiteltext, wähle captions. Für eine neue Audio-Transkription oder Sprecherzuordnung brauchst du Speech-to-Text. Bei auto und diarize=true überspringen wir deshalb die Untertitel. captions zusammen mit diarize=true lehnen wir ab, statt eine deiner Einstellungen zu ignorieren.
Auch language beeinflusst die Auswahl: Die Untertitelspur muss zur angefragten Sprache passen. Bei automatischer Sprachwahl gilt die Originalsprache des Videos. Automatisch übersetzte Spuren bleiben ausgeschlossen. Ein Sprachhinweis für Speech-to-Text hilft bei der Erkennung, übersetzt die Aufnahme aber nicht.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Vor einem neuen Versuch erst den Status prüfen
Ein privates Video, eine Altersbeschränkung oder ein laufender Livestream braucht eine andere Quelle. Ein neuer Request ändert daran nichts. Bei no_captions entscheidest du, ob eine Audio-Transkription für deine Anwendung infrage kommt. Läuft der Auftrag noch, ruf ihn erneut über seine ID ab. Die Fehlerübersicht hilft bei der Einordnung.
Musst du einen Create-Request nach einem Verbindungsfehler wiederholen, nutze den Idempotency-Key. Davon getrennt ist die Wiederverwendung einer früheren Transkription mit demselben Video und denselben Optionen. Ein Transkript aus dem Cache kann trotzdem als neuer Auftrag kostenpflichtig sein. Ein bereits fertiges Transkript über seine ID zu lesen, kostet keine weiteren Minuten.
Für Anwendungen mit mehreren Plattformen gilt: Auch YouTube, X, TikTok und Bluesky können Untertitel liefern, bevor auto auf Speech-to-Text zurückgreift. Derselbe Create-Endpoint nimmt etwa TikTok-Videos und Instagram Reels an. Prüfe die erlaubten Optionen je Plattform in der Quellenübersicht, bevor du sie in deiner Oberfläche anbietest.