Gambar

Buat Gambar

Membuat gambar berdasarkan prompt

POST
/v1/images/generations

Gambaran Umum

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

Setiap model menerima operasi dan field-nya masing-masing. GET /v1/models/{model} (Get Model) menyediakan endpoint untuk setiap operasi dalam tokenlab.request_format_summary.request_endpoint_by_operation, serta field, nilai, dan batasan yang diterima untuk setiap operasi dalam tokenlab.request_format_details.operation_constraints. Field yang tidak tercantum pada model dapat mengembalikan 400 unsupported_parameter. Operasi yang dikirim ke endpoint yang salah akan mengembalikan 400 unsupported_endpoint.

Tugas dan hasil gambar:

  • Model yang mencantumkan async di antara parameter yang didukung dapat membuat tugas terlebih dahulu: kirim async: true, lalu lakukan polling GET /v1/tasks/{id}.
  • Tautan gambar disimpan selama 30 hari; lihat Retensi data.
  • Kirim header Idempotency-Key untuk mencoba kembali permintaan pembuatan secara aman setelah waktu habis; lihat Mencoba kembali secara aman dengan kunci idempotensi.

gpt-image-2 adalah model GPT Image dengan harga berbasis token. TokenLab mengikuti rincian penggunaan resmi OpenAI untuk token input teks, input gambar, cached input yang dilaporkan, dan output gambar; model ini tidak ditagih sebagai model bertarif 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. Kosongkan size atau quality untuk membiarkan TokenLab menggunakan auto; nilai size kustom harus menggunakan format WIDTHxHEIGHT fleksibel yang didokumentasikan di bawah ini.

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

Output SVG dan GIF

gpt-image-2.6-flare dan gpt-image-2.6-sunburst dapat mengembalikan SVG atau GIF animasi alih-alih gambar raster. Model lain akan menolak format ini.

  • SVG: kirim output_format: "svg" dan svg: {"model": "..."}. Model gambar pertama-tama menggambar gambar referensi, kemudian model penulis menulis SVG dari gambar tersebut. svg.model wajib diisi; daftar detail model mencantumkan nilai yang diterima di bawah parameter_options (svg.model). Anda juga dapat mengirim svg.reasoning.effort. SVG hanya berfungsi pada endpoint ini, dengan n: 1, dan tanpa partial_images atau output_compression.
  • GIF: kirim output_format: "gif". frame_count (2 hingga 16, default 9) mengatur jumlah bingkai, dan frame_duration_ms (20 hingga 2000, default 200) mengatur durasi setiap bingkai. size adalah ukuran satu bingkai. GIF tidak menerima partial_images atau output_compression.

Hasilnya ada di data[].b64_json atau data[].url, sama seperti gambar lainnya. Dekode SVG sebagai teks XML UTF-8 dan simpan sebagai .svg; simpan GIF sebagai .gif.

Penagihan: token gambar ditagih berdasarkan harga token model, dan bingkai GIF adalah token output gambar. Permintaan SVG juga menagih token model penulis, yang dilaporkan respons dalam svg_usage, sesuai harga pembuatan SVG yang ditampilkan pada halaman model.

Catatan perilaku model

Model-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 publik text-to-image, image-to-image, dan image-edit mereka.
  • nano-banana-2 mendukung aspect_ratio dan resolution (1k, 2k, 4k) baik untuk pembuatan text-to-image maupun 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 disediakan sebagai JSON image_url / image_urls, atau sebagai berkas multipart image. images[] dan file_id tidak diterima di /v1/images/generations; buat 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 dan grok-imagine-image-2.0) mendukung aspect_ratio ditambah resolution (1k, 2k). Text-to-image menggunakan endpoint ini. Permintaan image-to-image dan image-edit mereka menggunakan /v1/images/edits.

hy-image-v3.5-preview membuat satu gambar 1024x1024 per permintaan dari teks pada endpoint ini dan hanya mendukung response_format: "url". Model ini mengedit gambar referensi di /v1/images/edits.

