Buat pekerjaan terjemahan
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonPermintaan
Section titled “Permintaan”| Bidang | Tipe | Diperlukan | Default | Deskripsi |
|---|---|---|---|---|
document_id | string | ✅ | — | ID dokumen yang telah dikonfirmasi |
target_lang | string | ✅ | — | Kode bahasa target |
source_lang | string | — | Deteksi otomatis | Kode bahasa sumber |
engine | string | — | xr-397b | ID pengaturan terjemahan, lihat pengaturan terjemahan |
output_mode | string | — | bilingual | single atau bilingual |
glossary_id | string | — | — | ID glosarium untuk akun ini. Glosarium diperuntukkan bagi akun berbayar (setidaknya telah melakukan satu pembayaran berhasil); akun yang belum dibayar namun mengirimkan satu permintaan akan mendapatkan 403 |
include_images | boolean | — | false | Terjemahkan juga teks pada gambar dalam dokumen |
context_translation | boolean | — | false | Aktifkan peningkatan konteks |
style_preset | string | — | — | Preset gaya |
Pekerjaan yang dibuat masuk ke antrean. Setiap akun memproses hingga 5 file sekaligus; pekerjaan tambahan tetap dibuat dan ditempatkan secara otomatis di antrean, mulai diproses saat pekerjaan sebelumnya selesai. Saat sebuah pekerjaan menunggu, stage_messagenya menunjukkan berapa banyak pekerjaan yang berada di depannya.
Sebelum suatu pekerjaan dimulai, saldo diperiksa terhadap ambang batas: sebuah PDF memerlukan saldo di atas “halaman × 2 kredit”; format lainnya ditentukan berdasarkan panjang teks sumber, minimal 2 kredit. Jika saldo tidak mencukupi untuk memulai sebuah file, pekerjaan tersebut berakhir dengan status=failed dan quota_exceeded=true, tidak ada biaya yang dikenakan, dan pekerjaan lain tidak terpengaruh. Ketika sebuah pekerjaan selesai, penggunaan aktual akan ditagih; jika biaya melebihi saldo, saldo menjadi negatif, kredit yang masuk kemudian akan melunasi utang terlebih dahulu, dan pekerjaan baru tidak dapat dimulai selama saldo negatif, sehingga perlu dilakukan penambahan saldo. Lihat kredit dan penggunaan .
Contoh
Section titled “Contoh”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"}'Respons 201 (bahasa stage_message server dalam bahasa Tionghoa):
{ "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"}Kesalahan
Section titled “Kesalahan”| Status | Penyebab |
|---|---|
403 | Kunci tidak mengizinkan pengaturan yang dipilih, atau akun yang belum dibayar mengirim glossary_id |
404 | Dokumen atau glosarium tidak ada, telah dihapus, atau milik akun lain |
415 | Format file tidak dapat diterjemahkan |
422 | File tersebut kosong, tidak memiliki teks yang dapat diterjemahkan, atau ada parameter yang tidak valid. |
429 | Terlalu banyak permintaan, atau antrian penuh; coba lagi setelah Retry-After |
Idempotensi
Section titled “Idempotensi”Idempotency-Key bersifat opsional tetapi direkomendasikan untuk setiap pengiriman. Kunci berupa 1–128 karakter ASCII yang dapat dilihat dan tetap valid tanpa batas waktu untuk kredensial yang sama:
- Kunci yang sama, badan yang sama: mengembalikan pekerjaan asli (termasuk yang gagal); tidak ada yang dibuat atau dikenakan biaya dua kali.
- Kunci yang sama, badan berbeda:
409(idempotency_request_conflict). - Pekerjaan asli telah dihapus:
410(idempotency_job_gone).
Gunakan UUID baru untuk setiap pengiriman baru, dan gunakan kembali kunci asli hanya saat mencoba ulang pengiriman yang sama.