Document Translation API Access Guide: Utilizați Python pentru a traduce în loturi Word și PDF și utilizați Webhook pentru a primi rezultatele

Utilizați API-ul de traducere a documentelor OmniDoc pentru a traduce în loturi fișiere Word, PDF, Excel și alte fișiere: procesul complet de încărcare, creare de sarcini, apeluri și descărcări Webhook, cu exemple Python, descrieri ale parametrilor, reîncercare idempotent și reguli de facturare.

API-ul de traducere a documentelor poate să încarce șiruri, să creeze sarcini, să primească apeluri înapoi și să descarce traduceri într-un proces automat. Puteți executa o traducere completă în patru pași.

Dacă sistemul dvs. procesează contracte, instrucțiuni, lucrări sau rapoarte în fiecare zi, încărcarea manuală, așteptarea și descărcarea vor deveni rapid un blocaj. Numai prin predarea acestor pași către program poate fi stabilă procesarea loturilor.

API-ul de traducere a documentelor al OmniDoc (Zhiyi) reunește întregul proces: Încărcați fișiere, creați sarcini, primiți notificări de finalizare și descărcați traduceri. Traducerea păstrează aspectul, tabelele, imaginile și formulele documentului original și poate produce comparații bilingve sau doar traducerea.

Acest articol este potrivit pentru dezvoltatorii care trebuie să integreze traducerea documentelor în propriile sisteme. După citire, veți putea stăpâni întregul proces de apelare, parametrii comuni, metodele de reîncercare idempotente, apelurile Webhook și regulile de facturare și veți putea rula o sarcină completă folosind Python.

Cum se accesează API-ul de traducere a documentelor? O singură propoziție concluzie

Puteți integra traducerea documentelor în propriul sistem utilizând API-ul pentru a încărca automat, a crea sarcini, a primi apeluri înapoi și a descărca traduceri într-un proces în patru pași.

Tabelul 0 Accesați scenarii și practici recomandate

situatia taPractici recomandatemotiv
Trebuie să procesați în loturi contracte, instrucțiuni, lucrări sau rapoarteUtilizați API pentru a încărca automat, a crea sarcini și a descărca traduceri conform procesului în patru pașiEliminați încărcarea manuală, așteptarea și descărcarea
Am nevoie de comparație bilingvăoutput_mode este setat la bilingual (implicit)Cu excepția PPTX, toate celelalte formate acceptă ieșire bilingvă
Sper că sarcina va fi procesată imediat după ce este finalizatăConfigurați Webhook și completați verificarea semnăturii secreteSistemul vă va notifica în mod proactiv serverul când sarcina se termină.
Rețeaua este instabilă și sunt îngrijorat de trimiterile repetate.Aduceți cheia Idempotency atunci când creați o sarcină și verificați mai întâi starea când expiră.Dacă aveți aceeași cheie și aceeași cerere, sarcina inițială va fi returnată și nu se vor face deduceri repetate.

Citiți informațiile de bază înainte de a accesa

Convențiile de bază ale API-ului sunt următoarele. Confirmați acest conținut înainte de a începe să scrieți cod.

Tabelul 1 Convențiile de bază ale API

proiectilustra
Adresa URL de bazăhttps://omnidoc.top/api/v1
CertificareCheia API este plasată în antetul cererii X-API-Key și poate fi trimisă și ca acreditări Bearer; creat în consola API
Format de solicitareJSON, Tip de conținut: aplicație/json
Solicitați urmărireaSalvați X-Request-Id-ul fiecărui răspuns și furnizați-l atunci când contactați asistența
Limitarea curentuluiApăsați Retry-After pentru a încerca din nou când 429 este returnat

Ce fișiere sunt acceptate?

Acceptă Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown cu text, subtitrări SRT/ASS, imagini CSV, PNG/JPG și documente UniDoc (.udoc).

Cu excepția PPTX, toate celelalte formate acceptă ieșire bilingvă. Când PPTX solicită bilingvism, se returnează doar traducerea. Pentru metode de comparare specifice, consultați comparația de bază de mai jos.