Body Permintaan

Batas waktu permintaan sinkron: Beberapa permintaan gambar mengembalikan gambar akhir secara langsung (inline) dan menunggu hingga proses pembuatan selesai. Permintaan beresolusi tinggi atau berkualitas tinggi dapat memakan waktu mendekati satu menit atau lebih lama, jadi atur batas waktu (timeout) klien HTTP Anda ke setidaknya 120s. Jika respons pembuatan menyertakan status: "pending", task_id, atau poll_url, lakukan polling GET /v1/tasks/{task_id} sebagai gantinya.

modelstringwajib

Model yang akan digunakan (misalnya, gpt-image-2, flux-pro-1.1, atau nano-banana-pro). Kueri GET /v1/models?recommended_for=image untuk daftar rekomendasi saat ini.

promptstringwajib

Deskripsi teks dari gambar yang diinginkan, hingga 32.000 karakter. Wajib diisi untuk setiap model yang detailnya mencantumkan prompt.

operationstring

text-to-image, image-to-image, atau image-edit. Jika dihilangkan, nilainya adalah image-to-image jika permintaan memiliki gambar referensi, selain itu text-to-image. Atur ke image-edit untuk model yang operasi pengeditannya berada di endpoint ini, seperti nano-banana-pro. text-to-image dengan gambar referensi akan mengembalikan 400 invalid_parameter.

image_urlstring

URL gambar publik untuk pembuatan image-to-image. Untuk permintaan gambar referensi Nano Banana, atur operation ke image-to-image; nano-banana-pro dapat menyertakan resolution.

image_urlsstring[]

URL gambar referensi publik, hingga 16. Gunakan ini untuk satu atau beberapa gambar referensi dalam permintaan JSON. file_id dan images[] tidak didukung di endpoint ini.

reference_image_urlsstring[]

URL gambar referensi tambahan, hingga 16, untuk model yang membedakan input utama dari referensi.

imagefile

Berkas gambar referensi multipart untuk pembuatan image-to-image. Gunakan ini jika gambar sumber bersifat privat atau dilindungi header. Ini berbeda dari file_id /v1/files, yang tidak diterima di endpoint ini.

nintegerbawaan: 1

Jumlah gambar yang akan dibuat (1-10, tergantung model).

sizestring

Ukuran gambar. Gunakan ini untuk keluarga gambar bergaya OpenAI dan model lain yang menerima ukuran piksel persis.

Untuk gpt-image-2, size menerima auto atau WIDTHxHEIGHT. Kedua dimensi kustom harus merupakan kelipatan 16, sisi terpanjang maksimal 3840px, rasio panjang/pendek maksimal 3:1, dan total piksel harus antara 655,360 dan 8,294,400. aspect_ratio dan resolution bukan bagian dari detail model TokenLab saat ini untuk gpt-image-2.

Untuk model gambar Google dengan tingkatan resolusi (gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image, nano-banana-2, nano-banana-2.1, dan nano-banana-pro), size menerima ukuran output dari tabel ukuran model, seperti 1376x768 (16:9 pada 1K), atau tingkatan resolusi: 1K, 2K, atau 4K. TokenLab mengirimkan tingkatan sebagai resolution, sehingga permintaan dan harganya sama seperti menggunakan resolution. Tingkatan yang tidak didukung model (misalnya 2K pada gemini-3.1-flash-lite-image), atau tingkatan yang berbeda dari resolution, akan mengembalikan 400 dengan kode invalid_image_size_contract dan allowed_resolutions milik model. Untuk model-model ini, format yang direkomendasikan adalah aspect_ratio dengan resolution.

aspect_ratiostring

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.

resolutionstring

Resolusi output yang bergantung pada model. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1, dan nano-banana-pro mendukung 1k, 2k, dan 4k; model gambar Grok Imagine mendukung 1k dan 2k. Kosongkan field ini kecuali model dan operasi yang dipilih secara eksplisit mendukungnya.

qualitystring

