Dokumentumfordítási API hozzáférési útmutató: Használja a Python-t a Word és a PDF kötegelt fordításához, és használja a Webhook-ot az eredmények eléréséhez

Használja az OmniDoc dokumentumfordító API-t a Word, PDF, Excel és egyéb fájlok kötegelt fordításához: a teljes feltöltés, feladatok létrehozása, Webhook visszahívások és letöltések, Python-példákkal, paraméterleírásokkal, idempotens újrapróbálkozási és számlázási szabályokkal.

A dokumentumfordító API automatizált folyamatba fűzheti a feltöltést, a feladatok létrehozását, a visszahívások fogadását és a fordítások letöltését. A teljes fordítást négy lépésben futtathatja.

Ha a rendszer minden nap feldolgozza a szerződéseket, utasításokat, papírokat vagy jelentéseket, a kézi feltöltés, várakozás és letöltés gyorsan szűk keresztmetszetté válik. Csak ezeknek a lépéseknek a programnak való átadásával lehet stabil a kötegelt feldolgozás.

Az OmniDoc (Zhiyi) dokumentumfordítási API-ja a teljes folyamatot egyesíti: Fájlok feltöltése, feladatok létrehozása, értesítések fogadása a befejezésről és fordítások letöltése. A fordítás megtartja az eredeti dokumentum elrendezését, táblázatait, képeit és képleteit, és kiadhatja a kétnyelvű összehasonlításokat vagy csak a fordítást.

Ez a cikk azoknak a fejlesztőknek szól, akiknek integrálniuk kell a dokumentumfordítást saját rendszerükbe. Elolvasás után elsajátíthatja a teljes hívási folyamatot, a gyakori paramétereket, az idempotens újrapróbálkozási módszereket, a Webhook visszahívásokat és a számlázási szabályokat, és képes lesz egy teljes feladat futtatására Python segítségével.

Hogyan lehet elérni a dokumentumfordító API-t? Egy mondatos következtetés

Integrálhatja a dokumentumfordítást saját rendszerébe az API segítségével, amellyel négy lépésben automatikusan feltölthet, feladatokat hozhat létre, visszahívásokat fogadhat és fordításokat tölthet le.

0. táblázat Hozzáférési forgatókönyvek és javasolt gyakorlatok

a helyzetedAjánlott gyakorlatokok
A szerződések, utasítások, papírok vagy jelentések kötegelt feldolgozása szükségesHasználja az API-t az automatikus feltöltéshez, feladatok létrehozásához és fordítások letöltéséhez a négy lépésből álló folyamat szerintSzüntesse meg a kézi feltöltést, várakozást és letöltést
Kétnyelvű összehasonlítás szükségesAz output_mode kétnyelvűre van állítva (alapértelmezett)A PPTX kivételével minden más formátum támogatja a kétnyelvű kimenetet
Reméljük, hogy a feladat befejezése után azonnal feldolgozásra kerülKonfigurálja a Webhookot, és töltse ki a titkos aláírás ellenőrzésétA rendszer proaktívan értesíti a szervert, amikor a feladat véget ér.
A hálózat instabil, és aggódom az ismételt beküldések miatt.Egy feladat létrehozásakor hozza magával az Idempotency-Key-t, és először ellenőrizze az állapotot, amikor az időtúllépést okoz.Ha ugyanaz a kulcs és ugyanaz a kérés, akkor az eredeti feladatot visszaküldjük, és nem történik ismételt levonás.

Olvassa el az alapvető információkat, mielőtt hozzáférne

Az API alapvető konvenciói a következők. A kód írásának megkezdése előtt erősítse meg ezeket a tartalmakat.

1. táblázat Az API alapvető konvenciói

projektszemléltet
Base URLhttps://omnidoc.top/api/v1
TanúsítványAz API kulcs az X-API-Key kérés fejlécébe kerül, és hordozó hitelesítő adatokként is elküldhető; létrehozva az API-konzolban
Kérelem formátumaJSON, tartalomtípus: alkalmazás/json
Nyomon követés kéréseMentse el minden válasz X-Request-ID-jét, és adja meg, amikor kapcsolatba lép az ügyfélszolgálattal
ÁramkorlátozásNyomja meg a Retry-After billentyűket, hogy megpróbálja újra, amikor a 429-es szám visszatér

Mely fájlok támogatottak?

Támogatja a Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown szöveget, SRT/ASS feliratokat, CSV, PNG/JPG képeket és UniDoc dokumentumokat (.udoc).

A PPTX kivételével minden más formátum támogatja a kétnyelvű kimenetet. Amikor a PPTX kétnyelvűséget kér, csak a fordítás kerül visszaadásra. A konkrét összehasonlítási módszerekhez lásd az alábbi alapvető összehasonlítást.