Finalizați o traducere în patru pași

  1. Solicitați încărcare: sunați la POST /upload/presign, trimiteți numele și dimensiunea fișierului și obțineți adresa de transfer direct, încărcați antetul și finalize_token.
  2. Încărcați și confirmați: utilizați antetul de încărcare returnat pentru a Pune fișierul și nu aduceți cheia API la încărcare. Apoi apelați POST /upload/finalize în schimbul document.id.
  3. Creați sarcina: Apelați POST /jobs, trimiteți document_id și target_lang și este recomandat să aduceți Idempotency-Key în același timp.
  4. Preluați rezultatele: Sondați GET /jobs/{id} sau abonați-vă la progresul SSE sau configurați Webhook. După ce sarcina este finalizată, utilizați GET /artefacts?job_id=... pentru a obține produsul și a-l descărca.

Parametri comuni pentru crearea sarcinilor

Când creați o sarcină, cele două câmpuri cel mai frecvent utilizate sunt document_id și target_lang. Alte câmpuri sunt setate după cum este necesar.

Tabelul 2 Câmpuri POST/solicitare locuri de muncă

Domeniuimplicitilustra
document_id—ID-ul documentului confirmat (obligatoriu)
target_lang—Codul limbii țintă (obligatoriu)
source_langDetectare automatăcodul limbii sursă
enginexr-397bConfigurație traducere: xr-397b, deepseek, qwen, chatgpt, gemeni, claude
output_modebilingualcomparație bilingvă bilingvă, o singură traducere
glossary_id—ID de glosar, nume de marcă unificat și cuvinte profesionale
include_imagesfalseDacă să procesați textul imaginii în document
context_translationfalseContext îmbunătățit, terminologie mai consistentă
style_preset—Stil implicit

Exemplu Python: Creați o sarcină și așteptați finalizarea

Fragmentul de mai jos depinde doar de solicitări. Pentru procesul complet de încărcare și descărcare, vă rugăm să consultați pagina Python din documentația pentru dezvoltatori.

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)

Loturi și reîncercare: concurență, coadă și idempotență

Așezare automată la coadă

Fiecare cont poate procesa 5 fișiere simultan. Sarcinile care depășesc limita superioară sunt create și puse în coadă ca de obicei, iar stage_message va indica câte sarcini sunt înainte.

Chei idempotente

Dacă Idempotency-Key este aceeași și corpul cererii este același, sarcina inițială va fi returnată și nu va fi creată sau taxată în mod repetat. Când întâmpinați un timeout de rețea, verificați mai întâi starea sarcinii și nu retrimiteți cu o cheie nouă.

Cod de eroare

  • 403: Configurația selectată nu este permisă pentru Key.
  • 404: Documentația sau glosarul nu există.
  • 415: Formatul nu este acceptat.
  • 422: Fișierul este gol sau parametrii sunt invalidi.

Webhook: notifică-ți serverul când sarcina se termină

Fiecare utilizator poate configura 3 webhook-uri. Creați cu POST /webhooks, actualizați sau dezactivați cu PATCH.

Când o sarcină de traducere a fișierului se termină (indiferent de succes sau eșec), sistemul trimite evenimentul job.completed:

  • data.status este finalizată sau eșuată.
  • data.char_count este numărul de caractere de traducere.

Completați secretul atunci când creați un Webhook și fiecare apel invers ulterioar va aduce X-Webhook-Signature. Utilizați HMAC-SHA256 pentru a semna cererea inițială pentru a confirma sursa de apel invers.

Adresa URL de apel invers trebuie să fie accesibilă din rețeaua publică și se recomandă HTTPS.

Cum se calculează taxa?

Verificarea soldului înainte de a începe

  • PDF: soldul trebuie să fie mai mare decât „număr de pagini × 2 puncte".
  • Alte formate: taxat în funcție de numărul de cuvinte originale, cel puțin 2 puncte.
  • Când soldul este insuficient, sarcina se va încheia cu quota_exceeded și nu vor fi deduse taxe.

Deducere bazată pe utilizarea reală