Kualitas gambar. Model GPT Image seperti gpt-image-2 menggunakan auto, low, medium, atau high. Model lain mungkin menggunakan nilai yang berbeda; periksa detail model sebelum mengirim nilai non-default.

output_formatstring

Format file gambar: png, jpeg, atau webp. gpt-image-2.6-flare dan gpt-image-2.6-sunburst juga menerima svg dan gif; lihat output SVG dan GIF.

svgobject

Pengaturan SVG, hanya dengan output_format: "svg". model (wajib) memilih model penulis yang membuat SVG tersebut. reasoning.effort secara opsional mengatur tingkat penalaran (reasoning effort).

frame_countintegerbawaan: 9

Jumlah frame GIF, dari 2 hingga 16. Hanya dengan output_format: "gif".

frame_duration_msintegerbawaan: 200

Durasi setiap frame GIF dalam milidetik, dari 20 hingga 2000. Hanya dengan output_format: "gif".

response_formatstring

Cara gambar dikembalikan: url atau b64_json.

  • Dikosongkan: ketika model mengembalikan byte gambar, setiap gambar berada dalam data[].b64_json, dan juga dalam data[].url ketika TokenLab menyimpannya. Ketika model mengembalikan tautan, setiap gambar berada dalam data[].url.
  • url: setiap gambar hanya ada di data[].url.
  • b64_json: setiap gambar hanya ada di data[].b64_json sebagai data Base64.

Tautan adalah URL hasil media TokenLab. Tautan tetap valid selama 30 hari. Lihat Retensi data.

asyncbooleanbawaan: false

Atur ke true untuk membuat tugas terlebih dahulu. Hanya model yang mencantumkan async di antara parameter yang didukungnya yang dapat menerimanya, contohnya gpt-image-2, flux-pro-1.1, nano-banana-pro, dan seedream-5.0-lite; untuk model lainnya, permintaan akan mengembalikan 400 unsupported_async_mode. Tugas gambar async yang telah selesai akan mengembalikan URL terlepas dari response_format yang diminta; gunakan permintaan sinkron saat Anda memerlukan b64_json.

stylestring

Pemilih gaya opsional. Hanya kirim ini jika model yang dipilih mendokumentasikannya secara eksplisit; kosongkan untuk gpt-image-2 kecuali metadata model menyatakan sebaliknya.

userstring

Pengenal unik untuk pengguna akhir.

Beberapa model juga menerima field seperti negative_prompt, seed, width, height, steps, guidance_scale, atau mask_url. Kirim parameter tersebut hanya jika detail model mencantumkannya. stream: true tidak didukung dan mengembalikan 400 unsupported_parameter.

Respons

Respons Inline

createdinteger

Timestamp Unix saat pembuatan.

dataarray

Array gambar yang dihasilkan.

Setiap objek berisi:

  • url (string): URL hasil media TokenLab untuk gambar tersebut, valid selama 30 hari. Tidak ada jika response_format adalah b64_json. Ketika response_format dikosongkan, field ini tidak ada jika TokenLab tidak dapat menyimpan gambar.
  • b64_json (string): Data gambar Base64. Ada ketika response_format adalah b64_json, atau ketika dikosongkan dan model mengembalikan byte gambar.
  • revised_prompt (string): Revisi prompt opsional, jika model yang dipilih mengembalikannya
usageobject

Jumlah token (input_tokens, output_tokens, total_tokens, dan detailnya) untuk model dengan harga berbasis token seperti gpt-image-2, jika tersedia.

svg_usageobject

Jumlah token dari model pembuat SVG (model, input_tokens, output_tokens, reasoning_tokens, total_tokens). Hanya ada untuk output SVG. Token ini tidak termasuk dalam usage dan ditagihkan dengan harga pembuatan SVG.

Respons Tugas Asinkron

Atur async: true pada model yang mendukungnya untuk membuat tugas alih-alih menunggu gambar akhir dalam permintaan pembuatan. Respons mencakup 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 dapat menahan perkiraan jumlah biaya saat tugas dibuat. Tugas yang selesai akan ditagih berdasarkan penggunaan aktual, dan tugas yang gagal atau kehabisan waktu akan dilepaskan atau dikembalikan dananya.

