Заголовок запиту
Використовуйте X-API-Key: sk_… або Authorization: Bearer sk_…, лише один із двох за запитом. Надсилайте Content-Type: application/json разом із тілами JSON.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Аутентифікація за ключем API · переклад файлів виконується як асинхронні завдання
Цей сайт описує хмарний API HTTP.
Перш ніж завантажувати файли, переконайтеся, що ваш ключ та мережа працюють. Перевірка балансу не зменшує кількість кредитів і не створює завдання перекладу.
Отримати ключ API
Увійдіть у консоль API і створіть ключ, що починається з sk_. Використовуйте окремий ключ для кожного додатка та встановіть для нього бюджет.
Ключ діє лише для облікового запису, який його створив. Зберігайте його на сервері та отримуйте зміст із змінної середовища; ніколи не розміщуйте його у вихідному коді веб-сторінки або публічному репозиторії.
Перевірте баланс
Установіть змінну середовища OMNIDOC_API_KEY, а потім запустіть будь-який із наведених нижче прикладів. Успішне виконання повертає JSON; 401 означає, що ключ має проблему і потребує перевірки. Ніколи не відображайте повний ключ у тикетах, скріншотах або логах.
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());Успішне завантаження означає лише те, що файл збережено. Після створення завдання дочекайтеся, поки воно набуде кінцевого стану, а потім отримайте та завантажте його результати.
| Крок | Метод і шлях | Що потрібно зберегти |
|---|---|---|
| Запитати завантаження | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Надішліть файл | PUT до повернутого upload_url | Відповідь про успішне виконання; цей запит не містить ключа API. |
| Підтвердьте завантаження | POST /upload/finalize | document.id |
| Створіть переклад | POST /jobs | Робота id |
| Перевірте стан | GET /jobs/{job_id} | completed або failed |
| Перелічіть результати | GET /artifacts?job_id={job_id} | Ідентифікатори та формати артефактів |
| Завантажити результат | GET /artifacts/{artifact_id}/download | Байти файлу та ім’я файлу відповіді |
Для прямого завантаження надсилайте upload_headers з сервера саме у такому вигляді, як він був повернутий, і ніколи не надсилайте X-API-Key за адресою сховища. Якщо термін дії адреси завантаження закінчився або передача завершилася невдачею, запитайте нову. Деталі: протокол завантаження , швидкий старт , повний робочий процес Node.js та поля запиту на переклад .
Кожен запис містить шляхи, поля запиту та приклади. Статус послуги вашого облікового запису та ліміти вашого ключа застосовуються до всіх них.
Ключ API ідентифікує обліковий запис. Це не загальнодоступний пароль для завантаження файлу.
Заголовок запиту
Використовуйте X-API-Key: sk_… або Authorization: Bearer sk_…, лише один із двох за запитом. Надсилайте Content-Type: application/json разом із тілами JSON.
Що може охопити ключ
Ключ має доступ лише до ресурсів, якими може користуватися його обліковий запис; статус послуги, бюджет ключа та дозволені налаштування перекладу залишаються чинними. Зміни в обліковому записі, а також створення, обертання або скасування ключів здійснюються в консолі.
Див. аутентифікація, бюджети та ротація і послуги та дозволи .
Таймаут не означає, що завдання не було створено. Розрізняйте помилки, які можна повторити, та запити, що потребують виправлення, щоб жоден елемент не надсилався або не оброблявся двічі.
Idempotency-Key для кожного нового операції створення; під час повторного виконання тієї ж самої операції використовуйте оригінальний ключ і точне те саме тіло запиту. Операції з документування, завдання мультимедіа та створення голосу потребують ключа; для інших ендпоїнтів створення див. їхні довідкові сторінки.| Статус | Спершу перевірте | Що робити |
|---|---|---|
401 / 403 | Ключ, дозволи, власність на ресурс | Виправте облікові дані або права доступу; не повторюйте спробу бездумно. |
402 | Доступні кредити | Поповніть рахунок, а потім надішліть запит ще раз. |
409 | Ключ і тіло ідемпотентності, стан ресурсу | Запитайте початкову операцію перед запуском нової |
422 | Помилки поля відповіді | Виправте параметри або файл |
429 | Бізнес code та Retry-After | Ліміти швидкості та черги можна просто дочекатися; спочатку потрібно збільшити вичерпаний бюджет ключа. |
5xx | Тимчасова помилка служби | Обмежений експоненціальний зсув; зберігайте ключ ідемпотентності для запитів на створення |
Зберігайте заголовок відповіді X-Request-Id, час запиту та шлях для усунення несправностей; ніколи не записуйте повний ключ. Усі коди помилок та приклади повторних спроб містяться у довідці про помилки . .
Без кредитів
Завантаження, перевірка завдань, завантаження результатів та перегляд балансу й записів розрахунків не вимагають кредитів; так само як і глосарії, проекти, теги, пошук і спільне використання.
Тарифікується за обсягом використання
Переклад файлів, інструменти для документів, миттєвий переклад та аудіо- й відеосервіси оплачуються за фактичним обсягом використання; створення завдання не є остаточною оплатою.
Перед початком завдання перевіряється лише поріг балансу; після його завершення тарифікується фактичне використання. Якщо баланс недостатній, різниця фіксується як заборгованість, і надходження кредитів спочатку списуються саме на неї. Ви можете збалансувати оплати та повернення коштів за кожним завданням або окремо за кожною операцією з кредитами. Коли бюджет ключа вичерпаний, ви все одно можете отримувати запити щодо завдань, результатів та записів, пов’язаних із цим ключем.