Dokumentübersetzungs-API | Document-Translator.com

Schnellstart

Melden Sie sich an und erstellen Sie einen API-Schlüssel. Speichern Sie den Schlüssel in der Geheimniskonfiguration Ihres Servers. Für API-Übersetzungen ist vorausbezahltes Guthaben erforderlich; das kostenlose Kontingent im Browser gilt nicht.
Extrahieren Sie den Text des Dokuments in Ihrem Client, weisen Sie jedem Segment eine stabile ID zu und fordern Sie einen Kostenvoranschlag an. Bewahren Sie das Originaldokument lokal für die Wiederherstellung auf.
Beginnen Sie mit der Angebots-ID, einem stabilen Idempotenzschlüssel und derselben Payload. Rufen Sie den Status ab, bis die Übersetzung fertig ist, laden Sie die übersetzten Segmente herunter und erstellen Sie Ihr Dokument neu.

Die Übersetzungs-API nimmt extrahierten Text entgegen und gibt übersetzte Segmente zurück. Erstellen Sie die fertige Datei in Ihrem Client und speichern Sie die übersetzte Datei bei Bedarf für einen späteren Download. Laden Sie die Originaldatei nicht hoch.

Angebot erstellen

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

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

Die Antwort enthält die Angebots-ID, die Wortzahl der Ausgangssprache, die genauen Guthabenkosten und den Ablaufzeitpunkt. Angebote sind zehn Minuten lang gültig. Durch eine Angebotsanfrage werden keine Guthaben reserviert und keine Dokumenttexte gespeichert.

Übersetzung starten

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

Senden Sie beim Start erneut die ursprüngliche Payload des Angebots. Der Server prüft vor dem Speichern des Textes oder dem Reservieren von Guthaben den Eigentümer und den kanonischen Hash. Die Reihenfolge der JSON-Objektschlüssel spielt keine Rolle. Änderungen am Text, an der Segmentreihenfolge, am Format, Fingerprint oder an den Sprachen erfordern ein neues Angebot.

Erstellen Sie einen Workflow zur Dokumentübersetzung

Extrahieren Sie den Text und erstellen Sie die Downloads in Ihrer Anwendung neu. Senden Sie die oben angezeigte Nutzlast und verwenden Sie anschließend die zurückgegebenen Segment-IDs, um jede Übersetzung wieder in das zugehörige Dokument einzufügen.

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCX behält unterstützte Originalstrukturen bei. Beim PDF-Export wird der Text neu umbrochen; das ursprüngliche Seitenlayout wird nicht exakt reproduziert. Gescannte oder passwortgeschützte PDFs werden nicht unterstützt. Prüfen Sie wichtige Übersetzungen und Formatierungen vor der Verwendung.

Übersetzungsguthaben und API-Schlüssel

Jedes API-Dokument verbraucht innerhalb der Uploadlimits ein Kontoguthaben. Guthaben werden zu Beginn reserviert und erst abgezogen, wenn eine vollständige, validierte Übersetzung bereitsteht. Anmeldebonusguthaben können über die API verwendet werden; das tägliche kostenlose Kontingent ist nur auf der Website verfügbar.

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

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 zehn 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 zehn 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.

Speichern Sie eine fertige Datei mit PUT und ihrem Binärinhalt, Content-Length und passendem Content-Type. Unterstützte Dateiendungen sind docx, 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.

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.

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.

Limits und Fehler

Bis zu 50.000 Wörter im Ausgangstext, 400.000 extrahierte Zeichen und 12.000 Textsegmente pro Dokument. Der Browser begrenzt Originaldateien außerdem auf 25 MB und PDFs auf 100 Seiten.
Bis zu 100 Dokumente pro Konto können in der Warteschlange stehen oder verarbeitet werden. Starts und Wiederholungsversuche unterliegen denselben Ratenbegrenzungen. Beachten Sie bei 429-Antworten den Retry-After-Header und verwenden Sie bei vorübergehenden Fehlern ein begrenztes Backoff.
Fehlende, doppelte oder fehlerhaft formatierte übersetzte Segmente führen dazu, dass die Validierung vor der Veröffentlichung und Abrechnung fehlschlägt. Bei fehlgeschlagenen oder abgebrochenen, nicht abgeschlossenen Aufträgen werden reservierte Guthaben freigegeben.

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.

Die Originaldokumente verbleiben auf Ihrem Gerät. Extrahierter Text wird von unserem Übersetzungsanbieter verarbeitet; gespeicherte übersetzte Dateien werden privat zum Herunterladen abgelegt. Temporäre Daten werden nach einem Zeitplan gelöscht; zusätzlich gelten die Aufbewahrungsrichtlinien des Anbieters. Datenschutzdetails

Document Translation API