> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt > Use this file to discover all available pages before exploring further. # Görsel Oluştur > Bir prompt verildiğinde bir görsel oluşturur ## Genel Bakış Kod üreten ajanlar için önce `GET /v1/models?recommended_for=image` ile mevcut önerilen görsel shortlist’ini keşfedin, ardından seçilen `model`i bu endpoint’e açıkça gönderin. `gpt-image-2`, token bazlı ücretlendirilen bir GPT Image modelidir. TokenLab; metin girdisi, görsel girdisi, raporlandığında önbellek girdisi ve görsel çıktı token’ları için OpenAI’ın resmi `usage` dökümünü izler; sabit görüntü başı fiyat olarak faturalandırılmaz. `gpt-image-2` görüntü oluşturma için desteklenen herkese açık parametreler `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` veya `compression`, `moderation` ve `user` alanlarıdır. `size` veya `quality` gönderilmezse TokenLab `auto` kullanır; özel `size` değerleri aşağıda belgelenen esnek `WIDTHxHEIGHT` sözleşmesini izlemelidir. `input_fidelity`, TokenLab'in mevcut `gpt-image-2` herkese açık sözleşmesinin parçası değildir; bu alanı atlayın, aksi halde istek `400 unsupported_parameter` döner. ### Model davranışı notları Google Gemini görsel aileleri aynı selector sözleşmesini paylaşmaz: * `gemini-3.1-flash-image`, `gemini-3-pro-image` ve `nano-banana-pro`, public text-to-image ve image-edit/image-to-image işlemlerinde `aspect_ratio` ile birlikte `resolution` (`1k`, `2k`, `4k`) destekler. * `nano-banana-2`, mevcut TokenLab sözleşmesinde yalnızca text-to-image için `aspect_ratio` ile birlikte `resolution` (`1k`, `2k`, `4k`) destekler. * `gemini-2.5-flash-image`, `nano-banana` ve `nano-banana-edit`, `aspect_ratio` destekler fakat public `resolution` seçimi sunmaz. * Nano Banana referans görsel istekleri için bu endpointte (`/v1/images/generations`) `nano-banana-edit` veya `nano-banana-pro` kullanın ve `operation: "image-to-image"` ile `image_urls` gönderin. Nano Banana referans görsel isteklerini `/v1/images/edits` endpointine göndermeyin. * Nano Banana image-to-image isteklerinde `nano-banana-pro`, `resolution` (`1k`, `2k`, `4k`) içerebilir; `nano-banana-edit` bunu atlamalıdır. `nano-banana` ve `nano-banana-2` mevcut public sözleşmede text-to-image modelleridir. * Bu endpointte referans görseller JSON `image_url` / `image_urls` olarak veya multipart `image` dosyası olarak gönderilebilir. `/v1/images/generations`, `images[]` ya da `file_id` kabul etmez; `/v1/files` referansları yalnızca `images[].file_id` dokümante eden `/v1/images/edits` modelleri için kullanılır. Google görsel aileleri için `aspect_ratio` kullanmayı tercih edin ve `resolution`'ı yalnızca model açıkça destekliyorsa gönderin. xAI Grok Imagine görsel modelleri (`grok-imagine-image`, `grok-imagine-image-quality` ve legacy `grok-imagine-image-pro`) `aspect_ratio` ile birlikte `resolution` (`1k`, `2k`) destekler. `grok-imagine-image-pro`, `grok-imagine-image-quality` için uyumluluk ID’si olarak korunur. ## İstek Gövdesi **Senkron istek zaman aşımı:** Bazı görsel istekleri son görseli inline döndürür ve üretimin tamamlanmasını bekler. Yüksek çözünürlüklü veya yüksek kaliteli istekler bir dakikaya yakın ya da daha uzun sürebilir; bu yüzden HTTP istemcisi zaman aşımını en az `120s` olarak ayarlayın. Oluşturma yanıtı `status: "pending"`, `task_id` veya `poll_url` içeriyorsa, dönen `poll_url` ile polling yapın. Kullanılacak model (ör. `gpt-image-2`, `flux-pro`, `qwen-image-plus` veya `nano-banana-pro`). Güncel önerilen liste için `GET /v1/models?recommended_for=image` kullanın. İstenen görselin metin açıklaması. Image-to-image üretim için herkese açık HTTPS referans görsel URL'si. Nano Banana referans görsel isteklerinde `operation` değerini `image-to-image` yapın; `nano-banana-pro` `resolution` içerebilir, `nano-banana-edit` ise bunu atlamalıdır. Herkese açık HTTPS referans görsel URL'leri. JSON isteklerinde bir veya daha fazla referans görsel için kullanın. Bu endpoint `file_id` ve `images[]` desteklemez. Ana giriş görselleri ile referansları ayıran sağlayıcılar için ek modele özgü referans görsel URL'leri. Image-to-image üretim için multipart referans görsel dosyası. Kaynak görsel özel veya header gerektiriyorsa bunu kullanın. Bu, /v1/files `file_id` değildir; bu endpoint `file_id` kabul etmez. Üretilecek görsel sayısı (1-10, modele bağlı). Görüntü boyutu. OpenAI tarzı görüntü aileleri ve kesin piksel boyutlarını kabul eden diğer modeller için kullanın. `gpt-image-2` için `size`, `auto` veya `WIDTHxHEIGHT` kabul eder. Özel boyutlarda her iki kenar da 16’nın katı olmalı, en uzun kenar en fazla `3840px` olmalı, uzun/kısa kenar oranı en fazla `3:1` olmalı ve toplam piksel sayısı `655,360` ile `8,294,400` arasında olmalıdır. `aspect_ratio` ve `resolution`, TokenLab’nın `gpt-image-2` için mevcut genel sözleşmesine dahil değildir. Google Gemini görüntü ailelerinde `size`, modelin genel `aspect_ratio` sözleşmesine ve desteklendiğinde `resolution` sözleşmesine eşlenen bir uyumluluk alias’ı olarak değerlendirilir. Bu modellerde doğrudan `aspect_ratio` göndermeyi tercih edin. Modele bağlı en-boy oranı seçici. Google görsel ailelerinde yaygın değerler `1:1`, `16:9`, `9:16`, `3:2` ve `2:3`'tür. Modele bağlı çıktı çözünürlüğü seçici. `gemini-3.1-flash-image` ve `gemini-3-pro-image` için text-to-image ve image-edit işlemlerinde, `nano-banana-pro` için text-to-image ve image-to-image işlemlerinde, `nano-banana-2` için yalnızca text-to-image işleminde desteklenir. Tipik değerler `1k`, `2k` ve `4k`'tür. Model bunu açıkça belgelemiyorsa bu parametreyi yalnızca oran seçimi destekleyen Gemini image ailelerine göndermeyin. xAI Grok Imagine görsel modelleri için `1k` veya `2k` kullanın. Görüntü kalitesi. `gpt-image-2` gibi GPT Image modelleri `auto`, `low`, `medium` veya `high` kullanır. Diğer görüntü aileleri sağlayıcıya özel değerler kullanabilir; varsayılan olmayan değerleri göndermeden önce seçilen model metadata bilgisini kontrol edin. Yanıt formatı: `url` veya `b64_json`. Varsayılan `url` değeridir. Azure Official veya Azure-compatible `gpt-image-2` isteklerinde TokenLab görüntü verisini `b64_json` olarak alır. `url` isteklerinde TokenLab her görseli CDN’e yükler ve `data[].url` döndürür. CDN depolama kullanılamıyorsa veya upload başarısız olursa istek Base64 yanıtına çevrilmeden başarısız olur. `b64_json` için ham Base64 döndürülür. `gpt-image-2` veya resmi FLUX/BFL görüntü modelleriyle önce bir görev oluşturmak için `true` yapın. Tamamlanan asenkron görüntü görevleri, istenen `response_format` ne olursa olsun URL döndürür; `b64_json` gerekiyorsa senkron istek kullanın. İsteğe bağlı stil seçici. Yalnızca seçilen model bunu açıkça belgeliyorsa gönderin; model metadata bilgisi aksini söylemiyorsa `gpt-image-2` için göndermeyin. Son kullanıcı için benzersiz bir identifier. ## Yanıt ### Senkron Yanıt Oluşturulma zamanının Unix timestamp'i. Üretilen görsellerin dizisi. Her object şunları içerir: * `url` (string): Üretilen görselin URL'si * `b64_json` (string): Base64 kodlanmış görsel (istenirse) * `revised_prompt` (string): Upstream model raporlarsa sağlayıcıdan gelen isteğe bağlı prompt revizyonu ### Asenkron görev yanıtı `gpt-image-2` veya resmi FLUX/BFL görüntü modelleriyle `async: true` kullanarak oluşturma isteğinde nihai görüntüyü beklemek yerine bir görev oluşturun. Yanıt `status: "pending"`, `task_id` ve `poll_url` içerir. Görev `completed` veya `failed` durumuna gelene kadar `/v1/tasks/{task_id}` adresini sorgulayın. Asenkron görüntü görevleri yalnızca nihai görüntü URL’lerini döndürür. Ham `b64_json` görüntü verisi gerekiyorsa senkron istek kullanın. Görev oluşturulurken tahmini tutar rezerve edilebilir. Tamamlanan görevler gerçek kullanıma göre ücretlendirilir; başarısız olan veya zaman aşımına uğrayan görevlerin rezervi serbest bırakılır veya iade edilir. Oluşturma zamanının Unix zaman damgası. Sorgulama için benzersiz görev kimliği. İlk durum: `pending`. Sonuçları sorgulamak için göreli URL, örneğin `/v1/tasks/{id}`. Görev beklemedeyken boştur. Tamamlanan görsel görevleri, `data[].url` içinde oluşturulan görsel URL'lerini döndürür. `status: "pending"` aldığınızda, sonucu almak için `poll_url` veya `GET /v1/tasks/{task_id}` kullanın. ```bash cURL theme={null} 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", "n": 1 }' ``` ```python Python theme={null} 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", aspect_ratio="16:9", resolution="2k", n=1 ) print(response.data[0].url) ``` ```javascript JavaScript theme={null} 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', n: 1 }); console.log(response.data[0].url); ``` ```php PHP theme={null} 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', 'n' => 1 ]) ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); echo $data['data'][0]['url']; ``` Yalnızca oran seçimi destekleyen image ailesi örneği: `gemini-2.5-flash-image`, `nano-banana` veya `nano-banana-edit` için `aspect_ratio` gönderin ancak `resolution`'ı atlayın: ```json theme={null} { "model": "gemini-2.5-flash-image", "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/generations` endpointine gönderin, `/v1/images/edits` endpointine göndermeyin. `resolution` opsiyoneldir ve `1k`, `2k` veya `4k` olabilir: ```json theme={null} { "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" } ``` Özel veya yerel kaynak görseller için doğrudan multipart upload kullanın. `/v1/images/generations` endpointine `file_id` göndermeyin: ```bash theme={null} 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" ``` ```json Senkron Yanıt theme={null} { "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..." } ] } ``` ```json Asenkron Yanıt theme={null} { "created": 1706000000, "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "pending", "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "data": [] } ``` ## Kullanılabilir Modeller Bunlar güncel örnek modellerdir, sabit bir katalog değildir. En son kullanılabilirlik ve fiyat için `GET /v1/models?recommended_for=image` veya Models sayfasını kullanın. | Model | Tip | Özellikler | | -------------------- | ------------------------ | -------------------------------------------------------- | | `gpt-image-2` | Inline veya task tabanlı | Token bazlı fiyatlanan GPT Image modeli, esnek boyutlar | | `flux-pro` | Sıklıkla task tabanlı | Fotogerçekçi, yüksek kalite | | `qwen-image-plus` | Sıklıkla task tabanlı | Güçlü metin oluşturma ve prompt takibi | | `nano-banana-pro` | Sıklıkla task tabanlı | Referans görüntü akışları ve yüksek çözünürlüklü çıktı | | `grok-imagine-image` | Sıklıkla task tabanlı | En-boy oranı ve çözünürlük seçimiyle xAI görüntü üretimi | | `ideogram-v3` | Sıklıkla task tabanlı | Güçlü metin oluşturma | Bir modeli her zaman senkron ya da her zaman asenkron olarak hard-code etmeyin. Create yanıtı `status: "pending"` döndürürse, `poll_url`'ı takip edin ve tamamlanana kadar polling yapın. ## Task Tabanlı Yanıtları İşleme Görsel modeller için, yanıtın `status: "pending"` içerip içermediğini her zaman kontrol edin: