API zur Textübersetzung

Diese API übersetzt Text als Aufträge in einer Warteschlange, mit einer Zielsprache pro Auftrag. Sende Text, 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 ä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/translate anstelle von /v3/translate verfügbar. Auf api.multitel.net verwendest du die Pfade mit /v3/translate.

Die Antwort mit den Dienstinformationen enthält enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages und ratesNanosPerCharacter. cpuLanguages listet die für Standardübersetzungen akzeptierten Basissprachcodes auf. ratesNanosPerCharacter gibt für jede Engine den konfigurierten Preis pro Codepunkt im Ausgangstext in Milliardstel US-Dollar an: Ein Wert von 5000 entspricht $5 pro Million Codepunkte. Die Antwort gibt nicht an, ob die erweiterte Übersetzung derzeit verfügbar ist; eine erweiterte Schätzung liefert 503, wenn sie nicht verfügbar ist. Der Abruf ist kostenlos.

Text übersetzen

Sende JSON mit Content-Type: application/json an POST https://api.multi.tel/v3/translate. Jeder Auftrag hat eine Zielsprache. Reiche daher für jedes Ziel einen separaten Auftrag ein.

Sprach-/Regionscodes sind BCP-47-Tags mit 2 bis 63 Buchstaben, Ziffern und Bindestrichen. Sie werden kanonisiert: en-us wird also als en-US gespeichert. Ungültige Tags sowie und, mul oder zxx ergeben 400 mit invalid_translation_language. Die Standardverfügbarkeit wird anhand der Basissprache geprüft; nb und nn zählen dabei als no. Ein regionales Ziel wie fr-CA wird akzeptiert und gespeichert. Die Standardausgabe folgt jedoch der Basissprache und spiegelt die Region nicht garantiert wider.

Begrenze den Anfragetext auf diesem Host auf 128 KiB. Sende Text als UTF-8, statt jedes Nicht-ASCII-Zeichen mit einer \u-Sequenz zu maskieren. Dies kann eine Anfrage mit 20,000 Zeichen über das Limit bringen.

Der Anfragetext akzeptiert nur diese vier Felder. Jede andere Eigenschaft wird mit 400 und invalid_translation_request abgelehnt, einschließlich idempotency_key, Eigentümer-IDs, Kennzeichen für kostenlose Verarbeitung und Segmentarrays.

Idempotenz und Wiederverwendung

Jede Einreichung benötigt einen Header Idempotency-Key mit 1 bis 190 Zeichen. Verwende ASCII-Buchstaben, Ziffern, -, _, . und : ohne führende oder nachgestellte Leerzeichen. 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 Übersetzung, über beide Hosts und alle Zugangsdaten deines Kontos hinweg.

• Derselbe Schlüssel mit demselben Text, denselben kanonisierten Sprachen und derselben Engine liefert den vorhandenen Auftrag mit HTTP 200 und duplicate: true zurück, ohne weitere Berechnung.
• Derselbe Schlüssel mit anderem Text, anderen Sprachen oder einer anderen Engine liefert 409 mit idempotency_conflict. Derselbe Schlüssel ergibt auch 409, wenn sich die Verarbeitungsversion seit der Erstellung seines Auftrags geändert hat. Rufe in diesem Fall den ursprünglichen Auftrag über seine ID ab, statt ihn erneut einzureichen.
• Ein neuer Schlüssel mit demselben Text, denselben kanonisierten Sprachen und derselben Engine liefert den vorhandenen Auftrag mit HTTP 200 und duplicate: true ohne erneute Verarbeitungskosten zurück, wenn ein Auftrag mit diesem Inhalt und der aktuellen Verarbeitungsversion wartet, verarbeitet wird, abgeschlossen ist oder auf Zahlung wartet. Ein wiederverwendeter Auftrag, der auf Zahlung wartet, muss weiterhin abgerechnet werden. Fehlgeschlagene Aufträge werden nicht wiederverwendet: Ein neuer Auftrag wird erstellt und bei Abschluss berechnet.

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

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

Ein neuer Auftrag liefert HTTP 202. Der Beispieltext hat 57 Codepunkte und kostet bei $5 pro Million Codepunkte somit $0.000285. Eine gekürzte Antwort (die Kennung ist ein Beispiel):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

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, und 429 mit translation_queue_full bei zu vielen offenen Aufträgen deines Kontos oder des Dienstes. In diesen Fällen wird 503 zurückgegeben:

• paid_translation_not_enabled bei deaktivierter kostenpflichtiger Übersetzung.
• translation_unavailable für eine erweiterte Anfrage, wenn die erweiterte Übersetzung nicht verfügbar ist.
• translation_pricing_unavailable wenn für die gewählte Engine kein Tarif konfiguriert ist.

Wiederhole Anfragen mit den Antworten 429 und 503 später mit demselben Schlüssel.

Qualität wählen

Langer Text wird in kleineren Teilen verarbeitet und wieder zusammengesetzt. Zeilenumbrüche und Abstände können sich ändern und ein Satz kann über eine Verarbeitungsgrenze hinweg Kontext verlieren. Bewahre den Originaltext auf und prüfe das zusammengesetzte Ergebnis. Die Standardübersetzung verwendet die Basissprache eines regionalen Tags; das Akzeptieren und Speichern eines Tags garantiert keine regionale Formulierung.

Die Standardübersetzung läuft auf CPU-Workern. Die erweiterte Übersetzung sendet Text an den konfigurierten externen KI-Dienst. Auch dessen Ausgabe muss geprüft werden. Der Dienst garantiert nicht, dass eine Engine für jedes Sprachpaar oder jeden Texttyp genauer ist.

