Speech-to-Text API: Tutorial für den Einstieg mit DeepScript

Wenn Sie Audio programmatisch transkribieren müssen, für ein SaaS-Produkt, ein internes Werkzeug oder eine automatische Verarbeitungskette, nimmt Ihnen die DeepScript-API die schwere Arbeit ab: Datei hoch, Transkript zurück. Keine ML-Infrastruktur, kein Modell-Hosting, keine GPU-Rechnung.

Diese Anleitung führt durch Authentifizierung, Upload, Statusabfrage und Ergebnisabruf, mit lauffähigen Beispielen in cURL, Python und JavaScript. Die vollständige Referenz steht unter api.deepscript.com/docs, die maschinenlesbare Spezifikation unter https://api.deepscript.com/openapi.json.

Authentifizierung

Jeder Aufruf braucht einen API-Schlüssel. Erzeugen lässt er sich im Dashboard unter Einstellungen > API-Schlüssel. Er gehört in den Authorization-Header jedes Requests:

Authorization: Bearer IHR_API_SCHLUESSEL

Der Schlüssel ist ein Geheimnis. Nicht in die Versionsverwaltung, nicht in Client-Code, sondern in eine Umgebungsvariable oder einen Secret-Manager.

Der Ablauf

Transkription ist ein asynchroner Job, und die API modelliert das offen statt es hinter einer langlaufenden Verbindung zu verstecken:

1. Upload einer Audio- oder Videodatei, das erzeugt den Job
2. Status abfragen, bis die Verarbeitung fertig ist, oder auf einen Webhook warten
3. Ergebnis abholen

Der Grund für die Trennung ist praktisch: eine Stunde Audio braucht je nach Modell 12 bis 30 Minuten. Keine HTTP-Verbindung soll so lange offen stehen.

Datei hochladen

cURL

curl -X POST https://api.deepscript.com/v1/transcriptions \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY" \
  -F "file=@besprechung.mp3" \
  -F "model=standard" \
  -F "language=de"

Python

import os
import requests

API_KEY = os.environ["DEEPSCRIPT_API_KEY"]
BASE_URL = "https://api.deepscript.com/v1"

def create_transcription(file_path, model="standard", language="de"):
    with open(file_path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/transcriptions",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f},
            data={"model": model, "language": language},
        )
    response.raise_for_status()
    return response.json()["data"]

job = create_transcription("besprechung.mp3")
print(f"Job angelegt: {job['id']}")

JavaScript (Node.js)

import fs from "fs";
import FormData from "form-data";

const API_KEY = process.env.DEEPSCRIPT_API_KEY;
const BASE_URL = "https://api.deepscript.com/v1";

