Przejdź do głównej zawartości

Wprowadź przepływy dokumentów do swojej aplikacji

Od przesyłania pojedynczego pliku przez jego tłumaczenie i sprawdzanie postępu po pobranie wyniku. Każdy krok jest objaśniony w kolejności integracji, z punktami dostępu do zarządzania plikami, przetwarzania dokumentów oraz usług audio i wideo.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · uwierzytelnianie za pomocą klucza API · tłumaczenie plików wykonywane jako zadania asynchroniczne

Ta strona opisuje interfejs API chmury HTTP.

01 Zacznij od żądania, które nie kosztuje żadnych kredytów

Dział zatytułowany „01 Zacznij od żądania, które nie kosztuje żadnych kredytów”

Upewnij się, że klucz i sieć działają przed przesłaniem plików. Sprawdzenie salda nie kosztuje żadnych kredytów ani nie generuje żadnego zadania tłumaczeniowego.

  1. Pobierz klucz API

    Zaloguj się do konsoli API i utwórz klucz rozpoczynający się od sk_. Użyj osobnego klucza dla każdej aplikacji i określ jego budżet.

    Klucz działa dla konta, które go utworzyło. Przechowuj go na serwerze i odczytuj z zmiennej środowiskowej; nigdy nie umieszczaj go w kodzie źródłowym strony internetowej ani w publicznym repozytorium.

  2. Sprawdź saldo

    Ustaw zmienną środowiskową OMNIDOC_API_KEY, a następnie uruchom dowolny z poniższych przykładów. Sukces oznacza kod JSON; 401 oznacza, że klucz ma problem i wymaga sprawdzenia. Nigdy nie wyświetlaj pełnego klucza w zgłoszeniach, zrzutach ekranu ani logach.

    Okno terminala
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Pomyślne przesłanie pliku oznacza jedynie, że został on zapisany. Po utworzeniu zadania należy poczekać, aż osiągnie ono stan finalny, a następnie pobrać i wyświetlić jego wyniki.

KrokMetoda i ścieżkaCo należy zachować
Poproś o przesłaniePOST /upload/presignupload_url, upload_headers, finalize_token
Wyślij plikPUT do zwracanego upload_urlOdpowiedź oznaczająca sukces; żądanie to nie zawiera klucza API.
Potwierdź przesyłaniePOST /upload/finalizedocument.id
Utwórz tłumaczeniePOST /jobsZadanie id
Sprawdź statusGET /jobs/{job_id}completed lub failed
Wyświetl wynikiGET /artifacts?job_id={job_id}Identyfikatory i formaty artefaktów
Pobierz wynikGET /artifacts/{artifact_id}/downloadBajty pliku i nazwa pliku odpowiedzi

W przypadku przesyłania bezpośredniego wyślij upload_headers z serwera dokładnie tak, jak zostało zwrócone, i nigdy nie wysyłaj X-API-Key na adres pamięci masowej. Jeśli adres przesyłania wygaśnie lub przekazanie nie powiedzie się, poproś o nowy. Szczegóły: protokół przesyłania, szybki start, kompletny przepływ pracy Node.js oraz polia żądania tłumaczenia.

Każdy wpis zawiera listę ścieżek, pól żądania i przykładów. Status usługi Twojego konta oraz limity Twojego klucza dotyczą wszystkich z nich.

Klucz API identyfikuje konto. Nie jest to publiczne hasło do pobrania pliku.

Nagłówek żądania

Użyj X-API-Key: sk_… lub Authorization: Bearer sk_…, tylko jeden z nich na każde żądanie. Prześlij Content-Type: application/json wraz z ciałami JSON.

Co może osiągnąć klucz

Klucz ma dostęp wyłącznie do zasobów, których może używać jego konto; nadal obowiązują status usługi, budżet klucza oraz zezwolone ustawienia tłumaczenia. Modyfikacje konta oraz tworzenie, rotacja lub unieważnianie kluczy dokonywane są w konsoli.

Zobacz autoryzacja, budżety i rotacja oraz usługi i uprawnienia .

05 Wbudowanie obsługi awarii kompilacji w proces integracji

Dział zatytułowany „05 Wbudowanie obsługi awarii kompilacji w proces integracji”

Czas oczekiwania na timeout nie oznacza, że zadanie nie zostało utworzone. Rozróżnij błędy podlegające ponownej próbie wykonania od żądań wymagających naprawy, aby żadne dane nie zostały przesłane lub przetworzone dwa razy.

  • Idempotentne tworzenie : generuj Idempotency-Key dla każdej nowej operacji tworzenia; podczas ponownego wykonania tej samej operacji użyj ponownie oryginalnego klucza i dokładnie takiego samego ciała żądania. Operacje dokumentów, zadania multimedialne i tworzenie głosu wymagają tego klucza; dla innych punktów końcowych tworzenia zobacz ich strony referencyjne.
  • Asynchroniczne powiadomienia : pobieranie listy co jakiś czas jest odpowiednie dla pierwszej integracji; aby śledzić postęp w czasie rzeczywistym, użyj SSE , a aby otrzymywać ostateczne stanu w tle, skorzystaj z webhook .
StatusSprawdź najpierwCo zrobić
401 / 403Klucz, uprawnienia, własność zasobówPopraw dane uwierzytelniające lub uprawnienia; nie ponawiaj próby bezwzględnie.
402Dostępne kredytyDoładuj, a następnie wyślij ponownie
409Klucz i treść idempotencji, stan zasobuPrzed rozpoczęciem nowej operacji należy zapytać o poprzednią.
422Błędy pola w odpowiedziPopraw parametry lub plik
429Biznes code i Retry-AfterOgraniczenia dotyczące częstotliwości i kolejki można przejść w oczekiwaniu; przed podniesieniem limitu klucza należy najpierw wykorzystać dostępny budżet.
5xxTemporary service errorOgraniczony eksponencjalny backoff; zachowaj klucz idempotencji dla żądań create

Zachowaj nagłówek odpowiedzi X-Request-Id, czas żądania i ścieżkę do rozwiązywania problemów; nigdy nie loguj pełnego klucza. Wszystkie kody błędów i przykłady powtórnego próbowania znajdują się w odniesieniu do błędów .

06 Sprawdź, jak działa rozliczanie, zanim dokonasz integracji

Dział zatytułowany „06 Sprawdź, jak działa rozliczanie, zanim dokonasz integracji”

Brak kredytów

Przesyłanie, sprawdzanie zadań, pobieranie wyników oraz odczytywanie salda i rekordów rozliczeń nie kosztują żadnych kredytów; podobnie jak słowniki, projekty, tagi, wyszukiwanie i udostępnianie.

Rozliczane według zużycia

Tłumaczenie plików, narzędzia do dokumentów, tłumaczenie natychmiastowe oraz usługi audio i wideo są rozliczane według rzeczywistego zużycia; utworzenie zadania nie stanowi ostatecznego opłaty.

Przed rozpoczęciem zadania sprawdzany jest tylko próg salda; po jego zakończeniu naliczane jest rzeczywiste zużycie. Jeśli saldo okazuje się niewystarczające, różnica zostaje zaksięgowana jako dług, a otrzymane później kredyty są stosowane w pierwszej kolejności do jego spłaty. Możesz rozliczyć opłaty i zwroty zarówno dla poszczególnych zadań, jak i dla pojedynczych operacji kredytowych. Gdy budżet klucza zostanie wykorzystany, nadal możesz przeglądać zadania, wyniki i zapisy przypisane do tego klucza.