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.
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.
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.
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.
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.
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());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.
| Schritt | Methode und Pfad | Was beizubehalten |
|---|---|---|
| Laden Sie eine Datei hoch | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Senden Sie die Datei | PUT zum zurückgegebenen upload_url | Erfolgsantwort; diese Anfrage enthält keinen API-Schlüssel. |
| Bestätigen Sie den Upload | POST /upload/finalize | document.id |
| Erstellen Sie eine Übersetzung | POST /jobs | Job id |
| Status überprüfen | GET /jobs/{job_id} | completed oder failed |
| Liste die Ergebnisse | GET /artifacts?job_id={job_id} | Artefakt-IDs und -Formate |
| Ergebnis herunterladen | GET /artifacts/{artifact_id}/download | Dateibytes 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 .
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.
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.| Status | Zuerst prüfen | Was ist zu tun? |
|---|---|---|
401 / 403 | Schlüssel, Berechtigungen, Ressourcenbesitz | Korrigieren Sie die Anmeldedaten oder Berechtigungen; führen Sie keinen blinden erneuten Versuch durch. |
402 | Verfügbare Gutschriften | Aufladen und dann erneut senden |
409 | Idempotenzschlüssel und -körper, Ressourcenzustand | Fragen Sie die ursprüngliche Operation ab, bevor Sie eine neue starten. |
422 | Feldfehler in der Antwort | Korrigieren Sie die Parameter oder die Datei |
429 | Business code und Retry-After | Rate- und Warteschlangenbeschränkungen können abgewartet werden; ein erschöpftes Schlüsselbudget muss zuerst aufgestockt werden. |
5xx | Temporärer Dienstfehler | Begrenztes 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 .
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.