Ringkasan
Untuk coding agents, cari shortlist gambar yang direkomendasikan saat ini terlebih dahulu denganGET /v1/models?recommended_for=image, lalu kirim model yang dipilih secara eksplisit ke endpoint ini.
gpt-image-2 adalah model GPT Image dengan penagihan berbasis token. TokenLab mengikuti rincian usage resmi OpenAI untuk menghitung token input teks, input gambar, input cache jika dilaporkan, dan output gambar; model ini tidak ditagih sebagai harga tetap per gambar.
Untuk pembuatan gambar dengan gpt-image-2, parameter publik yang didukung adalah prompt, n, size, quality, response_format, async, background, output_format, output_compression atau compression, moderation, dan user. background menerima auto atau opaque; transparent tidak didukung. Jika size atau quality tidak dikirim, TokenLab memakai auto; nilai size kustom harus mengikuti kontrak fleksibel WIDTHxHEIGHT yang dijelaskan di bawah.
input_fidelity bukan bagian dari kontrak publik TokenLab saat ini untuk gpt-image-2; hilangkan field ini atau request akan mengembalikan 400 unsupported_parameter.
Catatan perilaku model
Google Gemini tidak memakai kontrak selector yang sama:gemini-3.1-flash-image,gemini-3-pro-image, dannano-banana-promendukungaspect_ratioplusresolution(1k,2k,4k) untuk operasi publik text-to-image dan image-edit/image-to-image.nano-banana-2mendukungaspect_ratioplusresolution(1k,2k,4k) hanya untuk text-to-image dalam kontrak TokenLab saat ini.gemini-2.5-flash-image,nano-banana, dannano-banana-editmendukungaspect_ratiotetapi tidak menyediakan pemilihanresolutionpublik.- Untuk request Nano Banana dengan gambar referensi, gunakan
nano-banana-editataunano-banana-propada endpoint ini (/v1/images/generations) denganoperation: "image-to-image"danimage_urls. Jangan kirim request gambar referensi Nano Banana ke/v1/images/edits. - Untuk request Nano Banana image-to-image,
nano-banana-prodapat menyertakanresolution(1k,2k,4k);nano-banana-editharus menghilangkannya.nano-bananadannano-banana-2adalah model text-to-image dalam detail model saat ini. - Gambar referensi pada endpoint ini dapat dikirim sebagai JSON
image_url/image_urls, atau sebagai file multipartimage./v1/images/generationstidak menerimaimages[]ataufile_id; referensi/v1/fileshanya untuk model/v1/images/editsyang mendokumentasikanimages[].file_id.
aspect_ratio dan hanya kirim resolution jika model secara eksplisit mendukungnya.
Model gambar xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality, dan legacy grok-imagine-image-pro) mendukung aspect_ratio plus resolution (1k, 2k). grok-imagine-image-pro dipertahankan sebagai ID kompatibilitas untuk grok-imagine-image-quality.
Body Request
Timeout permintaan sinkron: beberapa request gambar mengembalikan gambar final secara inline dan menunggu proses generasi selesai. Permintaan resolusi tinggi atau kualitas tinggi dapat memakan waktu hampir satu menit atau lebih, jadi atur timeout HTTP client Anda minimal120s. Jika respons pembuatan berisi status: "pending", task_id, atau poll_url, ikuti poll_url yang dikembalikan.
string
wajib
Model yang digunakan (misalnya
gpt-image-2, flux-pro, qwen-image-plus, atau nano-banana-pro). Gunakan GET /v1/models?recommended_for=image untuk daftar rekomendasi terbaru.string
wajib
Deskripsi teks untuk gambar yang diinginkan.
string
URL HTTPS publik gambar referensi untuk image-to-image. Untuk request Nano Banana dengan gambar referensi, set
operation ke image-to-image; nano-banana-pro dapat menyertakan resolution, sedangkan nano-banana-edit sebaiknya menghilangkannya.string[]
URL HTTPS publik untuk gambar referensi. Gunakan untuk satu atau beberapa gambar referensi dalam request JSON. Endpoint ini tidak mendukung
file_id dan images[].string[]
URL gambar referensi tambahan khusus model untuk provider yang membedakan gambar input utama dan referensi.
file
File gambar referensi multipart untuk image-to-image. Gunakan saat gambar sumber bersifat privat atau membutuhkan header. Ini berbeda dari
file_id /v1/files; endpoint ini tidak menerima file_id.integer
default:"1"
Jumlah gambar yang dibuat (1-10, tergantung model).
string
default:"1024x1024"
Ukuran gambar. Gunakan untuk keluarga gambar bergaya OpenAI dan model lain yang menerima ukuran piksel presisi.Untuk
gpt-image-2, size menerima auto atau WIDTHxHEIGHT. Dimensi kustom harus berupa kelipatan 16 pada kedua sisi, sisi terpanjang maksimal 3840px, rasio sisi panjang/sisi pendek maksimal 3:1, dan total piksel harus berada antara 655,360 dan 8,294,400. aspect_ratio dan resolution saat ini bukan bagian dari detail model TokenLab untuk gpt-image-2.Untuk keluarga gambar Google Gemini, size diperlakukan sebagai alias kompatibilitas yang dipetakan ke detail model aspect_ratio model dan, bila didukung, resolution. Untuk model tersebut, sebaiknya kirim aspect_ratio secara langsung.string
Pemilih rasio aspek yang bergantung pada model.Nilai umum untuk keluarga gambar Google mencakup
1:1, 16:9, 9:16, 3:2, dan 2:3.string
Pemilih resolusi output yang bergantung pada model.Didukung pada
gemini-3.1-flash-image dan gemini-3-pro-image untuk text-to-image dan image-edit, pada nano-banana-pro untuk text-to-image dan image-to-image, serta pada nano-banana-2 hanya untuk text-to-image. Nilai tipikal adalah 1k, 2k, dan 4k. Jangan kirim parameter ini ke keluarga gambar Gemini yang hanya menerima rasio kecuali modelnya mendokumentasikannya secara eksplisit. Untuk model gambar xAI Grok Imagine, gunakan 1k atau 2k.string
default:"standard"
Kualitas gambar. Model GPT Image seperti
gpt-image-2 memakai auto, low, medium, atau high. Keluarga gambar lain dapat memakai nilai khusus provider; periksa metadata model sebelum mengirim nilai non-default.string
default:"url"
Format respons:
url atau b64_json. Default-nya url.Untuk gpt-image-2 melalui Azure Official atau layanan yang kompatibel dengan Azure, TokenLab menerima hasil gambar sebagai b64_json. Untuk request url, TokenLab mengunggah setiap gambar ke CDN lalu mengembalikan data[].url. Jika CDN tidak tersedia atau upload gagal, request gagal dan tidak diubah menjadi respons Base64. Untuk b64_json, Base64 mentah dikembalikan.boolean
default:"false"
Setel ke
true dengan gpt-image-2 atau model gambar resmi FLUX/BFL untuk membuat task terlebih dahulu. Task gambar async yang selesai mengembalikan URL apa pun response_format yang diminta; gunakan request sinkron jika membutuhkan b64_json.string
Selector style opsional. Kirim hanya jika model yang dipilih mendokumentasikannya secara eksplisit; hilangkan untuk
gpt-image-2 kecuali metadata model menyatakan sebaliknya.string
Identifier unik untuk end-user.
Respons
Respons Sinkron
integer
Unix timestamp saat pembuatan.
array
Array gambar yang dihasilkan.Setiap object berisi:
url(string): URL gambar yang dihasilkanb64_json(string): Gambar terenkripsi Base64 (jika diminta)revised_prompt(string): Revisi prompt opsional jika model yang dipilih mengembalikannya
Respons Task Async
Setelasync: true dengan gpt-image-2 atau model gambar resmi FLUX/BFL untuk membuat task alih-alih menunggu gambar final di request pembuatan. Respons berisi status: "pending", task_id, dan poll_url. Poll /v1/tasks/{task_id} hingga task menjadi completed atau failed.
Task gambar async hanya mengembalikan URL gambar final. Jika membutuhkan data gambar mentah b64_json, gunakan request sinkron.
Saat task dibuat, biaya estimasi dapat dicadangkan. Task yang selesai ditagih berdasarkan penggunaan aktual; task yang gagal atau timeout akan melepas atau mengembalikan cadangan biaya.
integer
Timestamp Unix saat dibuat.
string
Pengenal tugas unik untuk polling.
string
Status awal:
pending.string
URL relatif untuk polling hasil, misalnya
/v1/tasks/{id}.array
Kosong saat tugas masih pending. Tugas gambar yang selesai mengembalikan URL gambar yang dihasilkan di
data[].url.status: "pending", gunakan poll_url atau GET /v1/tasks/{task_id} untuk mengambil hasil.
Model Tersedia
Ini adalah contoh model saat ini, bukan katalog tetap. GunakanGET /v1/models?recommended_for=image atau halaman Models untuk ketersediaan dan harga terbaru.
Jangan hard-code model sebagai selalu sinkron atau selalu asinkron. Jika response create mengembalikan
status: "pending", ikuti poll_url dan polling sampai selesai.
Menangani Respons Berbasis Task
Untuk model gambar, selalu cek apakah respons berisistatus: "pending":