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 helyzeted | Ajánlott gyakorlatok | ok |
|---|---|---|
| A szerződések, utasítások, papírok vagy jelentések kötegelt feldolgozása szükséges | Haszná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 szerint | Szüntesse meg a kézi feltöltést, várakozást és letöltést |
| Kétnyelvű összehasonlítás szükséges | Az 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ül | Konfigurálja a Webhookot, és töltse ki a titkos aláírás ellenőrzését | A 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
| projekt | szemléltet |
|---|---|
| Base URL | https://omnidoc.top/api/v1 |
| Tanúsítvány | Az 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átuma | JSON, tartalomtípus: alkalmazás/json |
| Nyomon követés kérése | Mentse el minden válasz X-Request-ID-jét, és adja meg, amikor kapcsolatba lép az ügyfélszolgálattal |
| Áramkorlátozás | Nyomja 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
- 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.
- 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.
- 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.
- 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értelmezett | szemléltet |
|---|---|---|
| document_id | — | Megerősített dokumentumazonosító (kötelező) |
| target_lang | — | Célnyelv kódja (kötelező) |
| source_lang | Automatikus észlelés | forrásnyelvi kód |
| engine | xr-397b | Fordítási konfiguráció: xr-397b, deepseek, qwen, chatgpt, gemini, claude |
| output_mode | bilingual | ké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_images | false | Feldolgozza-e a kép szövegét a dokumentumban |
| context_translation | false | Tová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ípusa | Kétnyelvű összehasonlítási módszer | A kétnyelvűség támogatása |
|---|---|---|
| Word | Hasonlítsa össze bekezdésenként | igen |
| Excel | Hasonlítsa össze oszloponként | igen |
| Oldalonkénti összehasonlítás | igen | |
| Feliratok (SRT/ASS) | Hasonlítsa össze soronként | igen |
| PPTX | Csak a fordításhoz térjen vissza | nem |
🎯 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.


