Aufträge für Spracherkennung und Übersetzung

Ersetzen Sie SERVICE unten durch speech_to_text oder translate und JOB_ID durch die zurückgegebene UUID. Alle Vorgänge erfordern Zugangsdaten für Ihr Konto, wie unter Authentifizierung beschrieben, und sind auf das zugehörige Konto beschränkt. Ein Auftrag kann über beide API-Hosts gelesen werden. Die Hosts verwenden jedoch unterschiedliche Antwortstrukturen; verwenden Sie daher durchgehend denselben Host.

Auf api.multitel.net werden Authentifizierungsfehler (401) vor Anwendung dieser Antwortstruktur zurückgegeben und können einen anderen Antwortinhalt haben. Prüfen Sie vor dem Auswerten den HTTP-Status.

Authentifizierung

Jede Anfrage muss Zugangsdaten für Ihr Konto enthalten. Aufträge, Idempotenzschlüssel, Limits, Nutzungsdaten und Gebühren gehören dem Konto, dem die Zugangsdaten zugeordnet sind. Alle Zugangsdaten dieses Kontos teilen sie sich auf beiden Hosts, unabhängig davon, welche Zugangsdaten die Anfrage senden.

• HTTP Basic (Authorization: Basic oder curl --user). Akzeptiert werden ein API-Konto vom Typ Passwort, ein Unterkonto oder die Anmeldedaten Ihres Kontos. Wir empfehlen ein eigenes API-Konto. Der Benutzername darf keinen Doppelpunkt enthalten. Benutzername und Passwort dürfen nicht leer sein.
• Bearer-Token (Authorization: Bearer YOUR_TOKEN). Für ein API-Konto vom Typ Token akzeptiert. Token-API-Konten müssen eine IP-Beschränkung haben; Anfragen müssen von einer erlaubten Adresse stammen. Beide API-Hosts akzeptieren die für das Konto konfigurierten IPv4-Adressen und CIDR-Bereiche. Ein Token kann nicht als Basic-Passwort gesendet werden. Prüfen Sie, ob Ihr Token auf dem verwendeten Host funktioniert.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Ist ein API-Konto nach IP-Adresse eingeschränkt, senden Sie Anfragen von einer erlaubten Adresse. Fehlende oder ungültige Zugangsdaten liefern 401. Auf api.multitel.net liefern gültige, aber für diese Dienste nicht nutzbare Zugangsdaten, etwa als Basic gesendete Zugangsdaten eines Token-Kontos, 403 unsupported_transcription_principal oder unsupported_translation_principal. Wiederholte fehlgeschlagene Authentifizierungen von derselben Adresse auf api.multitel.net können zur Sperrung dieser Adresse führen. Korrigieren Sie die Zugangsdaten, bevor Sie es erneut versuchen.

Abschluss regelmäßig prüfen

Senden Sie GET /v3/SERVICE/JOB_ID. Wir empfehlen, höchstens alle 3 Sekunden abzufragen. Die äußere Antwortstruktur beschreibt die Anfrage. Prüfen Sie das Feld status im Auftrag, um festzustellen, ob die Verarbeitung abgeschlossen ist.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Auf api.multitel.net setzen Sie HOST auf https://api.multitel.net und lesen .response.id statt .data.id.

Anfragen mit unklarem Ergebnis sicher wiederholen

Läuft eine Übermittlung in einen Timeout oder liefert sie 429 oder einen 5xx-Status, senden Sie dieselben Eingaben mit demselben Idempotenzschlüssel erneut. Eine Antwort beider Hosts kann verloren gehen oder nach Annahme des Auftrags durch einen Fehler ersetzt werden. Erneutes Senden mit demselben Schlüssel gibt den Auftrag zurück, falls er existiert. Wird ein Schlüssel mit anderen Eingaben wiederverwendet, folgt 409 idempotency_conflict. Manche Fehler wiederholen sich bei jedem Versuch, etwa 503 bei einem deaktivierten kostenpflichtigen Dienst oder 500 bei einer nicht lesbaren Audiodatei. Brechen Sie nach einigen Versuchen ab.

Ein neuer Schlüssel hat je nach Dienst unterschiedliche Auswirkungen.

• Bei der Spracherkennung erstellt ein neuer Schlüssel einen neuen Auftrag, der bei erfolgreicher Verarbeitung gesondert berechnet wird. Der ursprüngliche Schlüssel gibt weiterhin den ursprünglichen Auftrag zurück, auch nach einer Aktualisierung der Verarbeitung.
• Bei der Übersetzung gibt ein neuer Schlüssel mit identischem Inhalt ohne neue Gebühren einen passenden wartenden, laufenden, abgeschlossenen oder auf Zahlung wartenden Auftrag zurück. Neue Arbeit entsteht, wenn der frühere Auftrag fehlgeschlagen ist oder sich die Verarbeitungsversion geändert hat. Ein erneuter Übersetzungsversuch mit dem ursprünglichen Schlüssel liefert nach einer Änderung der Verarbeitungsversion 409. Bewahren Sie daher die ursprüngliche Auftrags-ID auf und lesen Sie den Auftrag direkt.

Ergebnis nach Aufladung des Guthabens freigeben

