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.
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.
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.
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.
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.
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());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.
| Krok | Metoda i ścieżka | Co należy zachować |
|---|---|---|
| Poproś o przesłanie | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Wyślij plik | PUT do zwracanego upload_url | Odpowiedź oznaczająca sukces; żądanie to nie zawiera klucza API. |
| Potwierdź przesyłanie | POST /upload/finalize | document.id |
| Utwórz tłumaczenie | POST /jobs | Zadanie id |
| Sprawdź status | GET /jobs/{job_id} | completed lub failed |
| Wyświetl wyniki | GET /artifacts?job_id={job_id} | Identyfikatory i formaty artefaktów |
| Pobierz wynik | GET /artifacts/{artifact_id}/download | Bajty 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 .
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.
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.| Status | Sprawdź najpierw | Co zrobić |
|---|---|---|
401 / 403 | Klucz, uprawnienia, własność zasobów | Popraw dane uwierzytelniające lub uprawnienia; nie ponawiaj próby bezwzględnie. |
402 | Dostępne kredyty | Doładuj, a następnie wyślij ponownie |
409 | Klucz i treść idempotencji, stan zasobu | Przed rozpoczęciem nowej operacji należy zapytać o poprzednią. |
422 | Błędy pola w odpowiedzi | Popraw parametry lub plik |
429 | Biznes code i Retry-After | Ograniczenia dotyczące częstotliwości i kolejki można przejść w oczekiwaniu; przed podniesieniem limitu klucza należy najpierw wykorzystać dostępny budżet. |
5xx | Temporary service error | Ograniczony 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 .
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.