Referenz zu waafir-translate
Der Server waafir-translate stellt einem verbundenen KI-Client die
Übersetzung von Waafir in zwei Formen bereit:
translate_text— ein Textausschnitt, inline und synchron übersetzt.translate_file/translate_file_status— ein ganzes Dokument in einem Datenraum, übersetzt von derselben layouterhaltenden Pipeline, die auch die Produktfunktion KI-Übersetzung verwendet.
Verbindung: https://app.waafir.io/api/mcp/waafir oder der Bereichsserver
https://app.waafir.io/api/mcp/waafir-translate; die Tool-Namen sind auf beiden gleich — siehe
Einrichtung. translate_text und
translate_file_status benötigen ein
PAT mit dem Scope read (oder höher); translate_file benötigt
write, weil das Starten einer Dokumentübersetzung dauerhafte Datensätze anlegt und
kostenpflichtige Übersetzungsrechenleistung verbraucht.
translate_text
Übersetzt einen kurzen Text in eine Zielsprache. Der Aufruf ist synchron und arbeitet nach dem Prinzip Text rein / Text raus. Lassen Sie die Ausgangssprache weg, damit sie automatisch erkannt wird; die erkannte (oder angegebene) Ausgangssprache wird zurückgegeben, sodass Sie sie bestätigen können.
Eingaben
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
text | string | ja | Der zu übersetzende Text, 1–10.000 UTF-8-Bytes. |
target_lang | string | ja | Code der Zielsprache, z. B. fr, ar, es. |
source_lang | string | nein | Code der Ausgangssprache. Weglassen für automatische Erkennung. |
Ausgabe
{ translated_text, detected_source_lang }translated_text— der in die Zielsprache übertragene Text.detected_source_lang— die verwendete Ausgangssprache: die von Ihnen angegebene oder die automatisch erkannte, wennsource_langweggelassen wurde.
Voraussetzungen: ein kostenpflichtiger Tarif und aktivierte KI-Funktionen Ihrer Organisation (standardmäßig eingeschaltet; ein Organisationsadministrator kann sie unter Einstellungen → KI & Integrationen ausschalten). Aufrufe werden außerdem abgelehnt, sobald Ihre Organisation ihr tägliches KI-Nutzungslimit erreicht hat oder solange Waafir die Funktion pausiert hat; die Fehlermeldung nennt den Grund.
Größenlimit
Da das Tool der synchrone Weg ist, ist text auf 10.000 UTF-8-Bytes
pro Aufruf begrenzt. Eingaben über diesem Limit liefern einen eindeutigen Fehler, statt
stillschweigend gekürzt zu werden. Für größere Inhalte — ganze Dokumente — verwenden Sie die
Dokumentübersetzung, die für
Dateien entwickelt wurde und deren Layout erhält.
translate_file
Startet die Übersetzung eines ganzen Dokuments in einem Datenraum. Die Dokumentübersetzung ist
asynchron — der Aufruf kehrt zurück, sobald der Auftrag in die Warteschlange gestellt ist, und Sie fragen
translate_file_status nach dem Ergebnis ab.
Eingaben
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
file_id | string | ja | Die UUID der Datei. |
target_lang | string | ja | Code der Zielsprache — eine der 28 Sprachen, in die das Produkt Dokumente übersetzt. |
retry | boolean | nein | Führt eine Übersetzung erneut aus, die zuvor fehlgeschlagen ist. Wird bei abgeschlossenen oder laufenden Übersetzungen ignoriert. |
Ausgabe
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued,in_progress,already_translatedoderfailed.enqueued— ob dieser Aufruf tatsächlich Arbeit gestartet hat. Prüfen Sie das: Das Tool führt eine bereits abgeschlossene oder laufende Übersetzung nicht erneut aus, daher liefert ein zweiter Aufrufenqueued: falseund kostet nichts.previous_status— der Zustand der Übersetzung vor diesem Aufruf, gelesen aus dem Datensatz selbst.delete_with— wie Sie die Übersetzung entfernen und die Datei in ihren Originalzustand zurückversetzen.
Es übersetzt nicht zweimal dasselbe
Anders als beim wiederholten Klicken auf „Übersetzen“ im Produkt lehnt translate_file es ab,
erneut einzureihen, solange eine Übersetzung derselben Datei in dieselbe Sprache bereits
queued, translating oder finalizing ist, und es lehnt ab, eine fehlgeschlagene
Übersetzung erneut auszuführen, sofern Sie nicht ausdrücklich retry: true übergeben. Das ist gewollt: Eine
Wiederholungsschleife, die jedes Mal neu einreiht, würde bei jedem Durchlauf echte
Übersetzungsrechenleistung verbrauchen.
Voraussetzungen: ein kostenpflichtiger Tarif, aktivierte KI-Funktionen Ihrer Organisation (standardmäßig eingeschaltet; ein Organisationsadministrator kann sie unter Einstellungen → KI & Integrationen ausschalten) und die Berechtigung, die Datei zu lesen und herunterzuladen.
Eine Datei, die noch geprüft wird. Ist die Datei ein neuer Upload oder eine
neue Version, deren Prüfung Waafir noch nicht abgeschlossen hat, antwortet
translate_file mit UNAVAILABLE, error.reason: "ACTIVATION_PENDING" und der
Meldung This file is still being checked. Try again shortly. Es wird nichts in
die Warteschlange gestellt; rufen Sie das Tool nach kurzer Wartezeit erneut auf.
translate_file_status
Prüft eine Dokumentübersetzung und liefert, sobald sie fertig ist, eine kurzlebige Download-URL für die übersetzte Datei.
Eingaben
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
file_id | string | ja | Die UUID der Datei. |
target_lang | string | ja | Die Sprache, in der die Übersetzung angefordert wurde. |
Ausgabe
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found,queued,translating,finalizing,completed,failedoderstale.stalebedeutet, dass die Quelldatei auf eine frühere Version zurückgesetzt wurde, nachdem diese Übersetzung erstellt wurde, sodass die Übersetzung nicht mehr zum Dokument passt und nicht mehr ausgeliefert wird — für sie wird keinedownload_urlausgestellt. Rufen Sietranslate_fileerneut auf, um eine neue zu erstellen. Behandeln Sie jeden Status, den Sie nicht kennen, als „nicht fertig“ und nicht als Fehler.download_url— nur vorhanden, wenn die übersetzte Datei fertig ist, Ihnen gefahrlos ausgeliefert werden kann und beim Token Dokumentinhalt lesen aktiviert ist (Persönliche Zugriffstokens). Sie liefert dieselbe Kopie wie der Download im Browser, mit Wasserzeichen, wo der Raum Downloads mit Wasserzeichen versieht, und läuft nach wenigen Minuten ab. Höchstens 10 Links pro Minute und Token.- Ohne Dokumentinhalt lesen erhalten Sie weiterhin den
status, unddownload_withheld_reasonistcontent_grant_required. download_withheld_reason— stattdownload_urlvorhanden, wenn die Datei fertig ist, aber zurückgehalten wird. Der häufigste Fall: Das Dokument wurde geschwärzt, und die angeforderte Übersetzung wurde aus dem Original erstellt, sodass ihre Auslieferung Inhalte preisgeben würde, die die Schwärzung entfernt hat. Führen Sietranslate_fileerneut aus, um eine schwärzungssichere Übersetzung zu erstellen.
Jede von diesem Tool ausgestellte Download-URL wird im Audit-Trail Ihrer Organisation als Datei-Download protokolliert, dem Token zugeordnet und als von einem KI-Client stammend gekennzeichnet — genau so, wie ein Download über das Produkt protokolliert wird.