Заголовок запроса
Используйте 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, время запроса и путь для устранения неполадок; никогда не записывайте полный ключ. Все коды ошибок и примеры повторных попыток находятся в справочнике об ошибках . .
Без кредитов
Загрузка, проверка заданий, загрузка результатов, а также чтение баланса и записей о расчетах не потребуют кредитов; то же самое относится к глоссариям, проектам, тегам, поиску и обмену.
Оплата по фактическому использованию
Перевод файлов, инструменты для работы с документами, мгновенный перевод, а также аудио- и видеосервисы тарифицируются по фактическому использованию; создание задания не является окончательной платой.
Перед началом выполнения задания проверяется только порог остатка; после его завершения тарифицируется фактическое потребление. Если остатка недостаточно, разница фиксируется как долг, и поступающие позже кредиты списываются в первую очередь. Вы можете сверять начисления и возвраты по каждому заданию или по каждой операции с кредитами. Когда бюджет ключа исчерпан, вы по‑прежнему можете запрашивать задания, результаты и записи, связанные с этим ключом.