Készítsen fordítást négy lépésben

  1. Feltöltés jelentkezése: Hívja a POST /upload/presign-t, adja meg a fájl nevét és méretét, és szerezze meg a közvetlen átviteli címet, a feltöltési fejlécet és a finalize_token-t.
  2. Feltöltés és megerősítés: A visszaadott feltöltési fejléc segítségével helyezze el a fájlt, és ne vigye magával az API-kulcsot feltöltéskor. Ezután hívja meg a POST /upload/finalize parancsot a document.idért cserébe.
  3. Feladat létrehozása: Hívja meg a POST /jobs parancsot, küldje el a document_id és a target_lang nyelvet, és ajánlatos az Idempotency-Key-t egyszerre vinni.
  4. Eredmények lekérése: Lekérdezés GET /jobs/{id}, vagy iratkozzon fel az SSE folyamatra, vagy konfigurálja a Webhookot. A feladat befejezése után a GET /artifacts?job_id=... segítségével szerezze be és töltse le a terméket.

A feladatok létrehozásának általános paraméterei

Feladat létrehozásakor a két leggyakrabban használt mező a document_id és a target_lang. A többi mezőt szükség szerint kell beállítani.

2. táblázat POST /jobs kérelem mezők

Mezőalapértelmezettszemléltet
document_id—Megerősített dokumentumazonosító (kötelező)
target_lang—Célnyelv kódja (kötelező)
source_langAutomatikus észlelésforrásnyelvi kód
enginexr-397bFordítási konfiguráció: xr-397b, deepseek, qwen, chatgpt, gemini, claude
output_modebilingualkétnyelvű kétnyelvű összehasonlítás, egyetlen fordítás
glossary_id—Szószedet azonosító, egységes márkanév és szakmai szavak
include_imagesfalseFeldolgozza-e a kép szövegét a dokumentumban
context_translationfalseTovábbfejlesztett kontextus, következetesebb terminológia
style_preset—Stílus alapértelmezett

Python példa: Hozzon létre egy feladatot, és várja meg a befejezést

Az alábbi részlet csak a kérésektől függ. A teljes fel- és letöltési folyamatot a fejlesztői dokumentáció Python oldalán találja.

import time, uuid, requests

BASE = "https://omnidoc.top/api/v1"
HEADERS = {"X-API-Key": "sk_your_key"}

def create_job(document_id, target_lang="en", engine="xr-397b"):
    r = requests.post(f"{BASE}/jobs",
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={"document_id": document_id, "target_lang": target_lang, "engine": engine},
        timeout=30)
    r.raise_for_status()
    return r.json()

def wait_for_job(job_id):
    while True:
        job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=20).json()
        if job["status"] in ("completed", "failed"):
            return job
        time.sleep(5)

Kötegeltetés és újrapróbálkozás: párhuzamosság, sorban állás és idempotencia

Automatikus sorban állás

Minden fiók egyszerre 5 fájlt tud feldolgozni. A felső határt meghaladó feladatokat a rendszer a szokásos módon hozza létre és sorba állítja, és a stage_message jelzi, hogy hány feladat van még hátra.

Idempotens kulcsok

Ha az Idempotency-Key ugyanaz, és a kérés törzse ugyanaz, akkor az eredeti feladatot a rendszer visszaküldi, és nem hozza létre vagy terheli meg ismételten. Ha hálózati időtúllépésbe ütközik, először ellenőrizze a feladat állapotát, és ne küldje el újra új kulccsal.

Hibakód

  • 403: A kiválasztott konfiguráció nem engedélyezett a kulcshoz.
  • 404: Nem létezik dokumentáció vagy szószedet.
  • 415: A formátum nem támogatott.
  • 422: A fájl üres vagy a paraméterek érvénytelenek.

Webhook: Értesítse a szervert, amikor a feladat véget ér

Minden felhasználó 3 webhookot konfigurálhat. Hozzon létre a POST /webhooks segítségével, frissítse vagy deaktiválja a PATCH segítségével.

Amikor egy fájlfordítási feladat véget ér (függetlenül a sikertől vagy sikertelenségtől), a rendszer elküldi a job.completed eseményt:

  • a data.status befejeződött vagy sikertelen.
  • a data.char_count a fordítási karakterek száma.

Webhook létrehozásakor adja meg a titkot, és minden további visszahívás X-Webhook-Signature-t fog hozni. A HMAC-SHA256 segítségével írja alá az eredeti kérést a visszahívási forrás megerősítéséhez.

A visszahívási URL-nek elérhetőnek kell lennie a nyilvános hálózatról, és a HTTPS ajánlott.

Hogyan kell kiszámítani a díjat?

Indítás előtt ellenőrizze az egyensúlyt

  • PDF: Az egyenlegnek nagyobbnak kell lennie, mint "oldalak száma × 2 pont".
  • Egyéb formátumok: az eredeti szavak száma alapján fizetendő, legalább 2 pont.
  • Ha az egyenleg nem elegendő, a feladat a kvóta_túllépéssel zárul, és díjak nem kerülnek levonásra.

