Zum Inhalt springen

Integrieren Sie Dokumenten-Workflows in Ihre App

Vom Hochladen einer Datei über die Übersetzung, die Fortschrittsprüfung bis zum Herunterladen des Ergebnisses. Jeder Schritt wird in der Reihenfolge Ihrer Integration erläutert, mit Schnittstellen für das Dateimanagement, die Dokumentverarbeitung sowie Audio- und Videodienste.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API-Schlüssel-Authentifizierung · Dateiübersetzungen werden als asynchrone Aufträge ausgeführt

Diese Website beschreibt die Cloud HTTP-API.

01 Beginnen Sie mit einer Anfrage, die keine Credits kostet

Abschnitt betitelt „01 Beginnen Sie mit einer Anfrage, die keine Credits kostet“

Stellen Sie sicher, dass Ihr Schlüssel und Ihr Netzwerk funktionieren, bevor Sie Dateien hochladen. Eine Guthabenprüfung kostet keine Credits und erzeugt keinen Übersetzungsjob.

  1. API-Schlüssel abrufen

    Melden Sie sich in der API-Konsole an und erstellen Sie einen Schlüssel, der mit sk_ beginnt. Verwenden Sie für jede Anwendung einen separaten Schlüssel und legen Sie ein Budget fest.

    Ein Schlüssel gilt für das Konto, das ihn erstellt hat. Bewahren Sie ihn auf dem Server auf und lesen Sie ihn aus einer Umgebungsvariablen; geben Sie ihn niemals in den Quellcode einer Webseite oder in ein öffentliches Repository ein.

  2. Guthaben prüfen

    Setzen Sie die Umgebungsvariable OMNIDOC_API_KEY und führen Sie anschließend eines der unten stehenden Beispiele aus. Bei Erfolg wird JSON zurückgegeben; 401 bedeutet, dass der Schlüssel ein Problem aufweist und überprüft werden muss. Geben Sie den vollständigen Schlüssel niemals in Tickets, Screenshots oder Protokollen an.

    Terminal-Fenster
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Ein erfolgreicher Upload bedeutet lediglich, dass die Datei gespeichert wurde. Nachdem Sie einen Auftrag erstellt haben, warten Sie, bis er einen endgültigen Status erreicht hat, und listen Sie dann die Ergebnisse auf und laden Sie sie herunter.

SchrittMethode und PfadWas beizubehalten
Laden Sie eine Datei hochPOST /upload/presignupload_url, upload_headers, finalize_token
Senden Sie die DateiPUT zum zurückgegebenen upload_urlErfolgsantwort; diese Anfrage enthält keinen API-Schlüssel.
Bestätigen Sie den UploadPOST /upload/finalizedocument.id
Erstellen Sie eine ÜbersetzungPOST /jobsJob id
Status überprüfenGET /jobs/{job_id}completed oder failed
Liste die ErgebnisseGET /artifacts?job_id={job_id}Artefakt-IDs und -Formate
Ergebnis herunterladenGET /artifacts/{artifact_id}/downloadDateibytes und der Name der Antwortdatei

Für den direkten Upload senden Sie die upload_headers vom Server genau so zurück, wie sie zurückgegeben wurden, und senden Sie niemals X-API-Key an die Speicheradresse. Wenn die Upload-Adresse abläuft oder die Übertragung fehlschlägt, fordern Sie eine neue an. Details: Upload-Protokoll , schneller Einstieg , vollständiger Node.js Workflow und Felder der Übersetzungsanfrage .

Jeder Eintrag enthält die Pfade, Anfragefelder und Beispiele. Der Servicestatus Ihres Kontos sowie die Limits Ihres Schlüssels gelten für alle davon.

Ein API-Schlüssel identifiziert ein Konto. Er ist kein öffentliches Download-Passwort für eine Datei.

Anfrage-Header

Verwenden Sie X-API-Key: sk_… oder Authorization: Bearer sk_…, jeweils eines pro Anfrage. Senden Sie Content-Type: application/json mit JSON-Körpern.

Was ein Schlüssel erreichen kann