După finalizarea sarcinii, taxele vor fi deduse în funcție de utilizarea reală. Dacă sarcina eșuează sau este anulată, nu vor fi deduse taxe.

Interogare gratuită

Punctele nu vor fi deduse pentru verificarea soldului, starea sarcinii, utilizare, vouchere și adrese de descărcare.

Pachet de puncte

Pachetele de puncte încep de la 9,9 ¥ pentru 3.000 de puncte, iar punctele achiziționate sunt valabile o perioadă lungă de timp. Pachetele aflate în vânzare pot fi solicitate prin GET /billing/credits/plans.

Următorul pas

Exemple complete de cURL, Python, Node.js pot fi vizualizate în documentația pentru dezvoltatori: https://docs.omnidoc.top/guide/quickstart/.

Dacă nu doriți să scrieți cod pentru moment, vă puteți conecta și la asistentul AI al OmniDoc pentru a traduce direct fișierele native. Pentru detalii, consultați „Lăsați AI să opereze direct Word, Excel și PPT": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.

📊 Comparație de bază

Diferitele formate de fișiere au metode de ieșire bilingve diferite. Puteți planifica în avans în funcție de propriul tip de fișier.

Tip de fișierMetoda de comparare bilingvăDacă să sprijine bilingv
WordComparați după paragrafDa
ExcelComparați după coloanăDa
PDFComparați după paginăDa
Subtitrări (SRT/ASS)Comparați după rândDa
PPTXReveniți numai la traducerenu

🎯 Ce metodă este potrivită pentru tine?

Dacă trebuie să procesați în loturi contracte, caietul de sarcini sau documente

Utilizați API pentru a vă conecta la sistem și a încărca automat, crea sarcini și descărca traduceri conform procesului în patru pași, eliminând operațiunile manuale.

Dacă rețeaua dvs. este adesea instabilă

Aduceți Idempotity-Key atunci când creați sarcina. Interogați starea mai întâi după expirarea timpului pentru a evita crearea sau deducerile repetate.

Dacă doriți să procesați sarcina imediat după ce se încheie

Configurați Webhook și completați secretul pentru verificarea semnăturii. Sistemul vă va notifica în mod proactiv serverul când sarcina este finalizată.

Dacă aveți cerințe unificate pentru vocabularul profesional

Creați mai întâi un glosar, apoi introduceți glossary_id când creați o sarcină pentru a unifica traducerea numelor de marcă și a cuvintelor profesionale.

❓ Întrebări frecvente (FAQ)

1. Vor fi deduse taxele în mod repetat dacă trimit aceeași sarcină în mod repetat?

Dacă Idempotency-Key este aceeași și corpul cererii este același, sarcina inițială va fi returnată fără crearea sau deducerea repetată.

2. Dacă sarcina eșuează sau este anulată, vor fi deduse puncte?

Nu se vor percepe taxe. Când o sarcină eșuează sau este anulată, nu se vor face deduceri.

3. Ce se întâmplă când punctele sunt insuficiente?

Sarcina se va încheia cu quota_exceeded și nu vor fi deduse taxe. Pragul de echilibru înainte de a începe este: PDF-ul necesită un echilibru mai mare decât „număr de pagini × 2 puncte", iar alte formate necesită un echilibru de cel puțin 2 puncte pe baza numărului de cuvinte.

4. Trebuie să aduc o cheie API când încarc fișiere?

inutil. Când utilizați fișierul PUT de antet de încărcare, nu aduceți cheia API.

5. Ce ar trebui să fac dacă întâlnesc o limită de trafic 429?

Reîncercați conform timpului Retry-After din răspuns.

📝 Rezumat

Prin însirarea de încărcări, crearea de sarcini, apeluri înapoi și descărcări într-un proces automat, traducerea documentelor poate fi integrată în activitatea de zi cu zi. Începeți prin a rula o sarcină cu un exemplu Python, apoi adăugați un glosar, ieșire bilingvă și webhook-uri după cum este necesar.

Încercați acum: încărcați documentul pentru a începe traducerea, păstrând aspectul original

Actualizat 2026-11-17