Die Standardübersetzung ist ein Entwurf, dessen Qualität und Verarbeitungszeit vom Sprachpaar abhängen. Die erweiterte Übersetzung ist für kontextabhängige Texte gedacht, erfordert aber weiterhin eine Prüfung wichtiger Namen, Zahlen, Verneinungen und Zusagen. Keine der Optionen behebt Fehler, die bereits im ursprünglichen Transkript enthalten sind. Bewahre deshalb das Original zum Vergleich auf.

Verwende GET /v3/translate auf demselben API-Host, um aktuelle Verfügbarkeit, unterstützte Standardsprachen und konfigurierte Tarife zu prüfen. Eine Standardanfrage, deren Ausgangs- oder Zielbasissprache nicht in cpuLanguages steht, liefert 422 mit translation_language_pair_unavailable. Wird source_language angegeben und hat es dieselbe Basissprache wie das Ziel, liefert die Anfrage 409 mit translation_same_language statt einen Auftrag zu erstellen. Die erweiterte Übersetzung wird separat aktiviert: Solange sie nicht verfügbar ist, liefern erweiterte Einreichungen und Schätzungen 503.

Zuerst schätzen

Sende auf api.multi.tel denselben JSON-Anfragetext an POST /v3/translate/estimate. Ein Idempotenzschlüssel ist nicht erforderlich. Eine Schätzung führt dieselbe Validierung einschließlich der Prüfungen für 422 und 409 durch, erstellt aber keinen Auftrag, übersetzt keinen Text, reserviert kein Guthaben, prüft deinen Kontostand nicht und belastet dein Konto nicht. Sie liefert HTTP 200 mit estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd und costUsd unter data. Im obigen Beispiel beträgt costUsd bei Standardtarif 0.000285000. Ist die erweiterte Übersetzung nicht verfügbar, liefert eine erweiterte Schätzung 503 mit service_unavailable. Schätzungen verwenden den aktuell konfigurierten Tarif. Der Tarif eines Auftrags wird bei seiner Erstellung festgelegt; die Abrechnung verwendet diesen Tarif.

Übersetzung abrufen

Eine neue Einreichung liefert HTTP 202, ein vorhandener oder wiederverwendeter Auftrag HTTP 200. Bewahre data.id auf und verwende den gemeinsamen Auftragsablauf. Das Auftragsobjekt enthält diese Felder:

• id, status, engine, sourceLocale und targetLocale.
• sourceCharacters, costUsd, costIsEstimate und pricePerMillionCharactersUsd.
• progress und createdAt.
• modelVersion, eine opake Zeichenfolge für die Verarbeitungsversion.
• duplicate bei Antworten mit wiederverwendeten Aufträgen.
• failureCode bei fehlgeschlagenen Aufträgen: translation_failed, translation_timeout, input_failed oder worker_lease_lost.

Ein fehlgeschlagener Auftrag zeigt für costUsd den Betrag von null US-Dollar an.

Ein abgeschlossener Auftrag enthält data.result mit sourceLocale (leer, wenn keine Ausgangssprache angegeben wurde), targetLocale, dem übersetzten text (Segmenttexte mit Zeilenumbrüchen verbunden) und segments. Für über diese API eingereichten Text enthält segments einen Eintrag mit dem übersetzten text und der Zielsprache language. Ergebnisse von Aufträgen, die auf Zahlung warten, werden bis zur Abrechnung zurückgehalten.

api.multitel.net verwenden

Der Kompatibilitätsendpunkt POST https://api.multitel.net/v3/translate akzeptiert dieselben JSON-Felder und denselben Header Idempotency-Key. Fehlt der Header, akzeptiert er auch eine Zeichenfolge idempotency_key im JSON-Anfragetext. Jedes andere zusätzliche Feld wird mit 400 und unsupported_translation_option abgelehnt. Auf diesem Host darf der rohe Anfragetext bis zu 256,000 Bytes groß sein. Text mit mehr als 20,000 Codepunkten ergibt 413 mit translation_too_large statt 400. Ein leeres source_language wird als ausgelassen behandelt. Eine 429-Antwort enthält Retry-After: 15. Dieser Host gibt außerdem diese Fehler zurück:

• 400 json_body_required bei fehlendem Anfragetext, ungültigem JSON oder einem JSON-Skalar. Sende ein JSON-Objekt.
• 400 invalid_translation_options wenn text, target_language oder engine fehlt, leer oder keine Zeichenfolge ist oder wenn source_language keine Zeichenfolge ist.
• 400 invalid_translation_text bei Text, der nur aus Leerraumzeichen besteht.
• 400 invalid_translation_engine bei einer unbekannten Engine.
• 400 idempotency_key_required bei einem fehlenden, leeren oder zu langen Schlüssel oder wenn idempotency_key keine Zeichenfolge ist.
• 400 invalid_job bei einer falsch formatierten Auftrags-ID.

Antworten des Übersetzungsdienstes auf diesem Host verwenden die äußere Struktur {"status":{"code":HTTP_STATUS},"response":{...}}, wobei status ein Objekt ist. Lies die Auftrags-ID aus response.id und das fertige Ergebnis aus response.result. Fehler setzen den Code in response.code ohne Meldung oder Anfrage-ID. 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. Aufträge werden mit dem primären Host geteilt. Verwende aber für Statusabfragen, Abrechnung und Nutzung denselben Host, damit dein Parser zur äußeren Antwortstruktur passt. Dieser Host akzeptiert dieselben JSON-Felder auch unter /v3/translate/estimate ohne Idempotenzschlüssel; seine Schätzung steht unter response.