API zur Umwandlung von Sprache in Text

Diese API transkribiert abgeschlossene Audiodateien als Aufträge in einer Warteschlange. Sende eine Datei, bewahre die zurückgegebene Auftrags-ID auf und rufe den Auftrag ab, bis die Verarbeitung abgeschlossen ist. Sende jede Anfrage über HTTPS mit den Zugangsdaten deines Kontos: entweder mit HTTP-Basic-Zugangsdaten wie in den Beispielen oder mit einem API-Token, wie unter Authentifizierung beschrieben. Bewahre Zugangsdaten auf deinem Server auf.

Endpunkte

Die beiden API-Hosts https://api.multi.tel und der Kompatibilitätshost https://api.multitel.net teilen sich dieselben kontogebundenen Aufträge, Idempotenzschlüssel, Limits und Abrechnungsdaten. Sie unterscheiden sich in der Upload-Kodierung und der äußeren Antwortstruktur. Verwende deshalb durchgängig denselben Host mit einem passenden Parser.

Auf api.multi.tel ist jeder Pfad auch mit dem Präfix /v1/speech-to-text anstelle von /v3/speech_to_text verfügbar, zum Beispiel POST /v1/speech-to-text/estimate. Auf api.multitel.net verwendest du die Pfade mit /v3/speech_to_text.

Die Antwort mit den Dienstinformationen enthält mode (batch), realtime (false), paidEnabled (ob neue kostenpflichtige Einreichungen derzeit angenommen werden), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) und maxUploadBytes (26214400) sowie eine kurze description. Der Abruf ist kostenlos und funktioniert auch bei deaktivierten kostenpflichtigen Einreichungen. Er gibt nur dann 503 mit transcription_unavailable zurück, wenn der gesamte Dienst nicht verfügbar ist.

Audiodatei vorbereiten

Verwende eine abgeschlossene Audiodatei mit höchstens 25 MiB (26,214,400 Bytes) und einer Dauer von höchstens 2 Stunden (7,200 Sekunden). Beim Einreichen muss die Datei als MP3-, WAV-, Ogg-, FLAC-, MOV- oder Matroska-Medium mit einem Audiostream erkannt werden. Die Dauer in den Metadaten muss größer als null sein und darf 7,200 Sekunden nicht überschreiten. Eine erkannte Datei, die diese Prüfungen nicht besteht, wird mit 422 und unsupported_audio abgelehnt. Eine Datei, die in keinem dieser Formate gelesen werden kann, wird derzeit möglicherweise stattdessen mit einem Serverfehler (500) abgelehnt. Reiche eine solche Datei nicht unverändert erneut ein. Die Dateiendung allein belegt keine Kompatibilität.

Das Bestehen dieser Prüfungen garantiert nicht, dass sich das Audio dekodieren lässt. Audio wird mit einem oder zwei Kanälen verarbeitet. Eine Datei mit mehr als zwei Audiokanälen, mit einer dekodierten Audiodauer von mehr als 2 Stunden oder mit einem anderen Dekodierungsfehler während der Verarbeitung endet als Auftrag mit Status failed, in der Regel mit decode_failed, und wird nicht berechnet. Wandle Mehrkanalaudio vor dem Einreichen in Mono oder Stereo um.

Der optionale Sprachhinweis ist ein Code aus zwei oder drei Kleinbuchstaben für die gesprochene Sprache, etwa en. Wenn du keinen Hinweis geben möchtest, lasse das Feld weg; api.multi.tel lehnt eine leere Zeichenfolge ab. Der Hinweis steuert die Verarbeitung, wird aber nicht mit einer Liste unterstützter Sprachen abgeglichen. Verwende daher einen gültigen Code für die gesprochene Sprache.

Transkriptionsauftrag einreichen

Sende JSON mit Content-Type: application/json an POST https://api.multi.tel/v3/speech_to_text. Der Anfragetext darf bis zu 35 MiB groß sein. Damit ist eine Datei maximaler Größe nach der Base64-Kodierung abgedeckt. Ein größerer Anfragetext wird mit 413 abgelehnt.

Jede andere JSON-Eigenschaft, einschließlich idempotency_key, wird mit 400 und invalid_transcription_request abgelehnt. Sende den Schlüssel als Header.

Idempotenzschlüssel

Jede Einreichung benötigt einen Header Idempotency-Key mit 1 bis 190 Zeichen. Verwende ASCII-Buchstaben, Ziffern, -, _, . und : ohne führende oder nachgestellte Leerzeichen: Der Kompatibilitätshost entfernt umgebende Leerraumzeichen und misst den Schlüssel in Bytes. Andere Zeichen können daher auf den Hosts unterschiedlich gezählt werden. Ein fehlender Schlüssel oder ein Schlüssel mit 191 oder mehr Zeichen wird mit 400 abgelehnt.

Schlüssel gelten für dein Konto und die Spracherkennung, über beide Hosts und alle Zugangsdaten deines Kontos hinweg. Derselbe Schlüssel mit derselben Datei und Sprache liefert den vorhandenen Auftrag mit HTTP 200 und duplicate: true zurück, unabhängig vom Status und selbst dann, wenn die Verarbeitung seit der Auftragserstellung aktualisiert wurde. Es erfolgt keine weitere Berechnung. Die Wiederverwendung eines Schlüssels mit einer anderen Datei oder Sprache ergibt 409 mit idempotency_conflict. Ein neuer Schlüssel erstellt selbst für eine identische Datei einen neuen Auftrag, der bei erfolgreichem Abschluss der Verarbeitung separat berechnet wird.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

