Media job (asinkron)
Kirim pekerjaan media, poll statusnya, lalu ambil hasilnya dari domain kami.
Di halaman ini9 bagianTutup
Kapan memakai job#
Sebagian model media tidak menjawab dalam satu respons. Model seperti itu disebut model job: kamu mengirim pekerjaannya, menerima sebuah id, lalu menanyakan statusnya sampai selesai. Hasilnya diambil terpisah setelah job dilunasi.
Katalog memberi tahu model mana yang job: field is_job bernilai true. Kalau false, pakai rute sinkron biasa (misalnya /images/generations) — mengirim model sinkron ke /jobs, atau sebaliknya, akan ditolak dengan pesan yang menyebut jenis modelnya.
Parameter mengikuti modelnya#
Body permintaan job diteruskan apa adanya ke model, jadi field yang diterima berbeda antar model. Dua model gambar pun bisa memakai nama field yang berbeda untuk hal yang sama.
Karena itu daftar parameternya ada di model, bukan di halaman ini: job_parameters pada katalog menyebut nama field, tipe, nilai yang diterima, batas angka, dan default-nya. Field verified di dalamnya menyatakan apakah skema model itu sudah kami baca — kalau nilainya unverified, daftarnya kosong dan kamu perlu memeriksa dokumentasi model tersebut sebelum mengirim field tambahan.
Dua field berikut milik kami, bukan milik model, dan selalu boleh dikirim:
| Field | Tipe | Wajib | Artinya |
|---|---|---|---|
model | string | Ya | Id model dari katalog. |
n | integer | Tidak | Jumlah unit yang ingin dibuat (1–4 untuk gambar). Ini juga jumlah yang ditagih, jadi ia diterjemahkan ke field milik model. Untuk job video, satu job menghasilkan satu video — n di atas 1 ditolak. |
Video: dari teks atau dari gambar#
Model video punya dua arah — text-to-video (mulai dari prompt) dan image-to-video (mulai dari gambar sumber) — dan keduanya lewat rute /jobs yang sama. Yang membedakan hanya field yang kamu kirim.
| Field | Tipe | Wajib | Artinya |
|---|---|---|---|
prompt | string | Wajib | Deskripsi adegan videonya. Ini satu-satunya field yang dipakai setiap model video. |
image_url | string | i2v saja | Gambar sumber, sebagai URL atau data: URI. Model image-to-video menolak kalau field ini tidak ada. |
input_images | array | i2v saja | Bentuk sumber lain yang diterima model i2v: beberapa gambar sekaligus. |
# Text-to-video: cukup prompt.
curl https://api.menvorainterasia.com/v1/jobs \
-H "Authorization: Bearer sk-menv-..." \
-H "Content-Type: application/json" \
-d '{
"model": "<id-model-job-dari-katalog>",
"prompt": "Hujan rintik di jendela kafe, lampu kota berkedip pelan"
}'# Image-to-video: kirim gambar sumbernya.
curl https://api.menvorainterasia.com/v1/jobs \
-H "Authorization: Bearer sk-menv-..." \
-H "Content-Type: application/json" \
-d '{
"model": "<id-model-job-dari-katalog>",
"image_url": "data:image/png;base64,...",
"prompt": "Gerakkan kameranya maju perlahan"
}'Field lain yang didukung sebuah model — misalnya durasi, rasio aspek, atau skala pemandu — diteruskan apa adanya dengan nama persis seperti yang dipakai model itu. Tidak ada daftar tetap dari kami untuk surface video; kalau entri katalog modelmu membawa job_parameters, daftar field yang terverifikasi ada di sana.
1. Kirim pekerjaan#
Saldo ditahan saat submit, dan id job dikembalikan seketika.
POST/v1/jobsBearer API keycurl https://api.menvorainterasia.com/v1/jobs \
-H "Authorization: Bearer sk-menv-..." \
-H "Content-Type: application/json" \
-d '{
"model": "<id-model-job-dari-katalog>",
"prompt": "Perahu kertas biru kecil di air tenang, cahaya pagi",
"n": 1
}'{
"object": "job",
"id": "0b8f1c2e-...",
"status": "queued",
"model": "<id-model-job-dari-katalog>",
"created": "2026-11-02T04:10:22.481Z"
}Status awalnya queued. Simpan id-nya: itu satu-satunya cara menanyakan status dan mengambil hasil.
2. Tanyakan statusnya#
Rute ini hanya membaca. Ia tidak pernah memicu biaya tambahan.
GET/v1/jobs/{id}Bearer API keycurl https://api.menvorainterasia.com/v1/jobs/<id-job> \
-H "Authorization: Bearer sk-menv-..."Status yang mungkin kamu lihat:
| Status | Artinya | Selesai? | Uang |
|---|---|---|---|
queued | Menunggu giliran. | Belum | Ditahan |
in_progress | Sedang dikerjakan. | Belum | Ditahan |
succeeded | Berhasil, hasil tersedia. | Ya | Ditagih |
failed | Gagal di sisi model. | Ya | Dikembalikan |
expired | Tidak ada hasil dalam batas waktu. | Ya | Dikembalikan |
canceled | Dibatalkan. | Ya | Dikembalikan |
{
"object": "job",
"id": "0b8f1c2e-...",
"status": "succeeded",
"model": "<id-model-job-dari-katalog>",
"created": "2026-11-02T04:10:22.481Z",
"completed": "2026-11-02T04:11:03.190Z",
"charged_micro": "50000000000",
"artifact": { "url": "/v1/jobs/0b8f1c2e-.../artifact" },
"artifacts": [
{ "index": 0, "url": "/v1/jobs/0b8f1c2e-.../artifact?index=0" }
]
}charged_micro berisi angka yang benar-benar ditagih (dalam mikro-rupiah; 1 rupiah = 100.000.000). Nilainya null selama job belum selesai.
3. Ambil hasilnya#
Hasil diambil dari domain kami, bukan dari link provider — link provider kedaluwarsa dan tidak boleh kamu simpan.
GET/v1/jobs/{id}/artifactBearer API key# Ambil hasilnya dari domain kami — bukan link provider yang kedaluwarsa.
curl https://api.menvorainterasia.com/v1/jobs/<id-job>/artifact \
-H "Authorization: Bearer sk-menv-..." \
--output hasil.jpg
# Job dengan beberapa unit: pilih hasilnya lewat ?index=
curl https://api.menvorainterasia.com/v1/jobs/<id-job>/artifact?index=1 \
-H "Authorization: Bearer sk-menv-..." \
--output hasil-2.jpgJob dengan beberapa unit menghasilkan beberapa hasil. Field artifacts di respons status mendaftar semuanya dengan index-nya; pilih satu lewat ?index=N. Tanpa index, kamu mendapat hasil pertama.
Bagaimana uang bergerak#
Tiga langkah, dan kamu hanya membayar pekerjaan yang benar-benar menghasilkan.
| Tahap | Saldo | Yang terjadi | Catatan |
|---|---|---|---|
| Submit | Ditahan | Harga jual ditahan, ditambah buffer 25% sebagai pengaman. Angkanya terlihat di halaman harga model. | Job belum jalan; ini bukan tagihan. |
| Selesai | Ditagih | Ditagih sebesar harga terbit — bukan buffer. Sisanya kembali otomatis. | Angka akhir ada di charged_micro. |
| Gagal / kedaluwarsa | Kembali | Seluruh dana yang ditahan dikembalikan. | Tidak ada tagihan sama sekali. |
Kalau submit gagal sebelum pekerjaan terkirim ke model, dana yang ditahan langsung dikembalikan di permintaan yang sama.
Batas dan hal yang belum tersedia#
| Hal | Keadaan | Yang bisa kamu lakukan | Kenapa |
|---|---|---|---|
| Membatalkan job | Belum tersedia | Tinggalkan jobnya; ia kedaluwarsa sendiri dan dananya kembali. | Membatalkan setelah model mulai bekerja tetap menagih, jadi semantiknya belum kami buka. |
| Webhook saat job selesai | Belum tersedia | Poll GET /v1/jobs/{id} secara berkala. | Kami sudah menyelesaikan job di latar belakang; webhook hanya mempercepat pemberitahuan. |
| Lebih dari 4 unit per job | Ditolak | Jalankan beberapa job terpisah. | Batas ini menjaga satu job tidak menahan saldo terlalu besar. |
| Lebih dari 1 video per job | Ditolak | Jalankan beberapa job terpisah. | Model video tidak punya field jumlah, jadi unit tambahan tidak bisa diminta. |
Kalau ada yang tidak berjalan#
| Gejala | Penyebab | Solusi |
|---|---|---|
surface_not_served | Model job dikirim ke rute sinkron (atau sebaliknya). | Periksa is_job di katalog, lalu pakai /jobs untuk model job. |
| Hasil bukan yang diminta | Field tidak dikenal diabaikan model, jadi default yang dipakai. | Kirim hanya field dari job_parameters model itu. |
conflict saat ambil hasil | Job belum selesai atau belum dilunasi. | Poll statusnya sampai succeeded, lalu ambil hasilnya. |
| Job lama berubah menjadi expired | Tidak ada hasil dalam batas waktu; dananya sudah kembali. | Kirim ulang pekerjaannya. |
insufficient_balance | Saldo tidak cukup untuk menahan harga job. | Top up saldo, lalu kirim ulang. |