Gambar
Buat Gambar
Membuat gambar berdasarkan prompt
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
asyncdi antara parameter yang didukung dapat membuat tugas terlebih dahulu: kirimasync: true, lalu lakukan pollingGET /v1/tasks/{id}. - Tautan gambar disimpan selama 30 hari; lihat Retensi data.
- Kirim header
Idempotency-Keyuntuk 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"dansvg: {"model": "..."}. Model gambar pertama-tama menggambar gambar referensi, kemudian model penulis menulis SVG dari gambar tersebut.svg.modelwajib diisi; daftar detail model mencantumkan nilai yang diterima di bawahparameter_options(svg.model). Anda juga dapat mengirimsvg.reasoning.effort. SVG hanya berfungsi pada endpoint ini, dengann: 1, dan tanpapartial_imagesatauoutput_compression. - GIF: kirim
output_format: "gif".frame_count(2 hingga 16, default 9) mengatur jumlah bingkai, danframe_duration_ms(20 hingga 2000, default 200) mengatur durasi setiap bingkai.sizeadalah ukuran satu bingkai. GIF tidak menerimapartial_imagesatauoutput_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, dannano-banana-promendukungaspect_ratioditambahresolution(1k,2k,4k) untuk operasi publik text-to-image, image-to-image, dan image-edit mereka.nano-banana-2mendukungaspect_ratiodanresolution(1k,2k,4k) baik untuk pembuatan text-to-image maupun image-to-image.gemini-3.1-flash-lite-imagedannano-banana-2-litemendukung text-to-image, image-to-image, dan image-edit hanya pada resolusi1k.nano-bananamendukungaspect_ratiotetapi tidak mengekspos pemilihanresolutionpublik.- Untuk image-to-image dengan
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-image, ataugemini-3-pro-image, gunakan endpoint ini denganoperation: "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, ataunano-banana-propada endpoint ini (/v1/images/generations) denganoperation: "image-to-image"danimage_urls. Permintaan image-edit untuknano-banana-2,nano-banana-2.1,nano-banana-2-lite, dannano-banana-projuga menggunakan endpoint ini, denganoperation: "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 multipartimage.images[]danfile_idtidak diterima di/v1/images/generations; buat referensi/v1/fileshanya untuk model/v1/images/editsyang mendokumentasikanimages[].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.
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.
Deskripsi teks dari gambar yang diinginkan, hingga 32.000 karakter. Wajib diisi untuk setiap model yang detailnya mencantumkan prompt.
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.
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.
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.
URL gambar referensi tambahan, hingga 16, untuk model yang membedakan input utama dari referensi.
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.
1Jumlah gambar yang akan dibuat (1-10, tergantung model).
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.
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.
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.
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.
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.
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).
9Jumlah frame GIF, dari 2 hingga 16. Hanya dengan output_format: "gif".
200Durasi setiap frame GIF dalam milidetik, dari 20 hingga 2000. Hanya dengan output_format: "gif".
Cara gambar dikembalikan: url atau b64_json.
- Dikosongkan: ketika model mengembalikan byte gambar, setiap gambar berada dalam
data[].b64_json, dan juga dalamdata[].urlketika TokenLab menyimpannya. Ketika model mengembalikan tautan, setiap gambar berada dalamdata[].url. url: setiap gambar hanya ada didata[].url.b64_json: setiap gambar hanya ada didata[].b64_jsonsebagai data Base64.
Tautan adalah URL hasil media TokenLab. Tautan tetap valid selama 30 hari. Lihat Retensi data.
falseAtur 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.
Pemilih gaya opsional. Hanya kirim ini jika model yang dipilih mendokumentasikannya secara eksplisit; kosongkan untuk gpt-image-2 kecuali metadata model menyatakan sebaliknya.
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
Timestamp Unix saat pembuatan.
Array gambar yang dihasilkan.
Setiap objek berisi:
url(string): URL hasil media TokenLab untuk gambar tersebut, valid selama 30 hari. Tidak ada jikaresponse_formatadalahb64_json. Ketikaresponse_formatdikosongkan, field ini tidak ada jika TokenLab tidak dapat menyimpan gambar.b64_json(string): Data gambar Base64. Ada ketikaresponse_formatadalahb64_json, atau ketika dikosongkan dan model mengembalikan byte gambar.revised_prompt(string): Revisi prompt opsional, jika model yang dipilih mengembalikannya
Jumlah token (input_tokens, output_tokens, total_tokens, dan detailnya) untuk model dengan harga berbasis token seperti gpt-image-2, jika tersedia.
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.
Timestamp Unix saat pembuatan.
Pengenal tugas unik untuk polling.
Status awal: pending.
URL relatif untuk polling hasil, misalnya /v1/tasks/{id}.
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 -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'];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:
| Kode | Penyebab |
|---|---|
unsupported_parameter | Model tidak mencantumkan field tersebut, atau stream bernilai true |
unsupported_operation | Model tidak memiliki operation tersebut |
unsupported_endpoint | Operasi untuk model ini berada di endpoint lain, seperti /v1/images/edits |
unsupported_async_mode | Model tidak mendukung async: true |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | Nilai berada di luar yang diterima model. Error menyebutkan nilai-nilai yang diterima |
invalid_image_size_contract | size atau tingkatan yang tidak didukung model, atau yang berkonflik dengan resolution |
prompt_too_long | Prompt lebih panjang dari yang diterima model |
request_too_large, file_too_large | Unggahan 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 Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Header
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"
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.
1 <= length <= 255Respons
application/json
application/json
application/json
application/json
application/json
application/json
application/json