Ein neuer Auftrag liefert HTTP 202 mit den unten gezeigten Feldern zurück. Eine Wiederholung liefert HTTP 200 mit dem vollständigen Auftragsobjekt, das unter Transkript abrufen beschrieben ist. Lies die Auftrags-ID, eine UUID, aus data.id. Die Antwort für einen neuen Auftrag sieht so aus (Kennung und Werte sind Beispiele):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Während ein Auftrag wartet oder verarbeitet wird, sind durationSeconds, billedSeconds und costUsd Schätzungen aus den Dateimetadaten. Die endgültige Berechnung verwendet die dekodierte Dauer.

Eine Einreichung kann auch 402 mit insufficient_balance zurückgeben, wenn das Prepaid-Guthaben den Auftrag zusammen mit deinen anderen offenen Aufträgen nicht abdeckt, 429 mit transcription_queue_full bei zu vielen offenen Aufträgen deines Kontos oder des Dienstes, 429 mit audio_validation_busy bei ausgelasteter Dateivalidierung und 503 mit paid_transcription_not_enabled, solange die kostenpflichtige Transkription deaktiviert ist. Wiederhole Anfragen mit den Antworten 429 und 503 später mit demselben Schlüssel.

Schätzung ohne Auftragserstellung

Sende denselben JSON-Anfragetext an POST https://api.multi.tel/v3/speech_to_text/estimate. Ein Idempotenzschlüssel ist nicht erforderlich. Eine Schätzung validiert und vermisst die Datei, transkribiert sie aber nicht, erstellt keinen Auftrag, reserviert kein Guthaben, prüft deinen Kontostand nicht und belastet dein Konto nicht. Ein Hinweis im Feld language wird akzeptiert, beeinflusst die Schätzung jedoch nicht.

Eine erfolgreiche Schätzung liefert HTTP 200 mit estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd und costUsd unter data. Sie verwendet die Dauer aus den Dateimetadaten. Ein abgeschlossener Auftrag wird dagegen anhand seiner dekodierten Dauer berechnet, die abweichen kann. Schätzungen führen dieselben Dateiprüfungen wie Einreichungen durch. Sie sind nur bei aktivierter kostenpflichtiger Transkription verfügbar, andernfalls folgt 503 mit paid_transcription_not_enabled. Sie können 429 mit audio_validation_busy zurückgeben, wenn die Dateivalidierung ausgelastet ist. Versuche es nach kurzer Wartezeit erneut.

Transkript abrufen

Frage GET /v3/speech_to_text/JOB_ID regelmäßig ab, wie im Leitfaden zum Auftragsablauf beschrieben. Das Auftragsobjekt enthält diese Felder:

Transkripte sowie ihre Zeitstempel, Sprach- und Kanalangaben werden automatisch erzeugt; ihre Richtigkeit ist nicht garantiert. Nimm jedes Qualitätsmerkmal zum Anlass, das Ergebnis zu prüfen, und vergleiche wichtige Namen, Zahlen und Zusagen mit dem Originalaudio. Lange Stille und sehr leise Passagen werden übersprungen und erzeugen keine Segmente. Die Ergebnisse identifizieren keine einzelnen Sprecher. Meldet ein Ergebnis einen channelCount von 2, hat jedes Segment einen channel mit dem Wert A (erster bzw. linker Kanal) oder B (zweiter bzw. rechter Kanal). Sprecher werden damit nur getrennt, wenn jeder auf einem eigenen Kanal aufgenommen wurde. Zweikanalaudio wird einmal anhand seiner verstrichenen Dauer berechnet, nicht pro Kanal. Monoergebnisse haben keine Kanalangaben.

api.multitel.net verwenden

Der Kompatibilitätsendpunkt POST https://api.multitel.net/v3/speech_to_text akzeptiert multipart/form-data mit einem Dateiteil audio und einem optionalen Feld language statt des JSON-Felds audioBase64. Ein leerer Wert für language wird wie ein fehlender Sprachhinweis behandelt. Sende denselben Header Idempotency-Key. Fehlt der Header, akzeptiert dieser Host auch ein Formularfeld idempotency_key. Felder mit den Namen source, free, billing_source, realtime oder stream werden mit 400 und unsupported_transcription_option abgelehnt; andere Formularfelder werden ignoriert. Dieser Host gibt außerdem diese Fehler zurück:

• 400 idempotency_key_required bei fehlendem oder zu langem Schlüssel.
• 400 audio_upload_required bei fehlendem oder nicht vollständig empfangenem Upload.
• 400 invalid_language bei ungültiger Sprache.
• 413 invalid_audio_size bei einer leeren oder zu großen Datei.
• 400 invalid_job bei einer falsch formatierten Auftrags-ID.

Antworten des Spracherkennungsdienstes auf diesem Host verwenden die äußere Struktur {"status":{"code":HTTP_STATUS},"response":{...}}. Beachte, dass status ein Objekt und keine Zeichenfolge ist. Bei Erfolg enthält response dasselbe Objekt wie data auf dem primären Host. Die Auftrags-ID ist daher response.id. Bei einem Fehler enthält response.code den Fehlercode; weder eine Meldung noch eine Anfrage-ID ist enthalten. Authentifizierungsfehler (401) werden von der allgemeinen Anmeldeprüfung des Hosts zurückgegeben und können einen anderen Antworttext haben. Prüfe deshalb vor dem Parsen den HTTP-Status. Vertausche die Upload-Kodierung oder den Antwortparser nicht zwischen den Hosts.

Für eine Schätzung auf diesem Host sende dieselben Multipart-Felder per POST an /v3/speech_to_text/estimate. Ein Idempotenzschlüssel ist nicht erforderlich; die Schätzung steht unter response.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'