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. 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.
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.Deskripsi teks untuk gambar yang diinginkan.
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.URL HTTPS publik untuk gambar referensi. Gunakan untuk satu atau beberapa gambar referensi dalam request JSON. Endpoint ini tidak mendukung
file_id dan images[].URL gambar referensi tambahan khusus model untuk provider yang membedakan gambar input utama dan referensi.
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.Jumlah gambar yang dibuat (1-10, tergantung model).
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.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.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.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.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.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.Selector style opsional. Kirim hanya jika model yang dipilih mendokumentasikannya secara eksplisit; hilangkan untuk
gpt-image-2 kecuali metadata model menyatakan sebaliknya.Identifier unik untuk end-user.
Respons
Respons Sinkron
Unix timestamp saat pembuatan.
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.
Timestamp Unix saat dibuat.
Pengenal tugas unik untuk polling.
Status awal:
pending.URL relatif untuk polling hasil, misalnya
/v1/tasks/{id}.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.
| Model | Tipe | Fitur |
|---|---|---|
gpt-image-2 | Inline atau berbasis task | Model GPT Image berbasis harga token, ukuran fleksibel |
flux-pro | Sering berbasis task | Fotorealistik, kualitas tinggi |
qwen-image-plus | Sering berbasis task | Rendering teks dan kepatuhan prompt yang kuat |
nano-banana-pro | Sering berbasis task | Workflow gambar referensi dan output resolusi tinggi |
grok-imagine-image | Sering berbasis task | Generasi gambar xAI dengan pilihan rasio aspek dan resolusi |
ideogram-v3 | Sering berbasis task | Rendering teks yang kuat |
status: "pending", ikuti poll_url dan polling sampai selesai.
Menangani Respons Berbasis Task
Untuk model gambar, selalu cek apakah respons berisistatus: "pending":