Levonás a tényleges használat alapján

A feladat elvégzése után a tényleges használat alapján levonják a díjakat. Ha a feladat meghiúsul vagy törlésre kerül, nem vonunk le díjat.

Ingyenes lekérdezés

Az egyenleg, a feladat állapota, a felhasználás, az utalványok és a letöltési címek ellenőrzéséért nem vonnak le pontokat.

Pontcsomag

A pontcsomagok 9,9 ¥-tól indulnak 3000 pontért, és a megvásárolt pontok hosszú ideig érvényesek. Az akciós csomagok a GET /számlázás/kreditek/tervek oldalon keresztül érdeklődhetnek.

Következő lépés

A teljes cURL, Python, Node.js példák megtekinthetők a fejlesztői dokumentációban: https://docs.omnidoc.top/guide/quickstart/.

Ha egyelőre nem szeretne kódot írni, csatlakozhat az OmniDoc AI-asszisztenséhez is, hogy közvetlenül lefordítsa a natív fájlokat. A részletekért lásd: „A mesterséges intelligencia közvetlenül kezelje a Word, az Excel és a PPT-t": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.

📊 Alapvető összehasonlítás

A különböző fájlformátumoknak eltérő kétnyelvű kimeneti módszerei vannak. Előre tervezhet saját fájltípusának megfelelően.

Fájl típusaKétnyelvű összehasonlítási módszerA kétnyelvűség támogatása
WordHasonlítsa össze bekezdésenkéntigen
ExcelHasonlítsa össze oszloponkéntigen
PDFOldalonkénti összehasonlításigen
Feliratok (SRT/ASS)Hasonlítsa össze soronkéntigen
PPTXCsak a fordításhoz térjen visszanem

🎯 Melyik módszer illik hozzád?

Ha kötegelt feldolgoznia kell a szerződéseket, specifikációkat vagy papírokat

Használja az API-t a rendszerhez való csatlakozáshoz, valamint a négylépéses folyamatnak megfelelően automatikus feltöltéshez, feladatok létrehozásához és fordítások letöltéséhez, kiküszöbölve a kézi műveleteket.

Ha a hálózat gyakran instabil

A feladat létrehozásakor hozza magával az Idempotency-Key-t. Az időkorlát után először kérdezze le az állapotot, hogy elkerülje az ismételt létrehozást vagy az ismételt levonásokat.

Ha a feladatot közvetlenül a vége után szeretné feldolgozni

Konfigurálja a Webhookot, és adja meg a titkot az aláírás ellenőrzéséhez. A rendszer proaktívan értesíti a szervert, ha a feladat befejeződött.

Ha egységes követelményei vannak a szakmai szókincsre vonatkozóan

Először hozzon létre egy szószedetet, majd adja meg a glossary_id értéket a márkanevek és a szakmai szavak fordításának egységesítésére szolgáló feladat létrehozásakor.

❓ Gyakran Ismételt Kérdések (GYIK)

1. Ismételten levonják a díjat, ha ugyanazt a feladatot ismételten benyújtom?

Ha az Idempotency-Key azonos és a kérés törzse ugyanaz, akkor az eredeti feladat ismételt létrehozás vagy levonás nélkül kerül visszaadásra.

2. Ha a feladat sikertelen vagy törlődik, levonják a pontokat?

Semmilyen díj nem kerül felszámításra. Ha egy feladat meghiúsul vagy törlésre kerül, nem kerül sor levonásra.

3. Mi történik, ha nincs elegendő pont?

A feladat a quota_exceeded értékkel zárul, és semmilyen díj nem kerül levonásra. Az egyenleg küszöbértéke a kezdés előtt a következő: a PDF-hez az "oldalszám × 2 pontnál" nagyobb egyenleg szükséges, más formátumok esetén pedig legalább 2 pontos egyenleg szükséges a szószám alapján.

4. Kell-e vinnem API-kulcsot a fájlok feltöltéséhez?

szükségtelen. A feltöltési fejléc PUT fájl használatakor ne hozza magával az API-kulcsot.

5. Mit tegyek, ha 429-es forgalomkorlátozásba ütközöm?

Próbálja újra a válaszban szereplő Újrapróbálkozás utáni idő szerint.

📝 Összefoglaló

A feltöltések, a feladatok létrehozása, a visszahívások és a letöltések automatizált folyamatba fűzésével a dokumentumfordítás integrálható a mindennapi üzletmenetbe. Először futtasson végig egy feladatot egy Python-példával, majd adjon hozzá egy szószedetet, kétnyelvű kimenetet és szükség szerint webhookat.

Próbálja ki most: Töltse fel a dokumentumot a fordítás megkezdéséhez, megtartva az eredeti elrendezést

Frissítve: 2026-11-17