Document Translation API

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Ein Angebot mit cURL

Speichern Sie das obige Angebots-JSON als payload.json und legen Sie DOCUMENT_TRANSLATOR_API_KEY in Ihrer Shell fest. Dieser Befehl fordert nur ein Angebot an. Um zu starten, senden Sie das Start-JSON mit der zurückgegebenen Angebots-ID und der identischen Nutzlast an den Übersetzungsendpunkt.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

Verwenden Sie in PowerShell curl.exe und $env:DOCUMENT_TRANSLATOR_API_KEY. Schreiben Sie den Befehl in eine Zeile, statt die oben gezeigten Backslashes zur Zeilenfortsetzung zu verwenden.

Übersetzungsguthaben und API-Schlüssel

Für jedes API-Dokument wird im Rahmen der Limits ein Kontoguthaben reserviert. Bei strikter Ausgabe wird nur abgerechnet, wenn das Ergebnis validiert und bereit ist; bei fehlgeschlagenen oder abgebrochenen, nicht abgeschlossenen Aufträgen wird die Reservierung freigegeben. Bei bestmöglicher Ausgabe können kleine Lücken das vereinbarte Guthaben verbrauchen, während größere Lücken oder kritische Fehler zur Freigabe führen. Prüfen Sie outcome.creditOutcome und outcome.completion, statt davon auszugehen, dass jedes fertige Ergebnis berechnet wurde.

Erstellen Sie bis zu fünf aktive API-Schlüssel pro Konto. Schlüssel werden nur einmal angezeigt, als Hashes gespeichert und können unter „Konto“ widerrufen werden. Ein aktiver Schlüssel kann auf die kostenpflichtigen Übersetzungen des jeweiligen Kontos zugreifen, einschließlich Aufträgen, die mit einem anderen Schlüssel desselben Kontos erstellt wurden. Schlüssel berechtigen weder zur Anmeldung noch zu Zahlungen.

Erneute Versuche und unterbrochene Anfragen

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

Verwenden Sie nach einem unklaren Startvorgang dieselbe Angebots-ID, denselben Payload und denselben Idempotenzschlüssel erneut. Identische Wiederholungen geben den bestehenden Auftrag zurück, ohne erneut abzurechnen. Bei geändertem Payload oder wenn ein Schlüssel für ein anderes Angebot verwendet wird, wird 409 zurückgegeben. Auftrags- und Idempotenzmetadaten werden nach Beendigung sieben Tage lang aufbewahrt.

Ein fortsetzbarer fehlgeschlagener Auftrag kann erneut gestartet werden, solange sein Quelltext verfügbar ist. Beim erneuten Versuch bleibt die Auftrags-ID erhalten und bereits verarbeitete Textabschnitte werden wiederverwendet. Pro Auftrag sind höchstens drei Verarbeitungsversuche möglich. Fehlgeschlagene Downloads können über den Ergebnis-Endpunkt erneut versucht werden, ohne eine weitere Übersetzung zu starten.

Abfragen und Downloads

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

Der Batch-Status akzeptiert höchstens 100 IDs und gibt { jobs: [...] } mit ausschließlich autorisierten, nicht gelöschten Aufträgen zurück. Fragen Sie den Status während der Verarbeitung etwa alle fünf Sekunden und während der Warteschlange alle fünfzehn Sekunden ab. Verteilen Sie die Batches fair, wenn Sie mehr als 100 Aufträge wiederherstellen. Unterbrechen Sie die Statusabfrage in ausgeblendeten Tabs und beenden Sie sie bei einem Endstatus oder einem permanenten Autorisierungsfehler.

Sobald der Status „bereit“ lautet, rufen Sie das Ergebnis mit derselben Kontoberechtigung ab. Es enthält die Zuordnung der übersetzten Segmente zur lokalen Rekonstruktion. Ergebnisse sind nach Abschluss 24 Stunden lang verfügbar; ungültige Eingaben laufen eine Stunde nach ihrer Erstellung ab. Abgelaufene Ergebnisse geben 410 zurück. Gelöschte oder nicht zugängliche Aufträge geben 404 zurück.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

