Przewodnik po dostępie do interfejsu API tłumaczenia dokumentów: Użyj języka Python do zbiorczego tłumaczenia plików Word i PDF oraz użyj elementu Webhook, aby otrzymać wyniki

Interfejs API tłumaczenia dokumentów może przesyłać ciągi znaków, tworzyć zadania, odbierać wywołania zwrotne i pobierać tłumaczenia w zautomatyzowanym procesie. Pełne tłumaczenie możesz wykonać w zaledwie czterech krokach.

Jeśli Twój system codziennie przetwarza umowy, instrukcje, dokumenty lub raporty, ręczne przesyłanie, oczekiwanie i pobieranie szybko stanie się wąskim gardłem. Tylko przekazanie tych kroków programowi może zapewnić stabilność przetwarzania wsadowego.

Interfejs API tłumaczenia dokumentów OmniDoc (Zhiyi) łączy cały proces: Przesyłaj pliki, twórz zadania, otrzymuj powiadomienia o zakończeniu i pobieraj tłumaczenia. Tłumaczenie zachowuje układ, tabele, obrazy i formuły oryginalnego dokumentu i może generować porównania dwujęzyczne lub tylko tłumaczenie.

Ten artykuł jest odpowiedni dla programistów, którzy chcą zintegrować tłumaczenie dokumentów ze swoimi własnymi systemami. Po przeczytaniu będziesz w stanie opanować cały proces wywoływania, typowe parametry, idempotentne metody ponawiania prób, wywołania zwrotne webhooka i zasady rozliczeń, a także będziesz w stanie uruchomić całe zadanie przy użyciu języka Python.

Jak uzyskać dostęp do interfejsu API tłumaczenia dokumentów? Wniosek w jednym zdaniu

Możesz zintegrować tłumaczenie dokumentów ze swoim własnym systemem, korzystając z interfejsu API do automatycznego przesyłania, tworzenia zadań, odbierania połączeń zwrotnych i pobierania tłumaczeń w czteroetapowym procesie.

Tabela 0 Scenariusze dostępu i zalecane praktyki

Przeczytaj podstawowe informacje przed uzyskaniem dostępu

Podstawowe konwencje API są następujące. Potwierdź tę zawartość przed rozpoczęciem pisania kodu.

Tabela 1 Podstawowe konwencje API

Które pliki są obsługiwane?

Obsługuje programy Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown z tekstem, napisy SRT/ASS, obrazy CSV, PNG/JPG i dokumenty UniDoc (.udoc).

Z wyjątkiem PPTX, wszystkie inne formaty obsługują wydruk dwujęzyczny. Kiedy PPTX żąda dwujęzyczności, zwracane jest tylko tłumaczenie. Aby zapoznać się z konkretnymi metodami porównawczymi, zobacz podstawowe porównanie poniżej.

Dokończ tłumaczenie w czterech krokach

1. Wystąp o przesłanie: Wywołaj POST /upload/presign, podaj nazwę i rozmiar pliku oraz uzyskaj adres bezpośredniego przesyłania, nagłówek przesyłania i token finalizacji.
2. Prześlij i potwierdź: Użyj zwróconego nagłówka przesyłania, aby umieścić plik i nie przynoś klucza API podczas przesyłania. Następnie wywołaj POST /upload/finalize w zamian za document.id.
3. Utwórz zadanie: Wywołaj POST /jobs, prześlij identyfikator_dokumentu i język_docelowy. Zalecane jest jednoczesne zabranie klucza Idempotency-Key.
4. Pobierz wyniki: Odpytaj GET /jobs/{id}, zasubskrybuj postęp SSE lub skonfiguruj Webhook. Po zakończeniu zadania użyj GET /artifacts?job_id=..., aby uzyskać produkt i pobrać go.

Wspólne parametry tworzenia zadań

Podczas tworzenia zadania dwa najczęściej używane pola to document_id i target_lang. Pozostałe pola ustawia się według potrzeb.

Tabela 2 Pola żądania POST /jobs

Przykład w Pythonie: Utwórz zadanie i poczekaj na jego zakończenie

Poniższy fragment zależy tylko od żądań. Aby zapoznać się z pełnym procesem przesyłania i pobierania, zapoznaj się ze stroną Pythona w dokumentacji dla programistów.

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)

Baterie i ponawianie prób: współbieżność, kolejkowanie i idempotencja

Automatyczne kolejkowanie

Każde konto może przetwarzać jednocześnie 5 plików. Zadania przekraczające górny limit są tworzone i umieszczane w kolejce w zwykły sposób, a komunikat stage_message wskaże, ile zadań jest przed nami.

Klucze idempotentne

Jeśli klucz Idempotentności jest taki sam i treść żądania jest taka sama, oryginalne zadanie zostanie zwrócone i nie będzie wielokrotnie tworzone ani obciążane. W przypadku przekroczenia limitu czasu sieci sprawdź najpierw stan zadania i nie przesyłaj go ponownie z nowym kluczem.

Kod błędu

• 403: Wybrana konfiguracja nie jest dozwolona dla klucza.
• 404: Dokumentacja lub glosariusz nie istnieje.
• 415: Format nie jest obsługiwany.
• 422: Plik jest pusty lub parametry są nieprawidłowe.

Webhook: Powiadom swój serwer po zakończeniu zadania

Każdy użytkownik może skonfigurować 3 webhooki. Twórz za pomocą POST /webhooks, aktualizuj lub dezaktywuj za pomocą PATCH.