Ein Schlüssel greift nur auf die Ressourcen zu, die seinem Konto zustehen; der Dienststatus, das Budget des Schlüssels und die zulässigen Übersetzungseinstellungen bleiben weiterhin gültig. Änderungen am Konto sowie das Erstellen, Rotieren oder Widerrufen von Schlüsseln erfolgen in der Konsole.

Siehe Authentifizierung, Budgets und Rotation und Dienste und Berechtigungen .

05 Integrieren Sie die Behandlung von Build-Fehlern in die Integration

Abschnitt betitelt „05 Integrieren Sie die Behandlung von Build-Fehlern in die Integration“

Ein Timeout bedeutet nicht, dass der Job nicht erstellt wurde. Unterscheiden Sie wiederholbare Fehler von Anfragen, die behoben werden müssen, damit nichts doppelt eingereicht oder verarbeitet wird.

  • Idempotente Erstellung : Generieren Sie für jeden neuen Erstellungsaufruf einen Idempotency-Key; wenn Sie denselben Vorgang erneut ausführen, verwenden Sie den ursprünglichen Schlüssel und genau denselben Anfragetext. Dokumentenoperationen, Medienjobs und Spracherstellung erfordern den Schlüssel; für andere Erstellungsendpunkte siehe deren Referenzseiten.
  • Asynchrone Benachrichtigungen : Polling ist für eine erste Integration ausreichend; für kontinuierlichen Fortschritt verwenden Sie SSE , und um Endzustände im Hintergrund zu erhalten, nutzen Sie einen Webhook .
StatusZuerst prüfenWas ist zu tun?
401 / 403Schlüssel, Berechtigungen, RessourcenbesitzKorrigieren Sie die Anmeldedaten oder Berechtigungen; führen Sie keinen blinden erneuten Versuch durch.
402Verfügbare GutschriftenAufladen und dann erneut senden
409Idempotenzschlüssel und -körper, RessourcenzustandFragen Sie die ursprüngliche Operation ab, bevor Sie eine neue starten.
422Feldfehler in der AntwortKorrigieren Sie die Parameter oder die Datei
429Business code und Retry-AfterRate- und Warteschlangenbeschränkungen können abgewartet werden; ein erschöpftes Schlüsselbudget muss zuerst aufgestockt werden.
5xxTemporärer DienstfehlerBegrenztes exponentielles Backoff; Beibehaltung des idempotenten Schlüssels für Erstellungsanfragen

Behalten Sie den Antwort-Header X-Request-Id, die Anfragezeit und den Pfad zur Fehlerbehebung bei; protokollieren Sie niemals den vollständigen Schlüssel. Alle Fehlercodes und Wiederholungsbeispiele finden Sie in der Fehlerreferenz .

06 Prüfen Sie, wie die Abrechnung funktioniert, bevor Sie sie integrieren.

Abschnitt betitelt „06 Prüfen Sie, wie die Abrechnung funktioniert, bevor Sie sie integrieren.“

Keine Gutschriften

Das Hochladen, die Überprüfung von Aufträgen, das Herunterladen von Ergebnissen sowie das Lesen des Guthabens und der Abrechnungsprotokolle verursachen keine Kosten; ebenso fallen keine Gebühren für Glossare, Projekte, Tags, die Suche und das Teilen an.

Abgerechnet nach Nutzung

Dateiübersetzung, Dokumentenwerkzeuge, Sofortübersetzung sowie Audio- und Videodienste werden gemäß dem tatsächlichen Nutzungsaufwand abgerechnet; das Anlegen eines Auftrags stellt noch keine endgültige Abrechnung dar.

Vor Beginn eines Auftrags wird nur die Guthabenschwelle geprüft; nach dessen Abschluss wird der tatsächliche Verbrauch abgerechnet. Fällt das Guthaben darunter, wird die Differenz als Schulden erfasst, und später eingehende Gutschriften werden zunächst zur Begleichung verwendet. Sie können Abrechnungen und Rückerstattungen pro Auftrag oder pro Gutschriftsvorgang ausgleichen. Wird das Budget eines Schlüssels aufgebraucht, können weiterhin die zugehörigen Aufträge, Ergebnisse und Datensätze abgefragt werden.