OmniDocDocument Translation API Access Guide: Použijte Python k hromadnému překladu Wordu a PDF a použijte Webhook k získání výsledků
Použijte rozhraní API pro překlad dokumentů OmniDoc k dávkovému překladu souborů Word, PDF, Excel a dalších: kompletní proces nahrávání, vytváření úloh, zpětných volání a stahování z Webhooku, s příklady Pythonu, popisy parametrů, idempotentní opakování a pravidla účtování.
Rozhraní API pro překlad dokumentů dokáže zapojit nahrávání, vytváření úloh, přijímání zpětných volání a stahování překladů do automatizovaného procesu. Kompletní překlad můžete dokončit v pouhých čtyřech krocích.
Pokud váš systém zpracovává smlouvy, pokyny, dokumenty nebo zprávy každý den, ruční nahrávání, čekání a stahování se rychle stane úzkým hrdlem. Pouze předáním těchto kroků programu může být dávkové zpracování stabilní.
Rozhraní API pro překlad dokumentů OmniDoc (Zhiyi) spojuje celý proces dohromady: Nahrávání souborů, vytváření úkolů, přijímání oznámení o dokončení a stahování překladů. Překlad si zachovává rozvržení, tabulky, obrázky a vzorce původního dokumentu a může vydávat dvojjazyčná srovnání nebo pouze překlad.
Tento článek je vhodný pro vývojáře, kteří potřebují integrovat překlad dokumentů do svých vlastních systémů. Po přečtení budete schopni zvládnout kompletní proces volání, běžné parametry, idempotentní metody opakování, zpětná volání Webhooku a pravidla účtování a budete schopni spustit kompletní úlohu pomocí Pythonu.
Jak získat přístup k API pro překlad dokumentů? Závěr jednou větou
Překlad dokumentů můžete integrovat do svého vlastního systému pomocí rozhraní API k automatickému nahrávání, vytváření úloh, přijímání zpětných volání a stahování překladů ve čtyřech krocích.
Tabulka 0 Scénáře přístupu a doporučené postupy
| vaší situaci | Doporučené postupy | důvod |
|---|---|---|
| Potřebujete dávkově zpracovat smlouvy, specifikace, dokumenty nebo zprávy | Použijte API k automatickému nahrávání, vytváření úkolů a stahování překladů podle čtyřfázového procesu | Eliminujte ruční nahrávání, čekání a stahování |
| Potřebujete dvojjazyčné srovnání | output_mode je nastaven na dvojjazyčný (výchozí) | Kromě PPTX všechny ostatní formáty podporují dvojjazyčný výstup |
| Doufám, že úkol bude zpracován ihned po jeho dokončení | Nakonfigurujte Webhook a vyplňte tajné ověření podpisu | Systém bude proaktivně informovat váš server, když úloha skončí. |
| Síť je nestabilní a mám obavy z opakovaného odesílání. | Při vytváření úkolu vezměte klíč Idempotency-Key a po vypršení časového limitu nejprve zkontrolujte stav. | Pokud máte stejný klíč a stejný požadavek, bude původní úkol vrácen a nebudou prováděny žádné opakované srážky. |
Před přístupem si přečtěte základní informace
Základní konvence API jsou následující. Před zahájením psaní kódu tento obsah potvrďte.
Tabulka 1 Základní konvence rozhraní API
| projekt | ilustrovat |
|---|---|
| Základní URL | https://omnidoc.top/api/v1 |
| Osvědčení | Klíč API je umístěn v hlavičce požadavku X-API-Key a lze jej také odeslat jako pověření nositele; vytvořené v konzole API |
| Formát požadavku | JSON, Content-Type: application/json |
| Žádost o sledování | Uložte X-Request-Id každé odpovědi a uveďte je, když budete kontaktovat podporu |
| Omezení proudu | Stiskněte Retry-After a zkuste to znovu, když se vrátí 429 |
Které soubory jsou podporovány?
Podporuje Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown s textem, titulky SRT/ASS, obrázky CSV, PNG/JPG a dokumenty UniDoc (.udoc).
Kromě PPTX všechny ostatní formáty podporují dvojjazyčný výstup. Když PPTX požaduje dvojjazyčnost, vrátí se pouze překlad. Konkrétní srovnávací metody naleznete v základním srovnání níže.
Dokončete překlad ve čtyřech krocích
- Požádejte o nahrání: Zavolejte POST /upload/presign, odešlete název a velikost souboru a získejte adresu přímého přenosu, záhlaví pro nahrání a finalize_token.
- Nahrát a potvrdit: K PUT souboru použijte vrácenou hlavičku pro nahrání a při nahrávání nenoste klíč API. Poté zavolejte POST /upload/finalize výměnou za document.id.
- Vytvořte úkol: Zavolejte POST /jobs, odešlete document_id a target_lang a doporučuje se současně přinést Idempotency-Key.
- Načíst výsledky: Hlasování GET /jobs/{id} nebo se přihlaste k odběru SSE progress nebo nakonfigurujte Webhook. Po dokončení úkolu použijte GET /artifacts?job_id=... k získání produktu a jeho stažení.
Společné parametry pro vytváření úloh
Při vytváření úkolu se nejčastěji používají dvě pole document_id a target_lang. Ostatní pole jsou nastavena podle potřeby.
Tabulka 2 Pole požadavků POST / jobs
| Pole | výchozí | ilustrovat |
|---|---|---|
| document_id | — | Potvrzené ID dokumentu (vyžadováno) |
| target_lang | — | Kód cílového jazyka (povinné) |
| source_lang | Automatická detekce | kód zdrojového jazyka |
| engine | xr-397b | Konfigurace překladu: xr-397b, deepseek, qwen, chatgpt, gemini, claude |
| output_mode | bilingual | bilingvní bilingvní srovnání, jediný překlad |
| glossary_id | — | Glosář ID, jednotný název značky a odborná slova |
| include_images | false | Zda zpracovat text obrázku v dokumentu |
| context_translation | false | Rozšířený kontext, konzistentnější terminologie |
| style_preset | — | Výchozí styl |
Příklad Pythonu: Vytvořte úkol a počkejte na dokončení
Níže uvedený úryvek závisí pouze na žádostech. Kompletní proces nahrávání a stahování najdete na stránce Python v dokumentaci pro vývojáře.
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ávkování a opakování: souběžnost, řazení do fronty a idempotence
Automatické řazení do fronty
Každý účet může zpracovávat 5 souborů současně. Úkoly, které překračují horní limit, jsou vytvořeny a zařazeny do fronty jako obvykle a stage_message bude indikovat, kolik úkolů je před námi.
Idempotentní klíče
Pokud je Idempotency-Key stejný a tělo požadavku stejné, bude vrácena původní úloha a nebude opakovaně vytvářena ani účtována. Pokud dojde k vypršení časového limitu sítě, zkontrolujte nejprve stav úlohy a neodesílejte znovu s novým klíčem.
Kód chyby
- 403: Vybraná konfigurace není povolena pro klíč.
- 404: Dokumentace nebo glosář neexistuje.
- 415: Formát není podporován.
- 422: Soubor je prázdný nebo jsou parametry neplatné.
Webhook: Upozorní váš server, když úloha skončí
Každý uživatel může nakonfigurovat 3 webhooky. Vytvořte pomocí POST /webhooks, aktualizujte nebo deaktivujte pomocí PATCH.
Když úloha překladu souboru skončí (bez ohledu na úspěch nebo neúspěch), systém odešle událost job.completed:
- data.status je dokončen nebo selhal.
- data.char_count je počet znaků překladu.
Vyplňte tajemství při vytváření Webhooku a každé následující zpětné volání přinese X-Webhook-Signature. Pomocí HMAC-SHA256 podepište původní požadavek a potvrďte zdroj zpětného volání.
Adresa URL zpětného volání musí být dostupná z veřejné sítě a doporučuje se HTTPS.
Jak vypočítat poplatek?
Zkontrolujte rovnováhu před spuštěním
- PDF: Zůstatek musí být vyšší než "počet stránek × 2 body".
- Jiné formáty: účtováno na základě počtu původních slov, minimálně 2 body.
- Když je zůstatek nedostatečný, úloha skončí s překročením kvóty a nebudou odečteny žádné poplatky.
Odpočet na základě skutečného použití
Po dokončení úkolu budou poplatky odečteny na základě skutečného využití. Pokud úkol selže nebo je zrušen, nebudou strženy žádné poplatky.
Dotaz zdarma
Body nebudou odečteny za kontrolu zůstatku, stavu úkolu, využití, voucherů a stahovacích adres.
Bodový balíček
Bodové balíčky začínají na 9,9 ¥ za 3 000 bodů a zakoupené body jsou platné po dlouhou dobu. Na balíčky ve výprodeji lze zažádat prostřednictvím GET /billing/credits/plans.
Další krok
Kompletní příklady cURL, Python, Node.js si můžete prohlédnout v dokumentaci pro vývojáře: https://docs.omnidoc.top/guide/quickstart/.
Pokud prozatím nechcete psát kód, můžete se také připojit k asistentovi umělé inteligence OmniDoc a přímo překládat nativní soubory. Podrobnosti naleznete v části „Nechte AI přímo ovládat Word, Excel a PPT": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.
📊 Srovnání jádra
Různé formáty souborů mají různé metody dvojjazyčného výstupu. Můžete plánovat předem podle vlastního typu souboru.
| Typ souboru | Dvojjazyčná srovnávací metoda | Zda podporovat bilingvní |
|---|---|---|
| Word | Porovnejte podle odstavce | Ano |
| Excel | Porovnejte podle sloupce | Ano |
| Porovnejte podle stránky | Ano | |
| Titulky (SRT/ASS) | Porovnejte podle řádku | Ano |
| PPTX | Návrat pouze k překladu | žádný |
🎯 Která metoda je pro vás vhodná?
Pokud potřebujete dávkově zpracovat smlouvy, specifikace nebo dokumenty
Pomocí API se připojte k systému a automaticky nahrávejte, vytvářejte úkoly a stahujte překlady podle čtyřfázového procesu, což eliminuje ruční operace.
Pokud je vaše síť často nestabilní
Při vytváření úkolu si vezměte klíč Idempotency. Po uplynutí časového limitu se nejprve zeptejte na stav, abyste předešli opakovanému vytváření nebo opakovaným odpočtům.
Pokud chcete úkol zpracovat ihned po jeho skončení
Nakonfigurujte webhook a vyplňte tajný kód pro ověření podpisu. Systém bude proaktivně informovat váš server o dokončení úlohy.
Pokud máte jednotné požadavky na odbornou slovní zásobu
Nejprve vytvořte glosář a poté při vytváření úkolu předejte glosář_id, abyste sjednotili překlad názvů značek a odborných slov.
❓ Často kladené otázky (FAQ)
1. Budou se opakovat srážky za opakované zadání stejného úkolu?
Pokud je Idempotency-Key stejný a tělo požadavku stejné, bude původní úkol vrácen bez opakovaného vytváření nebo odečítání.
2. Pokud úkol selže nebo je zrušen, budou body odečteny?
Nebudou účtovány žádné poplatky. Pokud úkol selže nebo je zrušen, nebudou provedeny žádné srážky.
3. Co se stane, když není dostatek bodů?
Úloha skončí s překročením kvóty a nebudou odečteny žádné poplatky. Prahová hodnota zůstatku před zahájením je: PDF vyžaduje zůstatek vyšší než „počet stránek × 2 body"a ostatní formáty vyžadují zůstatek alespoň 2 body na základě počtu slov.
4. Musím při nahrávání souborů přinést API klíč?
zbytečné. Při použití souboru PUT s hlavičkou pro nahrávání nenoste klíč API.
5. Co mám dělat, když narazím na dopravní limit 429?
Opakujte to podle času Opakovat-After v odpovědi.
📝 Shrnutí
Spojením nahrávání, vytváření úkolů, zpětných volání a stahování do automatizovaného procesu lze překlad dokumentů integrovat do každodenního podnikání. Začněte tím, že si projdete úlohu s příkladem Pythonu, pak podle potřeby přidejte glosář, dvojjazyčný výstup a webhooky.
Vyzkoušejte to hned: Nahrajte dokument a začněte překládat při zachování původního rozvržení