createdinteger

Timestamp Unix saat pembuatan.

task_idstring

Pengenal tugas unik untuk polling.

statusstring

Status awal: pending.

poll_urlstring

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

dataarray

Kosong saat tugas berstatus pending. Tugas gambar yang selesai mengembalikan URL gambar yang dihasilkan di data[].url.

Saat Anda menerima status: "pending", panggil GET /v1/tasks/{task_id} untuk mengambil hasilnya.

Permintaan

cURL
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"
  }'
Python
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)
JavaScript
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
<?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'];

Contoh keluarga gambar hanya-rasio: untuk nano-banana, kirim aspect_ratio tetapi abaikan resolution:

{
  "model": "nano-banana",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

Contoh gambar referensi Nano Banana Pro: kirim permintaan ke /v1/images/generations, bukan /v1/images/edits. resolution bersifat opsional dan dapat diatur ke 1k, 2k, atau 4k:

{
  "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"
}

Contoh unggahan multipart langsung untuk gambar sumber privat atau lokal. Jangan meneruskan file_id ke /v1/images/generations:

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"

Respons

{
  "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..."
    }
  ]
}

Error

Error permintaan mengembalikan 400 (413 untuk unggahan yang melebihi batas ukuran) dengan error.code. Kode umum untuk permintaan gambar:

KodePenyebab
unsupported_parameterModel tidak mencantumkan field tersebut, atau stream bernilai true
unsupported_operationModel tidak memiliki operation tersebut
unsupported_endpointOperasi untuk model ini berada di endpoint lain, seperti /v1/images/edits
unsupported_async_modeModel tidak mendukung async: true
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_itemsNilai berada di luar yang diterima model. Error menyebutkan nilai-nilai yang diterima
invalid_image_size_contractsize atau tingkatan yang tidak didukung model, atau yang berkonflik dengan resolution
prompt_too_longPrompt lebih panjang dari yang diterima model
request_too_large, file_too_largeUnggahan melebihi batas ukuran (50 MiB per berkas, 200 MiB untuk semua input)

Untuk saldo (402), batas laju (429), dan aturan coba lagi, lihat Penanganan error.

Pilih Model

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

Jangan melakukan hard-code pada model sebagai selalu sinkron atau selalu asinkron. Permintaan tanpa async: true masih dapat mengembalikan status: "pending"; kapan pun respons pembuatan memuat status: "pending" atau status: "processing", lakukan polling GET /v1/tasks/{task_id} hingga selesai.

Menangani Respons Berbasis Tugas

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

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # Create image request
    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()

    # Check if task-based
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        print(f"Image task started: {task_id}")

        # Poll for result
        deadline = time.time() + 600
        while time.time() < deadline:
            status_resp = requests.get(
                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)
        raise TimeoutError(f"Image task {task_id} did not finish in time")
    else:
        # Inline response
        return data["data"][0]["url"]

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

Contoh Hy Image 3.5 Preview. Model ini hanya menerima size 1024x1024 dan n bernilai 1:

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

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.

Nilai yang tersedia

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Kunci opsional yang membuat permintaan gambar aman untuk dicoba ulang jika permintaan tersebut membuat tugas. Kirim nilai unik baru, seperti UUID, untuk setiap permintaan. Percobaan ulang dengan kunci dan body yang sama kemudian akan mengembalikan tugas tersebut dan tidak akan membuat, mengirim, atau mengenakan biaya untuk tugas kedua. Untuk permintaan yang mengembalikan gambar secara langsung, percobaan ulang dengan kunci yang sama dapat mengembalikan status tugas alih-alih gambar, atau 409 dengan idempotent_response_not_replayable. Body yang berbeda dengan kunci yang sudah diterima akan ditolak; kode status dan kode error untuk kasus tersebut tidak dijamin. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.

Panjang1 <= length <= 255

Body permintaan

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json