Створити завдання перекладу
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| Поле | Тип | Обов’язково | За замовчуванням | Опис |
|---|---|---|---|---|
document_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, жодна сума не списується, і інші завдання не впливають. Після завершення завдання оплачується фактичне використання; якщо вартість перевищує баланс, баланс стає від’ємним, прийняті пізніше кредити спочатку погашають заборгованість, а нові завдання не можуть розпочинатися, поки баланс від’ємний, тому слід поповнити рахунок. Див. кредити та використання .
Приклад
Section titled “Приклад”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"}Помилки
Section titled “Помилки”| Статус | Причина |
|---|---|
403 | Ключ не дозволяє вибране налаштування, або неплатоспроможний обліковий запис надіслав glossary_id |
404 | Документ або глосарій не існує, був видалений або належить іншому обліковому запису |
415 | Формат файлу не підлягає перекладу |
422 | Файл порожній, не містить перекладного тексту або параметр недійсний |
429 | Забагато запитів або черга повна; спробуйте ще раз через Retry-After |
Ідемпотентність
Section titled “Ідемпотентність”Idempotency-Key є необов’язковим, але рекомендованим для кожного надсилання. Ключ складається з 1–128 видимих символів ASCII і залишається дійсним невизначено довго для того самого облікового запису:
- Та сама клавіша, той самий корпус: повертається вихідне завдання (включаючи невдале); жодні ресурси не створюються і не оплачуються двічі.
- Та сама клавіша, інший корпус:
409(idempotency_request_conflict). - Оригінальне завдання було видалено:
410(idempotency_job_gone).
Використовуйте новий UUID для кожного нового надсилання та повторно використовуйте оригінальний ключ лише при повторній спробі надіслати саме це надсилання.