API v1Updated 2026-10-15

Gambar

Buat dan edit gambar dengan POST /v1/images/generations dan POST /v1/images/edits. Hasil dikembalikan inline sebagai base64 dan tidak pernah disimpan.

Endpoint Images menerima bentuk request Images API yang umum dan mengembalikan gambar secara inline sebagai b64_json. zrouter tidak meng-host URL gambar dan tidak menyimpan riwayat di server: prompt, gambar sumber, dan hasil hanya ada selama request berlangsung.

Membuat gambar#

POST /v1/images/generations

curl https://api.zrouter.dev/v1/images/generations \
  -H "Authorization: Bearer $ZROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-image-2","prompt":"Mercusuar saat senja, cat air","size":"1024x1024","output_format":"png"}' \
  | jq -r '.data[0].b64_json' | base64 --decode > image.png

Mengedit gambar#

Edit hanya berjalan pada model yang capabilities katalognya memuat edit. Model gambar yang tersedia saat ini baru mendukung generate; memanggil /v1/images/edits dengan model tersebut menghasilkan 400 unsupported_endpoint.

POST /v1/images/edits

curl https://api.zrouter.dev/v1/images/edits \
  -H "Authorization: Bearer $ZROUTER_API_KEY" \
  -F model=gpt-image-2 \
  -F prompt="Ubah langit jadi oranye" \
  -F [email protected] \
  | jq -r '.data[0].b64_json' | base64 --decode > edited.png

Parameter#

Field	Nilai	Catatan
`model`	id model gambar	Wajib.
`prompt`	1–32.000 karakter	Wajib.
`n`	`1`	Satu gambar per request.
`size`	`auto` atau `WxH`	Tiap sisi ≤ 4096 px, total ≤ 16.777.216 px.
`quality`	`auto`, `low`, `medium`, `high`	Opsional.
`output_format`	`png`, `jpeg`, `webp`	Opsional, default `png`.
`output_compression`	0–100	Hanya jpeg/webp.
`background`	`auto`, `opaque`, `transparent`	Opsional.
`image`	File PNG, JPEG atau WebP	Hanya edit. Tepat satu file, ≤ 10 MiB. URL remote ditolak.

response_format=url, stream, partial_images dan mask tidak didukung dan menghasilkan 400 unsupported_parameter. Field yang tidak dikenal ditolak, tidak diteruskan.

Batas#

Satu request gambar aktif per akun; request kedua yang bersamaan menghasilkan 429 image_concurrency_limit.
Request timeout setelah 120 detik (408 request_timeout).
Gambar hasil lebih dari 20 MiB ditahan (502).
Kirim header Idempotency-Key agar retry aman: memakai ulang key tidak pernah memicu generasi atau tagihan kedua, dan menghasilkan 409 idempotency_key_reused karena hasil tidak disimpan.

Penagihan#

Request gambar ditagih dari pemakaian token yang dilaporkan provider (usage.input_tokens / usage.output_tokens) dengan tarif per juta yang tercantum untuk model tersebut, memakai saldo Token Plan dulu lalu PAYG — sama seperti request teks. Header respons x-zrouter-billing bernilai settled saat tagihan tercatat. Jika provider tidak melaporkan pemakaian, gambar tetap dikirim, request tidak ditagih, dan masuk antrean peninjauan (x-zrouter-billing: unmetered).

Error khusus gambar#

Status	Kode	Arti
400	`content_policy_violation`	Provider menolak prompt atau gambar. Tidak ditagih.
400	`unsupported_parameter`	Ada field di luar set yang didukung.
400	`unsupported_endpoint`	Model tidak mendukung operasi gambar ini (misalnya edit).
402	`insufficient_balance`	Tidak ada saldo Token Plan atau PAYG untuk model ini.
408	`request_timeout`	Gambar tidak siap dalam 120 detik.
409	`idempotency_key_reused`	Idempotency-Key ini sudah dipakai.
413	`image_too_large`	Gambar sumber melebihi batas ukuran atau piksel.
429	`image_concurrency_limit`	Masih ada request gambar lain dari akun Anda yang berjalan.