Speichern Sie eine fertige Datei mit PUT und ihrem Binärinhalt, Content-Length und passendem Content-Type. Unterstützte Dateiendungen sind docx, pptx, xlsx, pdf, txt und md; pro Format kann eine Datei gespeichert werden. Die Ausgabe darf höchstens 50 MB groß sein. Bei erneutem Speichern nach einem erfolgreichen Vorgang bleibt die vorhandene Datei erhalten. GET lädt die gespeicherte Datei herunter; savedFormats im Auftragsstatus listet verfügbare Formate auf. Beim Speichern und Herunterladen gelten dieselben Auftragsberechtigungen; es werden keine zusätzlichen Guthaben verbraucht und die 24-Stunden-Frist wird nicht verlängert.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE bricht nicht abgeschlossene Vorgänge ab oder entfernt verfügbare Texte und gespeicherte Dateien. Das Löschen eines abgeschlossenen Ergebnisses erstattet keine Guthaben und verlängert den Downloadzeitraum nicht. In dieser Version gibt es keine Webhooks für abgeschlossene Vorgänge.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

Kontostand und Verlauf

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

Der Verlauf ist auf den aktuellen Kontoinhaber beschränkt und verwendet den zurückgegebenen Paginierungscursor. Der Kontostand-Endpunkt verwendet die Browser-Kontositzung und gibt nur grundlegende Anmelde- und Kontostandsinformationen zurück. Während eines ausstehenden Checkouts rufen Sie ihn alle fünf Sekunden ab, höchstens zehnmal. Pausieren Sie, solange die Seite verborgen ist, und beenden Sie die Abfrage, sobald Guthaben gutgeschrieben wird oder die Abmeldung erfolgt.

n8n, Make und Zapier

Verwenden Sie einen HTTP-Anforderungsschritt mit einem geheimen Bearer-Zugangsschlüssel. Extrahieren Sie zuerst den Text und senden Sie das JSON-Payload per POST an den Angebotsendpunkt. Senden Sie anschließend die Angebots-ID, das Payload und einen stabilen Idempotenzschlüssel mit 16–80 Zeichen per POST an den Übersetzungsendpunkt. Fügen Sie eine Verzögerung ein und rufen Sie den Status per GET ab, bis der Auftrag abgeschlossen ist. Rufen Sie dann das Ergebnis ab und setzen Sie den übersetzten Text wieder zusammen oder speichern Sie ihn. Speichern Sie die Angebots-ID und den Wiederholungsschlüssel in Ihrem Workflow-Datensatz. Ein spezieller Connector oder Multipart-Upload ist nicht erforderlich.

Limits und Fehler

• Bis zu 50.000 Wörter im Ausgangstext, 400.000 extrahierte Zeichen und 12.000 Textsegmente pro Dokument. Der Browser begrenzt außerdem Originaldateien auf 25 MB, PDFs auf 300 Seiten und PowerPoint-Dateien auf 300 Folien. Dies sind Ausgangslimits, die vor Beginn der Übersetzung geprüft werden.
• Bis zu 100 Dokumente pro Konto können in der Warteschlange stehen oder verarbeitet werden. API-Schlüssel teilen sich ein Limit von 120 Angebotsanfragen pro Minute und fünf neuen Aufträgen oder Wiederholungsversuchen alle zehn Sekunden pro Konto. Beachten Sie Retry-After bei 429-Antworten und verwenden Sie bei vorübergehenden Fehlern eine begrenzte Backoff-Strategie. Häufigeres Abrufen des Status beschleunigt die Verarbeitung nicht.
• Bei strikter Ausgabe werden fehlende, doppelte oder fehlerhaft formatierte Übersetzungssegmente vor der Abrechnung abgelehnt. Bei bestmöglicher Ausgabe bleiben validierte Übersetzungen erhalten; in ungelösten Abschnitten kann der Originaltext stehen bleiben. outcome und issues beschreiben das Ergebnis. Dokumentinhalten werden keine Wasserzeichen oder Hinweise auf den Dienst hinzugefügt.

Fehler enthalten eine Fehlermeldung und einen Code. 400 steht für ungültige Eingaben, 401 für ungültige Autorisierung, 402 für unzureichende Credits, 404 für einen nicht verfügbaren Auftrag, 409 für einen widersprüchlichen Kostenvoranschlag oder Status, 410 für den Ablauf der Gültigkeit, 429 für eine Raten- oder Kapazitätsbegrenzung und 503 für einen nicht verfügbaren Dienst.

Wir speichern eine private Kopie Ihres Originaldokuments bis 24 Stunden nach Abschluss der Übersetzung, damit Sie Ihre Downloads wiederherstellen können. Durch Löschen der Übersetzung können Sie die Kopie früher entfernen. Nur der extrahierte Text wird an unseren Übersetzungsanbieter gesendet. Datenschutzdetails