async function createTranscription(filePath, model = "standard", language = "de") {
  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));
  form.append("model", model);
  form.append("language", language);

  const response = await fetch(`${BASE_URL}/transcriptions`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}`, ...form.getHeaders() },
    body: form,
  });

  if (!response.ok) throw new Error(`Upload fehlgeschlagen: ${response.status}`);
  const { data } = await response.json();
  return data;
}

const job = await createTranscription("besprechung.mp3");
console.log(`Job angelegt: ${job.id}`);

Antwort

Der Upload antwortet mit 202 Accepted, sobald die Datei angenommen ist:

{
  "data": {
    "id": "3f7c1e42-9b18-4a6d-8f21-6c0b5d9e77a4",
    "status": "queued"
  }
}

Zwei Details, die beim Verdrahten Zeit sparen: jede Nutzlast steckt in einem data-Objekt, und IDs sind UUIDs. Wer auf ein Präfixformat wie txn_… baut, baut auf eine Annahme.

Status abfragen

Für das Polling gibt es einen eigenen, leichten Endpunkt. Er liefert nur ID, Status und Fortschritt und kostet damit einen Bruchteil der vollständigen Antwort. Empfohlenes Intervall: 2 bis 5 Sekunden.

cURL

curl "https://api.deepscript.com/v1/transcriptions/$JOB_ID/status" \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY"

Python

import time

def wait_for_transcription(job_id, interval=5):
    while True:
        response = requests.get(
            f"{BASE_URL}/transcriptions/{job_id}/status",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        response.raise_for_status()
        data = response.json()["data"]

        if data["status"] == "completed":
            return data
        if data["status"] == "failed":
            raise RuntimeError("Transkription fehlgeschlagen")

        print(f"{data['progress']} %")
        time.sleep(interval)

wait_for_transcription(job["id"])

Antwort

{
  "data": {
    "id": "3f7c1e42-9b18-4a6d-8f21-6c0b5d9e77a4",
    "status": "processing",
    "progress": 64
  }
}

Wer den Fortschritt in einer Oberfläche anzeigen will, nimmt statt des Pollings den SSE-Stream unter /v1/transcriptions/{id}/events: eine offene Verbindung, Ereignisse bei jeder Änderung, kein Intervall zu wählen.

Ergebnis abholen

Sobald der Status auf completed springt, liefert der Detail-Endpunkt den vollständigen Datensatz. Ihn holt man genau einmal, denn er enthält die Wortliste mit Zeitstempeln und ist entsprechend groß.

cURL

curl "https://api.deepscript.com/v1/transcriptions/$JOB_ID" \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY"

Python

def get_transcription(job_id):
    response = requests.get(
        f"{BASE_URL}/transcriptions/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    response.raise_for_status()
    return response.json()["data"]

detail = get_transcription(job["id"])
print(detail["resultText"])

Antwort, gekürzt

{
  "data": {
    "id": "3f7c1e42-9b18-4a6d-8f21-6c0b5d9e77a4",
    "status": "completed",
    "language": "de",
    "detectedLanguage": "de",
    "duration": 1847,
    "wordCount": 4021,
    "speakerCount": 3,
    "cost": 0.09,
    "resultText": "Herzlich willkommen zur Quartalsbesprechung. Fangen wir mit …",
    "resultJson": {
      "words": [
        { "word": "Herzlich", "start": 0.0, "end": 0.42, "speaker": 0 },
        { "word": "willkommen", "start": 0.42, "end": 0.91, "speaker": 0 }
      ]
    }
  }
}

resultText ist der Fließtext, resultJson.words die zeitlich aufgelöste Wortliste samt Sprecherzuordnung. Für Suche und Indexierung reicht der Text, für Untertitel und für das Springen an eine Audiostelle brauchen Sie die Wörter.

Untertitel und andere Formate

Untertitel müssen Sie nicht selbst aus den Zeitstempeln bauen. Der Export-Endpunkt rendert das Ergebnis in das gewünschte Format:

curl "https://api.deepscript.com/v1/transcriptions/$JOB_ID/export?format=srt" \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY" \
  -o untertitel.srt

Verfügbar sind txt, srt, vtt, json und docx. Der Aufruf funktioniert nur bei abgeschlossenen Transkriptionen, sonst antwortet die API mit dem Problem-Typ not-ready.

Modelle

Das Modell geht als model beim Upload mit, Voreinstellung ist standard. Für dialektal gefärbte Aufnahmen aus dem DACH-Raum lohnt premium: es ist darauf abgestimmt und läuft in der Prioritätswarteschlange.

Sprachen

99 Sprachen. language nimmt einen ISO-639-1-Code (de, en, fr, ja) oder auto für die automatische Erkennung.

Ein praktischer Hinweis für deutschsprachige Inhalte: setzen Sie language=de explizit, wenn Sie die Sprache kennen. Die automatische Erkennung arbeitet auf den ersten Sekunden, und wenn eine Besprechung mit englischem Smalltalk beginnt, kann sie danebengreifen. Bei gemischtsprachigen Aufnahmen ist auto trotzdem die bessere Wahl.

Sprechertrennung steuern

Die Sprechertrennung ist in beiden Modellen enthalten. Wenn Sie die Zahl der Sprecher kennen, sagen Sie sie:

curl -X POST https://api.deepscript.com/v1/transcriptions \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY" \
  -F "file=@interview.mp3" \
  -F "model=premium" \
  -F "num_speakers=2"

num_speakers setzt die Zahl fest. Alternativ grenzen min_speakers und max_speakers sie ein, die beiden gehören immer zusammen. Bei einem Interview mit zwei Beteiligten ist die feste Angabe der wirksamste einzelne Griff gegen falsch getrennte Sprecher.

Webhooks statt Polling

Für den Produktionsbetrieb ist ein Webhook das sauberere Muster. Sie registrieren einen Endpunkt einmal, nicht pro Upload:

curl -X POST https://api.deepscript.com/v1/webhooks \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ihre-app.de/api/transcription-callback",
    "events": ["transcription.completed", "transcription.failed"]
  }'

Die Antwort enthält das Signaturgeheimnis, und zwar genau einmal: es gibt keinen Weg, es später erneut abzurufen. Jede Auslieferung trägt eine HMAC-SHA256-Signatur über den Rumpf, die Sie mit diesem Geheimnis prüfen. Eine Webhook-Verarbeitung ohne Signaturprüfung ist ein offener Endpunkt, an dem jeder „fertig" rufen kann.

Custom Vocabulary

Für Fachbegriffe, Produktnamen, Eigennamen und interne Abkürzungen können Sie eine Wortliste mitgeben:

curl -X POST https://api.deepscript.com/v1/transcriptions \
  -H "Authorization: Bearer $DEEPSCRIPT_API_KEY" \
  -F "file=@aufnahme.mp3" \
  -F "model=premium" \
  -F 'vocabulary=["DeepScript", "Hetzner", "Auftragsverarbeitung", "Kubernetes"]'

Das Feld heißt vocabulary und nimmt ein JSON-Array oder eine kommagetrennte Liste. Wer dieselbe Liste immer wieder braucht, legt sie einmal unter /v1/vocabularies ab und übergibt danach nur die vocabulary_id. Die Engine gewichtet diese Wörter höher, wenn das Audio mehrdeutig ist, und das ist bei Eigennamen fast immer der Fall.

Fehlerbehandlung

Fehler kommen als RFC-7807-Problemdokument mit application/problem+json zurück:

{
  "type": "insufficient-balance",
  "title": "Insufficient balance",
  "status": 402,
  "detail": "Required 0.18 EUR, available 0.04 EUR."
}

Werten Sie type aus, nicht title oder den Statuscode: der Slug ist stabil, die Formulierung nicht. Die wichtigsten Fälle beim Upload sind unsupported-format, file-too-large (Grenze 500 MB) und insufficient-balance. Bei 429 liefert die Antwort einen Retry-After-Header, an den Sie sich halten sollten, statt sofort erneut zu senden.

Preise und Datenschutz

Abgerechnet wird nach Audiodauer: 0,18 € pro Stunde im Standard-Modell, 0,27 € im Premium-Modell, ohne Aufpreis für Sprechertrennung oder Custom Vocabulary. Der Preisrechner rechnet Ihr Volumen durch.

Die Verarbeitung läuft auf eigenen Servern in Deutschland. Kein Audio geht an Fremd-KI, keine Kundendaten fließen in Modelltraining, und einen AVV nach Art. 28 DSGVO können Sie direkt auf der Website unterzeichnen. Was das im Detail bedeutet, steht im Trust Center.

Damit ist die API auch für Material geeignet, bei dem das nicht verhandelbar ist: Mandantengespräche, medizinische Diktate, Personalgespräche. Für die beiden erstgenannten Fälle gibt es eigene Artikel zu Kanzleien und zur Medizin.

Nächste Schritte

• Die vollständige Referenz mit allen 20 Operationen: api.deepscript.com/docs
• Die indexierbare Übersicht der Endpunkte: API-Seite
• Wenn Sie überlegen, Whisper stattdessen selbst zu betreiben: die Kostenrechnung dazu