Skip to main content

Ringkasan

Untuk coding agents, cari shortlist gambar yang direkomendasikan saat ini terlebih dahulu dengan GET /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, dan nano-banana-pro mendukung aspect_ratio plus resolution (1k, 2k, 4k) untuk operasi publik text-to-image dan image-edit/image-to-image.
  • nano-banana-2 mendukung aspect_ratio plus resolution (1k, 2k, 4k) hanya untuk text-to-image dalam kontrak TokenLab saat ini.
  • gemini-2.5-flash-image, nano-banana, dan nano-banana-edit mendukung aspect_ratio tetapi tidak menyediakan pemilihan resolution publik.
  • Untuk request Nano Banana dengan gambar referensi, gunakan nano-banana-edit atau nano-banana-pro pada endpoint ini (/v1/images/generations) dengan operation: "image-to-image" dan image_urls. Jangan kirim request gambar referensi Nano Banana ke /v1/images/edits.
  • Untuk request Nano Banana image-to-image, nano-banana-pro dapat menyertakan resolution (1k, 2k, 4k); nano-banana-edit harus menghilangkannya. nano-banana dan nano-banana-2 adalah 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 multipart image. /v1/images/generations tidak menerima images[] atau file_id; referensi /v1/files hanya untuk model /v1/images/edits yang mendokumentasikan images[].file_id.
Untuk keluarga gambar Google, utamakan 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 minimal 120s. 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 dihasilkan
  • b64_json (string): Gambar terenkripsi Base64 (jika diminta)
  • revised_prompt (string): Revisi prompt opsional jika model yang dipilih mengembalikannya

Respons Task Async

Setel async: 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.
Saat Anda menerima 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. Gunakan GET /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 berisi status: "pending":