Перейти до вмісту

Інтегруйте робочі процеси документів у своє додаток

Від завантаження одного файлу до його перекладу, перевірки прогресу та завантаження результату. Кожний крок пояснюється у порядку інтеграції, з точками входу для управління файлами, обробки документів та аудіо- і відеосервісів.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Аутентифікація за ключем API · переклад файлів виконується як асинхронні завдання

Цей сайт описує хмарний API HTTP.

01 Почніть із запиту, який не коштує жодних кредитів

Section titled “01 Почніть із запиту, який не коштує жодних кредитів”

Перш ніж завантажувати файли, переконайтеся, що ваш ключ та мережа працюють. Перевірка балансу не зменшує кількість кредитів і не створює завдання перекладу.

  1. Отримати ключ API

    Увійдіть у консоль API і створіть ключ, що починається з sk_. Використовуйте окремий ключ для кожного додатка та встановіть для нього бюджет.

    Ключ діє лише для облікового запису, який його створив. Зберігайте його на сервері та отримуйте зміст із змінної середовища; ніколи не розміщуйте його у вихідному коді веб-сторінки або публічному репозиторії.

  2. Перевірте баланс

    Установіть змінну середовища OMNIDOC_API_KEY, а потім запустіть будь-який із наведених нижче прикладів. Успішне виконання повертає JSON; 401 означає, що ключ має проблему і потребує перевірки. Ніколи не відображайте повний ключ у тикетах, скріншотах або логах.

    Terminal window
    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"

Успішне завантаження означає лише те, що файл збережено. Після створення завдання дочекайтеся, поки воно набуде кінцевого стану, а потім отримайте та завантажте його результати.

КрокМетод і шляхЩо потрібно зберегти
Запитати завантаженняPOST /upload/presignupload_url, upload_headers, finalize_token
Надішліть файлPUT до повернутого upload_urlВідповідь про успішне виконання; цей запит не містить ключа API.
Підтвердьте завантаженняPOST /upload/finalizedocument.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 та поля запиту на переклад .

03 Знайдіть кінцеву точку для вашого завдання

Section titled “03 Знайдіть кінцеву точку для вашого завдання”

Кожен запис містить шляхи, поля запиту та приклади. Статус послуги вашого облікового запису та ліміти вашого ключа застосовуються до всіх них.

04 Аутентифікація та власність на ресурси

Section titled “04 Аутентифікація та власність на ресурси”

Ключ API ідентифікує обліковий запис. Це не загальнодоступний пароль для завантаження файлу.

Заголовок запиту

Використовуйте X-API-Key: sk_… або Authorization: Bearer sk_…, лише один із двох за запитом. Надсилайте Content-Type: application/json разом із тілами JSON.

Що може охопити ключ

Ключ має доступ лише до ресурсів, якими може користуватися його обліковий запис; статус послуги, бюджет ключа та дозволені налаштування перекладу залишаються чинними. Зміни в обліковому записі, а також створення, обертання або скасування ключів здійснюються в консолі.

Див. аутентифікація, бюджети та ротація і послуги та дозволи .

05 Інтеграція обробки помилок зборки

Section titled “05 Інтеграція обробки помилок зборки”

Таймаут не означає, що завдання не було створено. Розрізняйте помилки, які можна повторити, та запити, що потребують виправлення, щоб жоден елемент не надсилався або не оброблявся двічі.

  • Ідемпотентне створення : генеруйте Idempotency-Key для кожного нового операції створення; під час повторного виконання тієї ж самої операції використовуйте оригінальний ключ і точне те саме тіло запиту. Операції з документування, завдання мультимедіа та створення голосу потребують ключа; для інших ендпоїнтів створення див. їхні довідкові сторінки.
  • Асинхронні сповіщення : опитування підходить для першої інтеграції; для постійного відстеження прогресу використовуйте SSE , а для отримання кінцевих станів у фоновому режимі — webhook .
СтатусСпершу перевіртеЩо робити
401 / 403Ключ, дозволи, власність на ресурсВиправте облікові дані або права доступу; не повторюйте спробу бездумно.
402Доступні кредитиПоповніть рахунок, а потім надішліть запит ще раз.
409Ключ і тіло ідемпотентності, стан ресурсуЗапитайте початкову операцію перед запуском нової
422Помилки поля відповідіВиправте параметри або файл
429Бізнес code та Retry-AfterЛіміти швидкості та черги можна просто дочекатися; спочатку потрібно збільшити вичерпаний бюджет ключа.
5xxТимчасова помилка службиОбмежений експоненціальний зсув; зберігайте ключ ідемпотентності для запитів на створення

Зберігайте заголовок відповіді X-Request-Id, час запиту та шлях для усунення несправностей; ніколи не записуйте повний ключ. Усі коди помилок та приклади повторних спроб містяться у довідці про помилки . .

06 Перевірте, як працює тарифікація, перш ніж інтегрувати

Section titled “06 Перевірте, як працює тарифікація, перш ніж інтегрувати”

Без кредитів

Завантаження, перевірка завдань, завантаження результатів та перегляд балансу й записів розрахунків не вимагають кредитів; так само як і глосарії, проекти, теги, пошук і спільне використання.

Тарифікується за обсягом використання

Переклад файлів, інструменти для документів, миттєвий переклад та аудіо- й відеосервіси оплачуються за фактичним обсягом використання; створення завдання не є остаточною оплатою.

Перед початком завдання перевіряється лише поріг балансу; після його завершення тарифікується фактичне використання. Якщо баланс недостатній, різниця фіксується як заборгованість, і надходження кредитів спочатку списуються саме на неї. Ви можете збалансувати оплати та повернення коштів за кожним завданням або окремо за кожною операцією з кредитами. Коли бюджет ключа вичерпаний, ви все одно можете отримувати запити щодо завдань, результатів та записів, пов’язаних із цим ключем.