Document Translation API Access Guide: Použite Python na dávkový preklad Wordu a PDF a použite Webhook na získanie výsledkov
Použite rozhranie API na preklad dokumentov OmniDoc na dávkový preklad súborov Word, PDF, Excel a ďalších: kompletný proces nahrávania, vytvárania úloh, spätných volaní a sťahovaní cez Webhook, s príkladmi Pythonu, popismi parametrov, idempotentným opakovaním a pravidlami účtovania.
Rozhranie API na preklad dokumentov môže reťazcovať nahrávanie, vytváranie úloh, prijímanie spätných volaní a sťahovanie prekladov do automatizovaného procesu. Kompletný preklad môžete spustiť v štyroch krokoch.
Ak váš systém spracováva zmluvy, pokyny, dokumenty alebo správy každý deň, manuálne nahrávanie, čakanie a sťahovanie sa rýchlo stane prekážkou. Len odovzdaním týchto krokov programu môže byť dávkové spracovanie stabilné.
Rozhranie API na preklad dokumentov OmniDoc (Zhiyi) spája celý proces: Nahrávanie súborov, vytváranie úloh, prijímanie upozornení na dokončenie a sťahovanie prekladov. Preklad si zachováva rozloženie, tabuľky, obrázky a vzorce pôvodného dokumentu a môže vydávať dvojjazyčné porovnania alebo len preklad.
Tento článok je vhodný pre vývojárov, ktorí potrebujú integrovať preklad dokumentov do svojich vlastných systémov. Po prečítaní budete schopní zvládnuť celý proces volania, bežné parametre, metódy idempotentného opakovania, spätné volania Webhooku a pravidlá účtovania a budete môcť spustiť kompletnú úlohu pomocou Pythonu.
Ako získať prístup k API prekladu dokumentov? Záver jednou vetou
Preklad dokumentov môžete integrovať do svojho vlastného systému pomocou rozhrania API na automatické nahrávanie, vytváranie úloh, prijímanie spätných volaní a sťahovanie prekladov v štvorkrokovom procese.
Tabuľka 0 Scenáre prístupu a odporúčané postupy
| vaša situácia | Odporúčané postupy | dôvod |
|---|---|---|
| Potreba dávkového spracovania zmlúv, pokynov, dokumentov alebo správ | Použite API na automatické nahrávanie, vytváranie úloh a sťahovanie prekladov podľa štvorstupňového procesu | Eliminujte manuálne nahrávanie, čakanie a sťahovanie |
| Treba dvojjazyčné porovnanie | output_mode je nastavený na dvojjazyčný (predvolené) | Okrem PPTX všetky ostatné formáty podporujú dvojjazyčný výstup |
| Dúfam, že úloha bude spracovaná ihneď po jej dokončení | Nakonfigurujte Webhook a vyplňte overenie tajného podpisu | Systém bude proaktívne informovať váš server o ukončení úlohy. |
| Sieť je nestabilná a mám obavy z opakovaných podaní. | Pri vytváraní úlohy si prineste kľúč Idempotency a po uplynutí časového limitu skontrolujte stav. | Ak máte rovnaký kľúč a rovnakú požiadavku, pôvodná úloha sa vráti a nebudú sa vykonávať žiadne opakované odpočty. |
Pred prístupom si prečítajte základné informácie
Základné konvencie API sú nasledovné. Pred začatím písania kódu potvrďte tento obsah.
Tabuľka 1 Základné konvencie rozhrania API
| projektu | ilustrovať |
|---|---|
| Základná adresa URL | https://omnidoc.top/api/v1 |
| Certifikácia | Kľúč API je umiestnený v hlavičke požiadavky X-API-Key a možno ho tiež odoslať ako poverenia nosiča; vytvorené v konzole API |
| Formát žiadosti | JSON, typ obsahu: application/json |
| Požiadať o sledovanie | Uložte X-Request-Id každej odpovede a uveďte ho pri kontaktovaní podpory |
| Obmedzenie prúdu | Stlačte Retry-After a skúste to znova, keď sa vráti 429 |
Ktoré súbory sú podporované?
Podporuje Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown s textom, titulky SRT/ASS, obrázky CSV, PNG/JPG a dokumenty UniDoc (.udoc).
Okrem PPTX všetky ostatné formáty podporujú dvojjazyčný výstup. Keď PPTX požaduje dvojjazyčnosť, vráti sa iba preklad. Špecifické porovnávacie metódy nájdete v základnom porovnaní nižšie.
Dokončite preklad v štyroch krokoch
- Požiadajte o upload: Zavolajte POST /upload/presign, odošlite názov súboru a veľkosť a získajte adresu priameho prenosu, hlavičku nahrávania a finalize_token.
- Odovzdajte a potvrďte: Použite vrátenú hlavičku nahrávania na VLOŽENIE súboru a pri nahrávaní nenoste kľúč API. Potom zavolajte POST /upload/finalize výmenou za document.id.
- Vytvoriť úlohu: Zavolajte POST /jobs, odošlite document_id a target_lang a odporúča sa priniesť si kľúč Idempotency-Key v rovnakom čase.
- Načítať výsledky: Anketa GET /jobs/{id} alebo sa prihláste na odber SSE progress alebo nakonfigurujte Webhook. Po dokončení úlohy použite GET /artifacts?job_id=... na získanie produktu a jeho stiahnutie.
Bežné parametre pre vytváranie úloh
Pri vytváraní úlohy sa najčastejšie používajú dve polia document_id a target_lang. Ostatné polia sú nastavené podľa potreby.
Tabuľka 2 Polia žiadostí o POST / úlohy
| Pole | predvolená | ilustrovať |
|---|---|---|
| document_id | — | Potvrdené ID dokumentu (povinné) |
| target_lang | — | Kód cieľového jazyka (povinné) |
| source_lang | Automatická detekcia | kód zdrojového jazyka |
| engine | xr-397b | Konfigurácia prekladu: xr-397b, deepseek, qwen, chatgpt, gemini, claude |
| output_mode | bilingual | bilingválne bilingválne porovnanie, jediný preklad |
| glossary_id | — | ID slovníka, jednotný názov značky a odborné slová |
| include_images | falošný | Či sa má spracovať text obrázka v dokumente |
| context_translation | false | Rozšírený kontext, konzistentnejšia terminológia |
| style_preset | — | Predvolený štýl |
Príklad Pythonu: Vytvorte úlohu a počkajte na dokončenie
Úryvok nižšie závisí len od požiadaviek. Kompletný proces nahrávania a sťahovania nájdete na stránke Python v dokumentácii pre vývojárov.
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)
Dávkovanie a opakovanie: súbežnosť, radenie a idempotencia
Automatické radenie
Každý účet dokáže spracovať 5 súborov súčasne. Úlohy, ktoré presahujú horný limit, sa vytvoria a zaradia do frontu ako zvyčajne a stage_message bude indikovať, koľko úloh je pred nami.
Idempotentné kľúče
Ak je kľúč Idempotency rovnaký a telo požiadavky je rovnaké, pôvodná úloha sa vráti a nebude sa opakovane vytvárať ani účtovať. Keď sa stretnete s časovým limitom siete, najskôr skontrolujte stav úlohy a neodosielajte znova s novým kľúčom.
Kód chyby
- 403: Zvolená konfigurácia nie je povolená pre kľúč.
- 404: Dokumentácia alebo slovník neexistuje.
- 415: Formát nie je podporovaný.
- 422: Súbor je prázdny alebo sú neplatné parametre.
Webhook: Upozornite váš server, keď sa úloha skončí
Každý používateľ si môže nakonfigurovať 3 webhooky. Vytvorte pomocou POST /webhooks, aktualizujte alebo deaktivujte pomocou PATCH.
Keď sa skončí úloha prekladu súboru (bez ohľadu na úspech alebo zlyhanie), systém odošle udalosť job.completed:
- stav údajov je dokončený alebo neúspešný.
- data.char_count je počet znakov prekladu.
Vyplňte tajomstvo pri vytváraní Webhooku a každé ďalšie spätné volanie prinesie X-Webhook-Signature. Pomocou HMAC-SHA256 podpíšte pôvodnú požiadavku na potvrdenie zdroja spätného volania.
Adresa URL spätného volania musí byť prístupná z verejnej siete a odporúča sa HTTPS.
Ako vypočítať poplatok?
Pred spustením skontrolujte zostatok
- PDF: Zostatok musí byť vyšší ako "počet strán × 2 body".
- Iné formáty: spoplatnené na základe počtu pôvodných slov, minimálne 2 body.
- Keď je zostatok nedostatočný, úloha sa skončí s prekročením kvóty a nebudú odpočítané žiadne poplatky.
Odpočet na základe skutočného použitia
Po dokončení úlohy sa poplatky odpočítajú na základe skutočného použitia. Ak úloha zlyhá alebo je zrušená, nebudú odpočítané žiadne poplatky.
Dopyt zadarmo
Body sa nebudú odpočítavať za kontrolu zostatku, stavu úlohy, použitia, kupónov a adries na stiahnutie.
Bodový balík
Bodové balíčky začínajú na 9,9 ¥ za 3 000 bodov a zakúpené body platia dlhodobo. Balíčky v predaji je možné dopytovať cez GET /billing/credits/plans.
Ďalší krok
Kompletné príklady cURL, Python, Node.js si môžete pozrieť v dokumentácii pre vývojárov: https://docs.omnidoc.top/guide/quickstart/.
Ak zatiaľ nechcete písať kód, môžete sa tiež pripojiť k asistentovi AI OmniDoc a priamo prekladať natívne súbory. Podrobnosti nájdete v časti „Nechajte AI priamo ovládať Word, Excel a PPT": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.
📊 Základné porovnanie
Rôzne formáty súborov majú rôzne metódy dvojjazyčného výstupu. Môžete plánovať vopred podľa vlastného typu súboru.
| Typ súboru | Dvojjazyčná porovnávacia metóda | Či podporovať bilingválne |
|---|---|---|
| Word | Porovnajte podľa odseku | áno |
| Excel | Porovnajte podľa stĺpca | áno |
| Porovnajte podľa stránky | áno | |
| Titulky (SRT/ASS) | Porovnajte podľa riadkov | áno |
| PPTX | Návrat iba k prekladu | č |
🎯 Ktorá metóda je pre vás vhodná?
Ak potrebujete dávkové spracovanie zmlúv, špecifikácií alebo dokumentov
Použite API na pripojenie k systému a automatické nahrávanie, vytváranie úloh a sťahovanie prekladov podľa štvorstupňového procesu, čím sa eliminujú manuálne operácie.
Ak je vaša sieť často nestabilná
Pri vytváraní úlohy si prineste kľúč Idempotency. Po uplynutí časového limitu sa najskôr opýtajte na stav, aby ste sa vyhli opakovanému vytváraniu alebo opakovaným odpočtom.
Ak chcete úlohu spracovať ihneď po jej skončení
Nakonfigurujte Webhook a vyplňte tajný kód na overenie podpisu. Systém bude proaktívne informovať váš server o dokončení úlohy.
Ak máte jednotné požiadavky na odbornú slovnú zásobu
Najprv vytvorte slovník a potom pri vytváraní úlohy zadajte glossary_id, aby ste zjednotili preklad názvov značiek a odborných slov.
❓ Často kladené otázky (FAQ)
1. Budú sa poplatky strhávať opakovane, ak opakovane zadávam rovnakú úlohu?
Ak je kľúč idempotencie rovnaký a telo požiadavky je rovnaké, pôvodná úloha sa vráti bez opakovaného vytvárania alebo odpočítavania.
2. Ak úloha zlyhá alebo je zrušená, odpočítajú sa body?
Nebudú sa účtovať žiadne poplatky. Keď úloha zlyhá alebo je zrušená, nebudú sa vykonávať žiadne zrážky.
3. Čo sa stane, keď nie je dostatok bodov?
Úloha sa skončí s prekročením kvóty a nebudú odpočítané žiadne poplatky. Prah zostatku pred spustením je: PDF vyžaduje zostatok vyšší ako „počet strán × 2 body"a ostatné formáty vyžadujú zostatok najmenej 2 body na základe počtu slov.
4. Musím si pri nahrávaní súborov priniesť API kľúč?
zbytočné. Keď používate súbor PUT s hlavičkou nahrávania, nenoste kľúč API.
5. Čo mám robiť, ak narazím na dopravný limit 429?
Skúste to znova podľa času Retry-After v odpovedi.
📝 Zhrnutie
Zaradením nahrávania, vytvárania úloh, spätných volaní a sťahovania do automatizovaného procesu možno preklad dokumentov integrovať do každodenného podnikania. Začnite spustením úlohy s príkladom Pythonu a potom pridajte slovník, dvojjazyčný výstup a webhooky podľa potreby.
Skúste to teraz: Odovzdajte dokument a spustite preklad, pričom sa zachová pôvodné rozloženie