Po zakończeniu zadania tłumaczenia pliku (niezależnie od powodzenia lub niepowodzenia) system wysyła zdarzenie job.completed:

• data.status została ukończona lub nie powiodła się.
• data.char_count to liczba znaków tłumaczenia.

Wpisz sekret podczas tworzenia webhooka, a każde kolejne wywołanie zwrotne przyniesie X-Webhook-Signature. Użyj HMAC-SHA256, aby podpisać oryginalne żądanie w celu potwierdzenia źródła wywołania zwrotnego.

Adres URL wywołania zwrotnego musi być dostępny z sieci publicznej i zalecany jest protokół HTTPS.

Jak obliczyć opłatę?

Sprawdź saldo przed rozpoczęciem

• PDF: Saldo musi być wyższe niż „liczba stron × 2 punkty".
• Inne formaty: opłata na podstawie liczby oryginalnych słów, co najmniej 2 punkty.
• Gdy saldo będzie niewystarczające, zadanie zakończy się kwotą_przekroczoną i nie zostaną pobrane żadne opłaty.

Odliczenie na podstawie rzeczywistego zużycia

Po wykonaniu zadania opłaty zostaną potrącone na podstawie rzeczywistego wykorzystania. Jeśli zadanie nie powiedzie się lub zostanie anulowane, nie zostaną pobrane żadne opłaty.

Bezpłatne zapytanie

Punkty nie zostaną odjęte za sprawdzenie salda, statusu zadania, wykorzystania, kuponów i adresów do pobrania.

Pakiet punktów

Pakiety punktowe zaczynają się od 9,9 jenów za 3000 punktów, a zakupione punkty zachowują ważność przez długi czas. Pakiety objęte promocją można sprawdzić poprzez GET /billing/credits/plans.

Następny krok

Kompletne przykłady cURL, Python, Node.js można zobaczyć w dokumentacji programisty: https://docs.omnidoc.top/guide/quickstart/.

Jeśli na razie nie chcesz pisać kodu, możesz także połączyć się z asystentem AI OmniDoc, aby bezpośrednio tłumaczyć pliki natywne. Aby uzyskać szczegółowe informacje, zobacz „Pozwól sztucznej inteligencji bezpośrednio obsługiwać programy Word, Excel i PPT": https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.

📊 Porównanie rdzeni

Różne formaty plików mają różne dwujęzyczne metody wyjściowe. Możesz planować z wyprzedzeniem, zgodnie z własnym typem pliku.

🎯 Która metoda jest dla Ciebie odpowiednia?

Jeśli chcesz przetwarzać wsadowo umowy, specyfikacje lub dokumenty

Użyj API, aby połączyć się z systemem i automatycznie przesyłać, tworzyć zadania i pobierać tłumaczenia zgodnie z czteroetapowym procesem, eliminując operacje ręczne.

Jeśli Twoja sieć często jest niestabilna

Podczas tworzenia zadania zabierz ze sobą klucz Idempotencji. Najpierw zapytaj o status po upływie limitu czasu, aby uniknąć wielokrotnego tworzenia lub powtarzających się odliczeń.

Jeśli chcesz przetworzyć zadanie natychmiast po jego zakończeniu

Skonfiguruj Webhook i wpisz sekret do weryfikacji podpisu. System aktywnie powiadomi Twój serwer o zakończeniu zadania.

Jeśli masz ujednolicone wymagania dotyczące słownictwa zawodowego

Najpierw utwórz glosariusz, a następnie podczas tworzenia zadania podaj glossary_id, aby ujednolicić tłumaczenie nazw marek i słów zawodowych.

❓ Często zadawane pytania (FAQ)

1. Czy za wielokrotne przesyłanie tego samego zadania będą wielokrotne odliczenia?

Jeśli klucz Idempotencji jest taki sam i treść żądania jest taka sama, oryginalne zadanie zostanie zwrócone bez ponownego tworzenia lub odliczania.

2. Czy w przypadku niepowodzenia zadania lub anulowania zadania zostaną odjęte punkty?

Żadne opłaty nie będą pobierane. Jeśli zadanie nie powiedzie się lub zostanie anulowane, nie zostaną dokonane żadne potrącenia.

3. Co się stanie, jeśli nie będzie wystarczającej liczby punktów?

Zadanie zakończy się kwotą_przekroczoną i nie zostaną pobrane żadne opłaty. Próg salda przed rozpoczęciem wynosi: PDF wymaga salda wyższego niż „liczba stron × 2 punkty", a inne formaty wymagają salda co najmniej 2 punktów w oparciu o liczbę słów.

4. Czy muszę mieć przy sobie klucz API podczas przesyłania plików?

niepotrzebny. Korzystając z pliku nagłówka przesyłania PUT, nie zabieraj klucza API.

5. Co powinienem zrobić, jeśli napotkam limit ruchu 429?

Ponów próbę zgodnie z czasem Retry-After w odpowiedzi.

📝 Podsumowanie

Łącząc przesyłanie, tworzenie zadań, wywołania zwrotne i pobieranie w zautomatyzowany proces, tłumaczenie dokumentów można zintegrować z codzienną działalnością. Zacznij od wykonania zadania z przykładem języka Python, a następnie dodaj słownik, dwujęzyczne dane wyjściowe i elementy webhooki, jeśli to konieczne.

Wypróbuj teraz: prześlij dokument, aby rozpocząć tłumaczenie, zachowując oryginalny układ