Lewati ke isi dokumentasi
Media job (asinkron)

Media job (asinkron)

Kirim pekerjaan media, poll statusnya, lalu ambil hasilnya dari domain kami.

Referensi API9 bagianAPI v1
Di halaman ini9 bagian

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:

FieldTipeWajibArtinya
modelstringYaId model dari katalog.
nintegerTidakJumlah 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.

FieldTipeWajibArtinya
promptstringWajibDeskripsi adegan videonya. Ini satu-satunya field yang dipakai setiap model video.
image_urlstringi2v sajaGambar sumber, sebagai URL atau data: URI. Model image-to-video menolak kalau field ini tidak ada.
input_imagesarrayi2v sajaBentuk sumber lain yang diterima model i2v: beberapa gambar sekaligus.
text to video
# 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
# 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 key
shell
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": "Perahu kertas biru kecil di air tenang, cahaya pagi",
    "n": 1
  }'
json
{
  "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 key
shell
curl https://api.menvorainterasia.com/v1/jobs/<id-job> \
  -H "Authorization: Bearer sk-menv-..."

Status yang mungkin kamu lihat:

StatusArtinyaSelesai?Uang
queuedMenunggu giliran.BelumDitahan
in_progressSedang dikerjakan.BelumDitahan
succeededBerhasil, hasil tersedia.YaDitagih
failedGagal di sisi model.YaDikembalikan
expiredTidak ada hasil dalam batas waktu.YaDikembalikan
canceledDibatalkan.YaDikembalikan
json
{
  "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
shell
# 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.jpg

Job 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.

TahapSaldoYang terjadiCatatan
SubmitDitahanHarga jual ditahan, ditambah buffer 25% sebagai pengaman. Angkanya terlihat di halaman harga model.Job belum jalan; ini bukan tagihan.
SelesaiDitagihDitagih sebesar harga terbit — bukan buffer. Sisanya kembali otomatis.Angka akhir ada di charged_micro.
Gagal / kedaluwarsaKembaliSeluruh 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#

HalKeadaanYang bisa kamu lakukanKenapa
Membatalkan jobBelum tersediaTinggalkan jobnya; ia kedaluwarsa sendiri dan dananya kembali.Membatalkan setelah model mulai bekerja tetap menagih, jadi semantiknya belum kami buka.
Webhook saat job selesaiBelum tersediaPoll GET /v1/jobs/{id} secara berkala.Kami sudah menyelesaikan job di latar belakang; webhook hanya mempercepat pemberitahuan.
Lebih dari 4 unit per jobDitolakJalankan beberapa job terpisah.Batas ini menjaga satu job tidak menahan saldo terlalu besar.
Lebih dari 1 video per jobDitolakJalankan beberapa job terpisah.Model video tidak punya field jumlah, jadi unit tambahan tidak bisa diminta.

Kalau ada yang tidak berjalan#

GejalaPenyebabSolusi
surface_not_servedModel job dikirim ke rute sinkron (atau sebaliknya).Periksa is_job di katalog, lalu pakai /jobs untuk model job.
Hasil bukan yang dimintaField tidak dikenal diabaikan model, jadi default yang dipakai.Kirim hanya field dari job_parameters model itu.
conflict saat ambil hasilJob belum selesai atau belum dilunasi.Poll statusnya sampai succeeded, lalu ambil hasilnya.
Job lama berubah menjadi expiredTidak ada hasil dalam batas waktu; dananya sudah kembali.Kirim ulang pekerjaannya.
insufficient_balanceSaldo tidak cukup untuk menahan harga job.Top up saldo, lalu kirim ulang.