Create Image

Gambaran UmumCopy Anchor Link

Gunakan GET /v1/models?recommended_for=image untuk mendapatkan model gambar saat ini, kemudian kirim model yang dipilih secara eksplisit.

gpt-image-2 adalah model GPT Image dengan harga berbasis token. TokenLab mengikuti rincian penggunaan resmi OpenAI untuk input teks, input gambar, input yang di-cache, dan token output gambar; model ini tidak ditagih sebagai model dengan harga tetap per gambar.

Untuk pembuatan gambar 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. Hilangkan size atau quality agar TokenLab menggunakan auto; nilai size kustom harus menggunakan kontrak WIDTHxHEIGHT fleksibel yang didokumentasikan di bawah.

input_fidelity bukan bagian dari bidang yang didukung TokenLab saat ini untuk gpt-image-2; hilangkan bidang tersebut atau permintaan akan mengembalikan 400 unsupported_parameter.

Catatan perilaku modelCopy Anchor Link

Model keluarga gambar Google Gemini tidak menggunakan kontrak pemilih yang sama:

• gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2.1, dan nano-banana-pro mendukung aspect_ratio ditambah resolution (1k, 2k, 4k) untuk operasi text-to-image, image-to-image, dan image-edit publik mereka.
• nano-banana-2 mendukung aspect_ratio dan resolution (1k, 2k, 4k) untuk pembuatan text-to-image dan image-to-image.
• gemini-3.1-flash-lite-image dan nano-banana-2-lite mendukung text-to-image, image-to-image, dan image-edit hanya pada resolusi 1k.
• nano-banana mendukung aspect_ratio tetapi tidak mengekspos pemilihan resolution publik.
• Untuk image-to-image dengan gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, atau gemini-3-pro-image, gunakan endpoint ini dengan operation: "image-to-image" dan gambar referensi. Kirim permintaan image-edit untuk model-model ini ke /v1/images/edits.
• Untuk permintaan gambar referensi Nano Banana, gunakan nano-banana-2, nano-banana-2.1, nano-banana-2-lite, atau nano-banana-pro pada endpoint ini (/v1/images/generations) dengan operation: "image-to-image" dan image_urls. Permintaan image-edit untuk nano-banana-2, nano-banana-2.1, nano-banana-2-lite, dan nano-banana-pro juga menggunakan endpoint ini, dengan operation: "image-edit". Jangan kirim permintaan gambar referensi Nano Banana ke /v1/images/edits.
• Gambar referensi pada endpoint ini dapat diberikan sebagai JSON image_url / image_urls, atau sebagai file multipart image. images[] dan file_id tidak diterima pada /v1/images/generations; buat referensi /v1/files hanya untuk model /v1/images/edits yang mendokumentasikan images[].file_id.

Untuk keluarga gambar Google, lebih disarankan menggunakan aspect_ratio dan hanya kirim resolution jika model mendukungnya secara eksplisit.

Model gambar xAI Grok Imagine (grok-imagine-image, grok-imagine-image-2.0, dan versi lama grok-imagine-image-pro) mendukung aspect_ratio ditambah resolution (1k, 2k). grok-imagine-image-pro dipertahankan sebagai ID kompatibilitas untuk grok-imagine-image-2.0.

Isi PermintaanCopy Anchor Link

Timeout permintaan sinkron: Beberapa permintaan gambar mengembalikan gambar akhir secara inline dan menunggu pembuatan selesai. Permintaan resolusi tinggi atau kualitas tinggi dapat memakan waktu hampir satu menit atau lebih, jadi atur timeout klien HTTP Anda setidaknya ke 120s. Jika respons pembuatan menyertakan status: "pending", task_id, atau poll_url, ikuti poll_url yang dikembalikan.

ResponsCopy Anchor Link

Respons InlineCopy Anchor Link

Respons Tugas AsinkronCopy Anchor Link

Atur async: true dengan gpt-image-2 atau model gambar FLUX/BFL resmi untuk membuat tugas alih-alih menunggu gambar akhir dalam permintaan pembuatan. Respons menyertakan status: "pending", task_id, dan poll_url. Lakukan polling /v1/tasks/{task_id} hingga tugas mencapai completed atau failed.

Tugas gambar asinkron hanya mengembalikan URL gambar akhir. Jika Anda memerlukan data gambar b64_json mentah, gunakan permintaan sinkron.

Penagihan mungkin mencadangkan jumlah estimasi saat tugas dibuat. Tugas yang selesai ditagih berdasarkan penggunaan aktual, dan tugas yang gagal atau timeout akan dirilis atau dikembalikan dananya.

Ketika Anda menerima status: "pending", gunakan poll_url atau GET /v1/tasks/{task_id} untuk mengambil hasilnya.

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": "nano-banana",
  "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..."
    }
  ]
}

Memilih ModelCopy Anchor Link

Kueri GET /v1/models?recommended_for=image atau gunakan halaman Model untuk ketersediaan, kemampuan, dan harga saat ini.

Jangan melakukan hard-code model sebagai selalu sinkron atau selalu asinkron. Jika respons pembuatan mengembalikan status: "pending", ikuti poll_url dan lakukan polling hingga selesai.

Menangani Respons Berbasis TugasCopy Anchor Link

Untuk model gambar, selalu periksa apakah respons berisi status: "pending" / status: "processing":

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # Buat permintaan gambar
    response = requests.post(
        "https://api.tokenlab.sh/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt, "async": True},
        timeout=120
    )
    response.raise_for_status()
    data = response.json()

    # Periksa apakah berbasis tugas
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        # Polling untuk hasil
        while True:
            status_resp = requests.get(
                f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"},
                timeout=30
            )
            status_resp.raise_for_status()
            status_data = status_resp.json()

            if status_data["status"] == "completed":
                return status_data["data"][0]["url"]
            elif status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)
    else:
        # Respons inline
        return data["data"][0]["url"]

# Penggunaan
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")

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