Перейти к содержимому

Интегрируйте документооборот в ваше приложение

От загрузки одного файла до его перевода, проверки прогресса и скачивания результата. Каждый шаг описан в порядке интеграции, с доступом к управлению файлами, обработке документов и аудио- и видеосервисам.

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

Этот сайт описывает облачный API HTTP.

01 Начните с запроса, который не требует кредитов

Заголовок раздела «01 Начните с запроса, который не требует кредитов»

Перед загрузкой файлов убедитесь, что ваш ключ и сеть работают. Проверка баланса не потребует кредитов и не создаст задание на перевод.

  1. Получить ключ API

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

    Ключ действует для той учётной записи, которая его создала. Храните его на сервере и читайте из переменной окружения; никогда не размещайте его в исходном коде веб-страницы или в общедоступном репозитории.

  2. Проверить баланс

    Установите переменную окружения 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"

Успешная загрузка означает лишь, что файл сохранён. После создания задания дождитесь его перехода в конечное состояние, затем выведите и загрузите результаты.

ШагМетод и путьЧто следует сохранить
Запросить загрузку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 Найдите конечную точку для вашей задачи

Заголовок раздела «03 Найдите конечную точку для вашей задачи»

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

Ключ API идентифицирует учётную запись. Это не общедоступный пароль для загрузки файла.

Заголовок запроса

Используйте X-API-Key: sk_… или Authorization: Bearer sk_…, только один из двух по каждому запросу. Отправляйте Content-Type: application/json с телами JSON.

Что может охватить ключ

Ключ имеет доступ только к тем ресурсам, которые может использовать его аккаунт; при этом по‑прежнему применяются настройки службы, лимиты ключа и разрешённые параметры перевода. Изменения в аккаунте, а также создание, обновление или отзыв ключей выполняются в консоли.

См. аутентификация, бюджеты и ротация и службы и разрешения .

05 Включите обработку сбоев сборки в интеграцию

Заголовок раздела «05 Включите обработку сбоев сборки в интеграцию»

Тайм-аут не означает, что задание не было создано. Разделяйте повторяемые ошибки и запросы, требующие исправления, чтобы ни одна операция не была отправлена или обработана дважды.

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

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

06 Проверьте, как работает выставление счетов, прежде чем выполнять интеграцию

Заголовок раздела «06 Проверьте, как работает выставление счетов, прежде чем выполнять интеграцию»

Без кредитов

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

Оплата по фактическому использованию

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

Перед началом выполнения задания проверяется только порог остатка; после его завершения тарифицируется фактическое потребление. Если остатка недостаточно, разница фиксируется как долг, и поступающие позже кредиты списываются в первую очередь. Вы можете сверять начисления и возвраты по каждому заданию или по каждой операции с кредитами. Когда бюджет ключа исчерпан, вы по‑прежнему можете запрашивать задания, результаты и записи, связанные с этим ключом.