Tạo một công việc dịch thuật
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonYêu cầu
Phần tiêu đề “Yêu cầu”| Trường | Loại | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
document_id | chuỗi | ✅ | — | ID của một tài liệu đã được xác nhận |
target_lang | chuỗi | ✅ | — | Mã ngôn ngữ đích |
source_lang | chuỗi | — | Tự động phát hiện | Mã ngôn ngữ nguồn |
engine | chuỗi | — | xr-397b | ID cài đặt dịch thuật, xem cài đặt dịch thuật |
output_mode | chuỗi | — | bilingual | single hoặc bilingual |
glossary_id | chuỗi | — | — | Mã từ điển của tài khoản này. Từ điển chỉ áp dụng cho các tài khoản đã thanh toán (ít nhất một lần thanh toán thành công); tài khoản chưa thanh toán nhưng gửi một yêu cầu sẽ nhận được 403 |
include_images | boolean | — | false | Ngoài ra, hãy dịch cả văn bản trong các hình ảnh của tài liệu. |
context_translation | boolean | — | false | Bật tính năng nâng cao ngữ cảnh |
style_preset | chuỗi | — | — | Cài đặt trước kiểu dáng |
Một tác vụ được tạo sẽ vào hàng đợi. Mỗi tài khoản xử lý tối đa 5 tệp cùng lúc; các tác vụ tiếp theo vẫn được tạo và xếp vào hàng đợi tự động, bắt đầu ngay khi các tác vụ trước đó hoàn tất. Khi một tác vụ đang chờ, trường stage_message của nó hiển thị số lượng tác vụ đứng trước.
Trước khi một công việc bắt đầu, số dư được kiểm tra so với ngưỡng: một PDF yêu cầu số dư phải lớn hơn “số trang × 2 tín chỉ”; các định dạng khác dựa trên độ dài của văn bản nguồn, tối thiểu 2 tín chỉ. Nếu số dư không đủ để khởi tạo một tệp, công việc đó kết thúc với status=failed và quota_exceeded=true, không phát sinh phí, và các công việc khác không bị ảnh hưởng. Khi một công việc hoàn tất, mức sử dụng thực tế sẽ được tính phí; nếu chi phí vượt quá số dư, số dư trở nên âm, các tín chỉ đến sau sẽ được dùng để thanh toán nợ trước, và trong thời gian số dư âm, các công việc mới không thể bắt đầu, vì vậy cần nạp thêm tiền. Xem tín chỉ và mức sử dụng .
Ví dụ
Phần tiêu đề “Ví dụ”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"}'Phản hồi 201 (ngôn ngữ của stage_message trên máy chủ là tiếng Trung):
{ "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"}| Trạng thái | Nguyên nhân |
|---|---|
403 | Khóa không cho phép cài đặt đã chọn, hoặc tài khoản chưa thanh toán đã gửi glossary_id |
404 | Tài liệu hoặc bảng chú giải không tồn tại, đã bị xóa hoặc thuộc về tài khoản khác |
415 | Định dạng tệp không thể được dịch |
422 | Tệp trống, không chứa văn bản có thể dịch hoặc có tham số không hợp lệ |
429 | Quá nhiều yêu cầu, hoặc hàng đợi đã đầy; vui lòng thử lại sau Retry-After |
Tính idempotent
Phần tiêu đề “Tính idempotent”Idempotency-Key là tùy chọn nhưng được khuyến nghị cho mọi bản gửi. Khóa là một chuỗi 1–128 ký tự ASCII hiển thị và duy trì hiệu lực vô thời hạn đối với cùng một thông tin xác thực:
- Cùng một khóa, cùng một thân máy: trả về công việc gốc (bao gồm cả công việc thất bại); không có gì bị tạo ra hoặc tính phí hai lần.
- Cùng chung khóa, khác thân:
409(idempotency_request_conflict). - Công việc gốc đã bị xóa:
410(idempotency_job_gone).
Sử dụng một UUID mới cho mỗi lần gửi mới, và chỉ tái sử dụng khóa gốc khi thử lại cùng một lần gửi đó.