Görseller
Görsel Oluştur
Belirtilen bir istemden görsel oluşturur
Genel Bakış
Mevcut görsel modellerini almak için GET /v1/models?recommended_for=image kullanın, ardından seçilen model bilgisini açıkça gönderin.
Her model kendi işlemlerini ve alanlarını kabul eder. GET /v1/models/{model} (Modeli Al), tokenlab.request_format_summary.request_endpoint_by_operation içinde her işlem için uç noktayı ve tokenlab.request_format_details.operation_constraints içinde her işlem için kabul edilen alanları, değerleri ve sınırları verir. Modelin listelemediği bir alan 400 unsupported_parameter döndürebilir. Yanlış uç noktaya gönderilen bir işlem 400 unsupported_endpoint döndürür.
Görsel görevleri ve sonuçları:
- Desteklenen parametreleri arasında
asynclisteleyen modeller önce bir görev oluşturabilir:async: truegönderin, ardındanGET /v1/tasks/{id}uç noktasını yoklayın. - Görsel bağlantıları 30 gün boyunca saklanır; bkz. Veri saklama.
- Bir zaman aşımından sonra oluşturma isteğini güvenli bir şekilde yeniden denemek için bir
Idempotency-Keyüst bilgisi gönderin; bkz. Bir idempotency key ile güvenle yeniden deneme.
gpt-image-2, token bazlı fiyatlandırılan bir GPT Image modelidir. TokenLab; metin girdisi, görsel girdisi, bildirilen önbelleğe alınmış girdi ve görsel çıktısı token'ları için OpenAI'ın resmi kullanım dökümünü takip eder; görsel başına sabit ücretlendirilen bir model değildir.
gpt-image-2 görsel oluşturma için desteklenen genel parametreler prompt, n, size, quality, response_format, async, background, output_format, output_compression veya compression, moderation ve user'dır. background, auto veya opaque kabul eder; transparent desteklenmez. TokenLab'in auto kullanmasına izin vermek için size veya quality parametrelerini atlayın; özel size değerleri aşağıda belgelenen esnek WIDTHxHEIGHT sözleşmesini kullanmalıdır.
input_fidelity, gpt-image-2 için TokenLab tarafından desteklenen mevcut alanların bir parçası değildir; bunu atlayın, aksi takdirde istek 400 unsupported_parameter döndürür.
SVG ve GIF çıktısı
gpt-image-2.6-flare ve gpt-image-2.6-sunburst, raster görüntü yerine SVG veya animasyonlu GIF döndürebilir. Diğer modeller bu formatları reddeder.
- SVG:
output_format: "svg"vesvg: {"model": "..."}gönderin. Görüntü modeli önce bir referans görüntü çizer, ardından yazar model bundan SVG'yi oluşturur.svg.modelzorunludur; model detayları, kabul edilen değerleriniparameter_options(svg.model) altında listeler. Ayrıcasvg.reasoning.effortda gönderebilirsiniz. SVG yalnızca bu uç noktada,n: 1ile vepartial_imagesveyaoutput_compressionolmadan çalışır. - GIF:
output_format: "gif"gönderin.frame_count(2 ile 16 arası, varsayılan 9) kare sayısını,frame_duration_ms(20 ile 2000 arası, varsayılan 200) ise her karenin süresini belirler.size, bir karenin boyutudur. GIF,partial_imagesveyaoutput_compressionkabul etmez.
Sonuç, diğer görüntülerde olduğu gibi data[].b64_json veya data[].url içindedir. Bir SVG'yi UTF-8 XML metni olarak çözün ve .svg olarak kaydedin; bir GIF'i ise .gif olarak kaydedin.
Faturalandırma: Görüntü token'ları, modelin token fiyatları üzerinden faturalandırılır ve GIF kareleri görüntü çıktı token'ları olarak sayılır. Bir SVG isteği ayrıca, yanıtın svg_usage kısmında bildirdiği yazar modelin token'larını, model sayfasında gösterilen SVG oluşturma fiyatları üzerinden faturalandırır.
Model davranışı notları
Google Gemini görsel ailesi modelleri aynı seçici sözleşmesini paylaşmaz:
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3-pro-image,nano-banana-2.1venano-banana-progenel text-to-image, image-to-image ve image-edit işlemleri içinaspect_ratioile birlikteresolution(1k,2k,4k) parametrelerini destekler.nano-banana-2, hem text-to-image hem de image-to-image oluşturma içinaspect_ratioveresolution(1k,2k,4k) parametrelerini destekler.gemini-3.1-flash-lite-imagevenano-banana-2-liteyalnızca1kçözünürlükte text-to-image, image-to-image ve image-edit işlemlerini destekler.nano-banana,aspect_ratioparametresini destekler ancak genelresolutionseçimini sunmaz.gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-imageveyagemini-3-pro-imageile image-to-image içinoperation: "image-to-image"ve referans görsellerle birlikte bu uç noktayı kullanın. Bu modeller için image-edit isteklerini/v1/images/editsuç noktasına gönderin.- Nano Banana referans görsel istekleri için bu uç noktada (
/v1/images/generations)operation: "image-to-image"veimage_urlsilenano-banana-2,nano-banana-2.1,nano-banana-2-liteveyanano-banana-prokullanın.nano-banana-2,nano-banana-2.1,nano-banana-2-litevenano-banana-proiçin image-edit istekleri deoperation: "image-edit"ile bu uç noktayı kullanır. Nano Banana referans görsel isteklerini/v1/images/editsuç noktasına göndermeyin. - Bu uç noktadaki referans görseller, JSON formatında
image_url/image_urlsolarak veya multipartimagedosyası olarak sağlanabilir.images[]vefile_id,/v1/images/generationsuç noktasında kabul edilmez;/v1/filesreferanslarını yalnızcaimages[].file_idparametresini belgeleyen/v1/images/editsmodelleri için oluşturun.
Google görsel aileleri için aspect_ratio tercih edin ve resolution parametresini yalnızca model açıkça desteklediğinde gönderin.
xAI Grok Imagine görsel modelleri (grok-imagine-image ve grok-imagine-image-2.0), aspect_ratio ile birlikte resolution (1k, 2k) parametresini destekler. Text-to-image bu uç noktayı kullanır. Bu modellerin image-to-image ve image-edit istekleri /v1/images/edits uç noktasını kullanır.
hy-image-v3.5-preview, bu uç noktada metinden istek başına bir adet 1024x1024 görsel oluşturur ve yalnızca response_format: "url" destekler. Referans görselleri /v1/images/edits üzerinde düzenler.
İstek Gövdesi
Senkron istek zaman aşımı: Bazı görsel istekleri nihai görseli satır içi (inline) olarak döndürür ve oluşturmanın bitmesini bekler. Yüksek çözünürlüklü veya yüksek kaliteli istekler bir dakikaya yakın veya daha uzun sürebilir, bu nedenle HTTP istemcisi zaman aşımınızı en az 120s olarak ayarlayın. Oluşturma yanıtı status: "pending", task_id veya poll_url içeriyorsa, bunun yerine GET /v1/tasks/{task_id} uç noktasını yoklayın.
Kullanılacak model (örneğin, gpt-image-2, flux-pro-1.1 veya nano-banana-pro). Güncel önerilen liste için GET /v1/models?recommended_for=image sorgusunu yapın.
İstenen görselin metin açıklaması, en fazla 32.000 karakter. Ayrıntılarında prompt listeleyen her model için gereklidir.
text-to-image, image-to-image veya image-edit. Belirtilmediğinde, istekte bir referans görsel varsa image-to-image, aksi takdirde text-to-image olur. nano-banana-pro gibi düzenleme işlemi bu uç noktada olan modeller için image-edit olarak ayarlayın. Referans görsel içeren text-to-image isteği 400 invalid_parameter döndürür.
image-to-image oluşturma için herkese açık görsel URL'si. Nano Banana referans görsel istekleri için operation değerini image-to-image olarak ayarlayın; nano-banana-pro resolution içerebilir.
Herkese açık referans görsel URL'leri, en fazla 16 adet. JSON isteklerinde bir veya daha fazla referans görsel için bunu kullanın. file_id ve images[] bu uç noktada desteklenmez.
Birincil girdileri referanslardan ayıran modeller için 16 adede kadar ek referans görsel URL'si.
image-to-image oluşturma için multipart referans görsel dosyası. Kaynak görsel gizli olduğunda veya üst bilgi (header) korumalı olduğunda bunu kullanın. Bu, bu uç noktada kabul edilmeyen bir /v1/files file_id değerinden farklıdır.
1Oluşturulacak görsel sayısı (1-10, modele bağlıdır).
Görsel boyutu. Bunu OpenAI tarzı görsel aileleri ve tam piksel boyutlarını kabul eden diğer modeller için kullanın.
gpt-image-2 için size, auto veya WIDTHxHEIGHT kabul eder. Özel boyutların her ikisi de 16'nın katı olmalı, en uzun kenar en fazla 3840px olmalı, uzun/kısa oranı en fazla 3:1 olmalı ve toplam piksel 655,360 ile 8,294,400 arasında olmalıdır. aspect_ratio ve resolution, gpt-image-2 için mevcut TokenLab model ayrıntılarının bir parçası değildir.
Çözünürlük katmanlarına sahip Google görsel modelleri için (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 ve nano-banana-pro), size parametresi modelin boyut tablosundan 1376x768 (1K'da 16:9) gibi bir çıktı boyutunu veya bir çözünürlük katmanını kabul eder: 1K, 2K veya 4K. TokenLab bir katmanı resolution olarak gönderir, bu nedenle istek ve fiyatı resolution ile aynıdır. Modelin desteklemediği bir katman (örneğin gemini-3.1-flash-lite-image üzerinde 2K) veya resolution parametresinden farklı bir katman, invalid_image_size_contract kodu ve modelin allowed_resolutions listesi ile birlikte 400 döndürür. Bu modeller için önerilen biçim resolution ile birlikte aspect_ratio kullanılmasıdır.
Modele bağlı en boy oranı seçicisi.
Yaygın Google görsel ailesi değerleri arasında 1:1, 16:9, 9:16, 3:2 ve 2:3 bulunur.
Modele bağlı çıktı çözünürlüğü. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1 ve nano-banana-pro 1k, 2k ve 4k destekler; Grok Imagine görsel modelleri 1k ve 2k destekler. Seçilen model ve işlem açıkça desteklemediği sürece bu alanı atlayın.
Görsel kalitesi. gpt-image-2 gibi GPT Image modelleri auto, low, medium veya high kullanır. Diğer modeller farklı değerler kullanabilir; varsayılan olmayan bir değer göndermeden önce model ayrıntılarını kontrol edin.
Görüntünün dosya formatı: png, jpeg veya webp. gpt-image-2.6-flare ve gpt-image-2.6-sunburst ayrıca svg ve gif formatlarını da kabul eder; bkz. SVG ve GIF çıktısı.
SVG ayarları, yalnızca output_format: "svg" ile kullanılır. model (zorunlu), SVG'yi oluşturan yazar modeli seçer. reasoning.effort ise isteğe bağlı olarak muhakeme çabasını ayarlar.
9GIF kare sayısı, 2 ile 16 arası. Yalnızca output_format: "gif" ile kullanılır.
200Her bir GIF karesinin milisaniye cinsinden süresi, 20 ile 2000 arası. Yalnızca output_format: "gif" ile kullanılır.
Görsellerin nasıl döndürüleceği: url veya b64_json.
- Belirtilmediğinde: model görsel baytları döndürdüğünde her görsel
data[].b64_jsoniçinde yer alır ve TokenLab depoladığındadata[].urliçinde de bulunur. Model bir bağlantı döndürdüğünde her görseldata[].urliçinde yer alır. url: her görsel yalnızcadata[].urliçinde yer alır.b64_json: her görsel yalnızca Base64 verisi olarakdata[].b64_jsoniçinde yer alır.
Bağlantılar TokenLab medya sonucu URL'leridir. 30 gün boyunca geçerli kalırlar. Bkz. Veri saklama.
falseÖnce bir görev oluşturmak için true olarak ayarlayın. Yalnızca desteklenen parametreleri arasında async listeleyen modeller bunu kabul eder; örneğin gpt-image-2, flux-pro-1.1, nano-banana-pro ve seedream-5.0-lite. Diğer tüm modeller için istek 400 unsupported_async_mode hatası döndürür. Tamamlanan async görsel görevleri, istenen response_format değerinden bağımsız olarak URL döndürür; b64_json formatına ihtiyaç duyduğunuzda senkron istekleri kullanın.
İsteğe bağlı stil seçici. Bunu yalnızca seçilen model açıkça belgelediğinde gönderin; model meta verileri aksini belirtmedikçe gpt-image-2 için bunu atlayın.
Son kullanıcı için benzersiz bir tanımlayıcı.
Bazı modeller negative_prompt, seed, width, height, steps, guidance_scale veya mask_url gibi alanları da kabul eder. Bunları yalnızca modelin ayrıntıları listelediğinde gönderin. stream: true desteklenmez ve 400 unsupported_parameter döndürür.
Yanıt
Satır İçi Yanıt
Oluşturulma zamanının Unix zaman damgası.
Oluşturulan görseller dizisi.
Her nesne şunları içerir:
url(string): Görselin 30 gün geçerli TokenLab medya sonucu URL'si.response_formatb64_jsonolduğunda mevcut değildir.response_formatbelirtilmediğinde, TokenLab görseli depolayamadıysa eksiktir.b64_json(string): Base64 görsel verisi.response_formatb64_jsonolduğunda veya belirtilmediğinde ve model görsel baytları döndürdüğünde mevcuttur.revised_prompt(string): Seçilen model döndürdüğünde, isteğe bağlı istem revizyonu
Mevcut olduğunda, gpt-image-2 gibi token bazlı fiyatlandırılan modeller için token sayıları (input_tokens, output_tokens, total_tokens ve ayrıntıları).
SVG author model'inin token sayıları (model, input_tokens, output_tokens, reasoning_tokens, total_tokens). Yalnızca SVG çıktısı için mevcuttur. Bu token'lar usage içerisinde yer almaz ve SVG oluşturma fiyatları üzerinden ücretlendirilir.
Asenkron Görev Yanıtı
Oluşturma isteğinde nihai görseli beklemek yerine bir görev oluşturmak için destekleyen bir modelde async: true ayarlayın. Yanıt status: "pending", task_id ve poll_url içerir. Görev completed veya failed durumuna ulaşana kadar /v1/tasks/{task_id} uç noktasını yoklayın.
Asenkron görsel görevleri yalnızca nihai görsel URL'lerini döndürür. Ham b64_json görsel verisine ihtiyacınız varsa, senkron bir istek kullanın.
Faturalandırma, görev oluşturulduğunda tahmini tutarı bloke edebilir. Tamamlanan görevler gerçek kullanıma göre faturalandırılır, başarısız olan veya zaman aşımına uğrayan görevlerin blokesi kaldırılır veya ücreti iade edilir.
Oluşturulma zamanının Unix zaman damgası.
Yoklama için benzersiz görev tanımlayıcısı.
Başlangıç durumu: pending.
Sonuçları yoklamak için göreli URL, örneğin /v1/tasks/{id}.
Görev beklemedeyken boştur. Tamamlanan görsel görevleri, oluşturulan görsel URL'lerini data[].url içinde döndürür.
status: "pending" aldığınızda, sonucu almak için GET /v1/tasks/{task_id} çağrısını yapın.
İstek
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'];Yalnızca oran destekleyen görsel ailesi örneği: nano-banana için aspect_ratio gönderin ancak resolution parametresini atlayın:
{
"model": "nano-banana",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}Nano Banana Pro referans görsel örneği: isteği /v1/images/edits yerine /v1/images/generations uç noktasına gönderin. resolution isteğe bağlıdır ve 1k, 2k veya 4k olarak ayarlanabilir:
{
"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"
}Gizli veya yerel kaynak görseller için doğrudan multipart yükleme örneği. /v1/images/generations uç noktasına bir file_id iletmeyin:
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"Yanıt
{
"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..."
}
]
}Hatalar
İstek hataları, bir error.code ile birlikte 400 (aşırı büyük yüklemeler için 413) döndürür. Görsel istekleri için yaygın kodlar:
| Kod | Neden |
|---|---|
unsupported_parameter | Model alanı listelemiyor veya stream değeri true |
unsupported_operation | Modelde böyle bir operation yok |
unsupported_endpoint | Bu model için işlem /v1/images/edits gibi başka bir uç noktada |
unsupported_async_mode | Model async: true desteklemiyor |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | Bir değer modelin kabul ettiğinin dışında. Hata, kabul edilen değerleri belirtir |
invalid_image_size_contract | Modelin desteklemediği bir size veya katman ya da resolution ile çakışan bir değer |
prompt_too_long | İstem, modelin kabul ettiğinden daha uzun |
request_too_large, file_too_large | Bir yükleme boyut sınırının üzerinde (dosya başına 50 MiB, tüm girdiler için 200 MiB) |
Bakiye (402), hız sınırı (429) ve yeniden deneme kuralları için bkz. Hata yönetimi.
Bir Model Seçin
Güncel kullanılabilirlik, yetenekler ve fiyatlar için GET /v1/models?recommended_for=image sorgusunu yapın veya Modeller sayfasını kullanın.
Bir modeli her zaman senkron veya her zaman asenkron olarak sabit kodlamayın. async: true içermeyen bir istek de status: "pending" döndürebilir; oluşturma yanıtı status: "pending" veya status: "processing" taşıdığında, tamamlanana kadar GET /v1/tasks/{task_id} uç noktasını yoklayın.
Görev Tabanlı Yanıtları İşleme
Görsel modelleri için yanıtın status: "pending" / status: "processing" içerip içermediğini her zaman kontrol edin:
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}")Hy Image 3.5 Preview örneği. Yalnızca size 1024x1024 ve n 1 alır:
{
"model": "hy-image-v3.5-preview",
"prompt": "A yellow lemon on a white table",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Yetkilendirme
BearerAuth API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.
Konum: header
Başlıklar
İstek bazlı Teslimat politikası. API anahtarı ve Çalışma Alanı varsayılanlarını geçersiz kılar. Otomatik olarak önce TokenLab Verified dener ve çıktı, istek kabulü veya kalıcı kaynak oluşturma öncesinde bir kez Official seçeneğine geçiş yapabilir.
Geçerli değerler
- "auto"
- "verified"
- "official"
İstek bir görev oluşturduysa, görüntü isteğinin güvenli bir şekilde yeniden denenmesini sağlayan isteğe bağlı anahtar. Her istek için UUID gibi yeni ve benzersiz bir değer gönderin. Aynı anahtar ve aynı gövde ile yapılan bir yeniden deneme, o görevi döndürür ve ikinci bir görev oluşturmaz, göndermez veya ücretlendirmez. Görüntüyü doğrudan döndüren bir istek için, aynı anahtarla yapılan bir yeniden deneme, görüntü yerine bir görev durumu veya idempotent_response_not_replayable ile 409 hatası döndürebilir. Daha önce kabul edilmiş bir anahtara sahip farklı bir gövde reddedilir; bu durum için durum kodu ve hata kodu garanti edilmez. 255 karakterden uzun bir anahtar yok sayılır ve bu durumda isteğin idempotency koruması olmaz. Bkz: Idempotency anahtarı ile güvenli yeniden deneme.
1 <= length <= 255Yanıt
application/json
application/json
application/json
application/json
application/json
application/json
application/json