Создать задание на перевод
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| Поле | Тип | Обязательно | По умолчанию | Описание |
|---|---|---|---|---|
document_id | строка | ✅ | — | ID подтверждённого документа |
target_lang | строка | ✅ | — | Код целевого языка |
source_lang | строка | — | Автоматическое определение | Код исходного языка |
engine | строка | — | xr-397b | Идентификатор настроек перевода, см. настройки перевода |
output_mode | строка | — | bilingual | single или bilingual |
glossary_id | строка | — | — | Идентификатор глоссария для этой учётной записи. Глоссарии предназначены для платящих учётных записей (как минимум один успешный платёж); неоплаченная учётная запись, отправившая один платёж, получает 403 |
include_images | булевый | — | false | Также переведите текст на изображениях в документе. |
context_translation | булевый | — | false | Включить улучшение контекста |
style_preset | строка | — | — | Стилевой пресет |
Созданный задание помещается в очередь. Каждая учётная запись обрабатывает одновременно до 5 файлов; при этом новые задания продолжают создаваться и автоматически добавляются в очередь, начиная обработку по мере завершения предыдущих. Пока задание находится в ожидании, его stage_message указывает, сколько заданий находятся перед ним.
Перед началом задания баланс проверяется по пороговому значению: для формата PDF требуется баланс выше «страницы × 2 кредита»; для других форматов — длина исходного текста, минимум 2 кредита. Если баланс не позволяет начать файл, это задание завершается с кодами status=failed и quota_exceeded=true, плата не взимается, и другие задания не затрагиваются. По завершении задания списывается фактическое потребление; если стоимость превышает баланс, он становится отрицательным, пришедшие позже кредиты сначала погашают долг, а новые задания не могут быть запущены, пока баланс отрицательный, поэтому необходимо пополнить счет. См. кредиты и использование .
curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \ -H "X-API-Key: $OMNIDOC_API_KEY" \ -H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \ -H "Content-Type: application/json" \ -d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'Ответ 201 (серверный stage_message на китайском языке):
{ "id": "q3f8s6c2a9m1k4tx", "document_id": "4q8mx2q9z1k7p6ra", "source_lang": null, "target_lang": "en", "engine": "xr-397b", "status": "pending", "stage": "queued", "stage_progress": 0, "stage_message": "排队中", "time_cost": 0, "error_msg": null, "quota_exceeded": false, "queue_position": null, "created_at": "2026-10-01T12:01:00Z", "updated_at": "2026-10-01T12:01:00Z"}| Статус | Причина |
|---|---|
403 | Ключ не поддерживает выбранный параметр, либо для неоплаченного аккаунта отправлено glossary_id |
404 | Документ или глоссарий не существует, был удалён или принадлежит другой учётной записи. |
415 | Формат файла не подлежит преобразованию |
422 | Файл пуст, не содержит переводимого текста или параметр недопустим. |
429 | Слишком много запросов или очередь заполнена; повторите попытку через Retry-After |
Идемпотентность
Заголовок раздела «Идемпотентность»Idempotency-Key является необязательным, но рекомендуется для каждого отправления. Ключ состоит из 1–128 видимых символов ASCII и остаётся действительным бессрочно для одного и того же удостоверения:
- Один и тот же ключ, одна и та же база данных: возвращается исходное задание (включая неудачное); ничего не создаётся и не оплачивается дважды.
- Один и тот же ключ, разные корпуса:
409(idempotency_request_conflict). - Исходное задание удалено:
410(idempotency_job_gone).
Используйте новый UUID для каждой новой отправки и повторно применяйте исходный ключ только при повторной попытке отправить ту же самую заявку.