Buat Gambar

RingkasanCopy Anchor Link

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 modelCopy Anchor Link

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 dan resolution (1k, 2k, 4k) untuk text-to-image dan image-to-image.
• 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.
• 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 RequestCopy Anchor Link

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.

ResponsCopy Anchor Link

Respons SinkronCopy Anchor Link

Respons Task AsyncCopy Anchor Link

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.

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",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)

print(response.data[0].url)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.generate({
  model: 'gemini-3-pro-image',
  prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
  aspect_ratio: '16:9',
  resolution: '2k'
});

console.log(response.data[0].url);

<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gemini-3-pro-image',
        'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
        'aspect_ratio' => '16:9',
        'resolution' => '2k'
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

{
  "model": "nano-banana-pro",
  "prompt": "Create a clean cinematic character image based on the reference images",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/reference-1.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=nano-banana-pro" \
  -F "prompt=Create a clean cinematic character image based on this reference" \
  -F "operation=image-to-image" \
  -F "image=@reference.png" \
  -F "aspect_ratio=1:1" \
  -F "resolution=2k"

{
  "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 TersediaCopy Anchor Link

Gunakan GET /v1/models?recommended_for=image untuk model gambar, kemampuan, dan harga saat ini.

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 TaskCopy Anchor Link

Untuk model gambar, selalu cek apakah respons berisi status: "pending":

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}