Lewati ke konten

Buat pekerjaan terjemahan

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
BidangTipeDiperlukanDefaultDeskripsi
document_idstring✅—ID dokumen yang telah dikonfirmasi
target_langstring✅—Kode bahasa target
source_langstring—Deteksi otomatisKode bahasa sumber
enginestring—xr-397bID pengaturan terjemahan, lihat pengaturan terjemahan
output_modestring—bilingualsingle atau bilingual
glossary_idstring——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_imagesboolean—falseTerjemahkan juga teks pada gambar dalam dokumen
context_translationboolean—falseAktifkan peningkatan konteks
style_presetstring——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 .

Terminal window
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"
}
StatusPenyebab
403Kunci tidak mengizinkan pengaturan yang dipilih, atau akun yang belum dibayar mengirim glossary_id
404Dokumen atau glosarium tidak ada, telah dihapus, atau milik akun lain
415Format file tidak dapat diterjemahkan
422File tersebut kosong, tidak memiliki teks yang dapat diterjemahkan, atau ada parameter yang tidak valid.
429Terlalu banyak permintaan, atau antrian penuh; coba lagi setelah Retry-After

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.