Für einen Auftrag mit Status awaiting_payment laden Sie Guthaben auf, sodass es mindestens dem Wert costUsd des Auftrags entspricht, aufgerundet auf das nächste Vielfache von $0.00001. Senden Sie anschließend POST /v3/SERVICE/JOB_ID/settle. Abbuchungen erfolgen in ganzen Schritten von $0.00001 und enthalten übertragene Restbeträge früherer Aufträge desselben Dienstes. Der abgebuchte Betrag kann costUsd daher um weniger als $0.00001 übersteigen. Senden Sie auf api.multi.tel JSON {} oder einen leeren Inhalt; jede Eigenschaft im Anfrageinhalt wird mit 400 abgewiesen. api.multitel.net ignoriert den Anfrageinhalt. Die Begleichung gibt das gespeicherte Ergebnis frei, ohne Spracherkennung oder Übersetzung erneut auszuführen. Die Antwort enthält den Auftrag; prüfen Sie, ob sein Status completed lautet. Reicht das Guthaben weiterhin nicht aus, bleibt der Auftrag im Status awaiting_payment und die Antwort lautet weiterhin HTTP 200.

Bei der Spracherkennung gibt die Begleichung eines bereits abgeschlossenen Auftrags diesen mit duplicate: true zurück. Für einen wartenden, laufenden oder fehlgeschlagenen Auftrag folgt 409 transcription_not_awaiting_payment. Bei der Übersetzung wird ein Auftrag in jedem anderen Status unverändert zurückgegeben. Die Begleichung ist nur bei aktivierter kostenpflichtiger Verarbeitung verfügbar, andernfalls folgt 503. Auf Zahlung wartende Aufträge zählen zu den reservierten Kosten und können bei Prepaid-Konten neue kostenpflichtige Übermittlungen mit 402 blockieren, bis sie beglichen sind.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Nutzung prüfen

Verwenden Sie GET /v3/SERVICE/usage. Die optionalen Parameter from und to sind UTC-Daten im Format YYYY-MM-DD. Beide Grenzdaten sind eingeschlossen. Ohne Angabe ist from standardmäßig das Datum 30 Tage vor heute und to das heutige Datum (UTC). to darf nicht vor from liegen. Die Daten dürfen höchstens 366 Tage auseinanderliegen, also bis zu 367 eingeschlossene Datumswerte. Ungültige Kalendertage, ein umgekehrter oder längerer Zeitraum und andere Abfrageparameter auf api.multi.tel liefern 400.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Die Antwort enthält mode, currency (USD), from, to und days, eine Liste mit den neuesten Einträgen zuerst.

• Einträge der Spracherkennung werden nach Datum und Quelle gruppiert. Sie enthalten date, source (api oder hpbx für Hosted-PBX-Aufzeichnungen), files, audioSeconds, billedSeconds, accruedUsd und debitedUsd.
• Übersetzungseinträge werden nach Datum, Quelle und Engine gruppiert. Sie enthalten date, source, engine, jobs, sourceCharacters, accruedUsd und debitedUsd.

accruedUsd ist der genaue Betrag mit neun Nachkommastellen, debitedUsd der abgebuchte Betrag mit fünf. Die Nutzung wird am UTC-Datum der Begleichung der jeweiligen Auftragsgebühr erfasst. Wartende, laufende, fehlgeschlagene und auf Zahlung wartende Aufträge erscheinen daher nicht.

Limits

Jedes Konto kann insgesamt höchstens 50 offene Aufträge für Spracherkennung und Übersetzung haben: wartend, laufend oder auf Zahlung wartend, einschließlich der Verarbeitung von Hosted-PBX-Aufzeichnungen. Bei Erreichen dieses Limits oder der Gesamtkapazität des Dienstes liefern Übermittlungen 429 transcription_queue_full oder translation_queue_full. api.multi.tel begrenzt außerdem jede Client-IP-Adresse auf 300 Anfragen pro Minute über alle Anfragen an diesen Host hinweg. Dieses Limit liefert 429 mit Headern zur Ratenbegrenzung und einem reinen Textinhalt statt der JSON-Fehlerstruktur.

Anfragefehler behandeln

Auf dem primären Host liefern Fehler einen HTTP-Fehlerstatus und JSON mit status: "error", code, message und requestId. Jede Antwort enthält außerdem einen Header X-Request-ID. Sie können einen eigenen Wert angeben; Werte über 128 Zeichen werden gekürzt. Der Kompatibilitätshost liefert nur den Fehlercode in response.code. Protokollieren Sie die Anfrage-ID, sofern vorhanden, und den Fehlercode. Nehmen Sie keine Audiodaten, Texte oder Zugangsdaten in die Protokolle auf.

Häufige Statuscodes:

Richten Sie sich nach dem zurückgegebenen Fehlercode, statt für jeden Validierungsfehler denselben Status anzunehmen.

Warten Sie bei 429 oder 503 und versuchen Sie es mit zunehmenden Abständen und demselben Übermittlungsschlüssel erneut. Beachten Sie Retry-After, falls vorhanden. Beheben Sie bei ungültigen Eingaben oder Zugangsdaten zuerst die Ursache. Senden Sie nicht wiederholt neue Schlüssel, solange frühere Aufträge noch warten.