Buat Gambar - TokenLab

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, partial_images, dan user. Jika size atau quality tidak dikirim, TokenLab memakai auto; nilai size kustom harus mengikuti kontrak fleksibel WIDTHxHEIGHT yang dijelaskan di bawah. Catatan kompatibilitas: jika permintaan gpt-image-2 mengirim input_fidelity, TokenLab menghapus kolom itu sebelum meneruskan karena GPT Image 2 sudah otomatis memproses input gambar dengan fidelitas tinggi.

Catatan perilaku model

Google Gemini tidak memakai kontrak selector yang sama:

gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-2, dan nano-banana-pro mendukung aspect_ratio plus resolution (1k, 2k, 4k) untuk text-to-image.
gemini-2.5-flash-image, nano-banana, dan nano-banana-edit mendukung aspect_ratio tetapi tidak menyediakan pemilihan resolution publik.
gemini-2.0-flash-preview-image-generation didokumentasikan di sini sebagai text-to-image yang hanya prompt.
Untuk request gambar referensi nano-banana, nano-banana-2, dan nano-banana-pro, gunakan 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 image-to-image Nano Banana, jangan kirim resolution. nano-banana-2 dan nano-banana-pro hanya mengekspos resolution untuk text-to-image, sedangkan nano-banana tidak mengeksposnya.
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 dan dirutekan upstream ke grok-imagine-image-quality.

Body Request

Timeout permintaan sinkron: beberapa penyedia gambar yang dirutekan 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.

model

string

default:"dall-e-3"

Model yang digunakan (misalnya gpt-image-2, dall-e-3, flux-pro, midjourney).

prompt

string

wajib

Deskripsi teks untuk gambar yang diinginkan.

image_url

string

URL HTTPS publik gambar referensi untuk image-to-image. Untuk keluarga Nano Banana, set operation ke image-to-image dan jangan kirim resolution kecuali model secara eksplisit mendukungnya untuk operasi itu.

image_urls

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[].

reference_image_urls

string[]

URL gambar referensi tambahan khusus model untuk provider yang membedakan gambar input utama dan referensi.

image

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

size

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 kontrak publik TokenLab untuk gpt-image-2.Untuk keluarga gambar Google Gemini, size diperlakukan sebagai alias kompatibilitas yang dipetakan ke kontrak publik aspect_ratio model dan, bila didukung, resolution. Untuk model tersebut, sebaiknya kirim aspect_ratio secara langsung.

aspect_ratio

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.

resolution

string

Pemilih resolusi output yang bergantung pada model.Didukung pada gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-2, nano-banana-pro, dan keluarga resolusi tinggi serupa. 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.

quality

string

default:"standard"

Kualitas gambar. Model DALL-E memakai standard atau hd; model GPT Image seperti gpt-image-2 memakai auto, low, medium, atau high.

response_format

string

default:"url"

Format respons: url atau b64_json. Default-nya url.Untuk rute gpt-image-2 Azure Official atau Azure-compatible, TokenLab tidak meneruskan response_format ke upstream. Gateway selalu menerima data gambar upstream sebagai b64_json; untuk request url, setiap gambar diunggah ke CDN lalu data[].url dikembalikan. Jika storage CDN tidak tersedia atau upload gagal, request gagal alih-alih fallback ke Base64. Untuk b64_json, Base64 mentah dikembalikan.

async

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.

style

string

default:"vivid"

Style untuk DALL-E 3: vivid atau natural.

user

string

Identifier unik untuk end-user.

Respons

Respons Sinkron

created

integer

Unix timestamp saat pembuatan.

data

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): Prompt yang dipakai (DALL-E 3)

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.

created

integer

Timestamp Unix saat dibuat.

task_id

string

Pengenal tugas unik untuk polling.

status

string

Status awal: pending.

poll_url

string

URL relatif untuk polling hasil, misalnya /v1/tasks/{id}.

data

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.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}

Model Tersedia

Model	Tipe	Fitur
`dall-e-3`	Biasanya inline	Kualitas terbaik, peningkatan prompt
`dall-e-2`	Biasanya inline	Lebih cepat, lebih murah
`flux-pro`	Sering berbasis task	Fotorealistik, kualitas tinggi
`flux-schnell`	Biasanya inline	Sangat cepat
`midjourney`	Sering berbasis task	Gaya artistik
`ideogram-v3`	Sering berbasis task	Rendering teks terbaik
`stable-diffusion-3`	Biasanya inline	Open source, dapat dikustomisasi

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":

Documentation Index

​Ringkasan

​Catatan perilaku model

​Body Request

​Respons

​Respons Sinkron

​Respons Task Async

​Model Tersedia

​Menangani Respons Berbasis Task

Ringkasan

Catatan perilaku model

Body Request

Respons

Respons Sinkron

Respons Task Async

Model Tersedia

Menangani Respons Berbasis Task