Medya kılavuzları
Görüntü oluşturma
Görüntüler oluşturun veya düzenleyin, tamamlanmış dosyaları veya asenkron görevleri yönetin
TokenLab; metinden görüntüye (text-to-image), görüntüden görüntüye (image-to-image) ve görüntü düzenleme işlemlerini destekler. Parametreler modele göre değişiklik gösterir, bu nedenle istek göndermeden önce seçilen modelin istek alanlarını kontrol edin.
Bir endpoint seçin
| İhtiyacınız olan | Endpoint | Kullanım durumu | Kullanılmaması gereken durum |
|---|---|---|---|
| Metinden görüntüye | POST /v1/images/generations | Kullanıcı sadece metinle başlıyorsa | Mevcut bir GPT Image dosyasını düzenlemek için |
| Görüntüden görüntüye | POST /v1/images/generations | Model operation: "image-to-image" ve görüntü URL'lerini kabul ediyorsa | Multipart düzenleme girişi gerektiren modeller için |
| Görüntü düzenleme | POST /v1/images/edits | Desteklenen bir düzenleme modeli mevcut bir görüntüyü değiştiriyorsa | Nano Banana tarzı referans oluşturma için |
| Varyasyon | POST /v1/images/variations | Mevcut bir entegrasyon zaten variations API'sini kullanıyorsa | Yeni bir referans-görüntü özelliği için |
| Durum | GET /v1/tasks/{id} | Oluşturma yanıtı task_id, status: "pending" veya poll_url döndürüyorsa | Oluşturma yanıtı zaten nihai data[] içeriyorsa |
Her zaman model gönderin; görüntü API'leri sizin yerinize varsayılan bir model seçmez.
Bir model seçin
Güncel görüntü modellerini şununla bulun:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"Şunları doğrulamak için seçilen modelin detaylarını açın:
text-to-image,image-to-imageveyaimage-editgibi desteklenen işlem.- Modelin beklediği istek endpoint'i.
- Referansların nasıl gönderileceği:
image_url,image_urls,reference_image_urls, multipartimageveya JSONimages[]. - Modelin
size,aspect_ratio,resolution,quality,background,output_formatveyaresponse_formatkabul edip etmediği.
Modele özgü alanlar
gpt-image-2tarzı istekler, OpenAI benzerisize,qualityve düzenleme alanlarını kullanır. Bu modelle oluşturma ve düzenleme işlemleri içinbackgroundalanıautoveyaopaquedeğerlerini kabul eder;transparentdesteklenmez. Otomatik varsayılanları kullanmak için isteğe bağlı alanları boş bırakın.- Gemini ve Nano Banana görüntü aileleri genellikle
aspect_ratiokullanır;resolutiondeğerini yalnızca model detaylarında belirtilmişse gönderin. Çözünürlük katmanlarına sahip modellerde,1K,2Kveya4Kboyutundaki birsizedeğeriresolutionolarak gönderilir;resolutiondeğerinden farklı bir katman reddedilir. - Nano Banana görüntüden görüntüye işlemi,
operation: "image-to-image"ve referans görüntü URL'leri ile/v1/images/generationsüzerinde gerçekleştirilmelidir. /v1/images/generations, üst düzeyimages[]veyafile_idkabul etmez; bunlar düzenleme akışı yapılarıdır.- Uzak görüntü referansları herkese açık
httpveyahttpsURL'leri olmalıdır. Özel ağ URL'leri, gömülü kimlik bilgileri, URL parçaları veya işleme başlamadan önce süresi dolabilecek imzalı URL'ler göndermeyin.
Metinden görüntüye örneği
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
"size": "1024x1024",
"response_format": "url"
}'Referans-görüntü örneği
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'Görüntüyü alma
Görüntü yanıtları senkron veya asenkron olabilir:
- Senkron yanıtlar,
urlveyab64_jsoniçeren nihaidata[]değerini döndürür. - Asenkron yanıtlar
id,task_id,statusve genelliklepoll_urldöndürür. Görüntüyü beklemek yerine bir görev almak için, genel asenkron yürütmeyi destekleyen bir modelde"async": truegönderin. - Asenkron bir görevi kontrol etmek için, döndürülen
idveyatask_idileGET /v1/tasks/{id}çağrısı yapın. b64_jsondeğerine ihtiyaç duyduğunuzda senkron bir istek kullanın; asenkron görüntü sonuçları URL'leri kullanır.
Görüntü sonuç URL'leri, 30 gün boyunca geçerli kalan TokenLab medya-sonuç URL'leridir. media_retention.items, her öğenin kaydetme durumunu ve expires_at değerini raporlar; kaydetme durumu zamanında bilinmediğinde yanıt media_retention alanını içermeyebilir ancak URL yine de çalışır. Satır içi Base64 sonuçları bu URL kopyalama saklama süresinin dışındadır. Bir görüntüyü manuel olarak Medya Kütüphanesine kaydetmek, ona ayrı bir yaşam döngüsü kazandırır. Bkz: Veri saklama.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Döndürülen görüntü URL'sini, görev kimliğini, modeli ve kendi kullanıcı/iş kimliğinizi kalıcı hale getirin. Terminal durumuna ulaşıldıktan sonra sorgulamaya devam etmeyin.
Başlatmadan önce
- TokenLab'i çağırmadan önce kullanıcı girişlerini doğrulayın: istem uzunluğu, görüntü sayısı, URL erişilebilirliği ve dosya türü.
- Senkron yüksek çözünürlüklü istekler için HTTP zaman aşımlarını yeterince yüksek ayarlayın. Uzun süren işlemler için modelin desteklediği yerlerde
async: truekullanın. request_id,task_id,poll_url, model, endpoint ve gönderilen alan adlarını saklayın.- Bir görüntü isteği bir görev döndürdüğünde,
Idempotency-Keyoluşturma isteğini yeniden denemeyi güvenli hale getirir: bir istemci zaman aşımından sonra, aynı görevi almak için aynı anahtarla aynı isteği gönderin. Doğrudan görüntüyü döndüren bir istek için, aynı anahtarla yapılan bir yeniden deneme, görüntü yerine bir görev durumu veyaidempotent_response_not_replayablehatasıyla409döndürebilir. Bir anahtarınız yoksa, yeniden denemeden önce bir görev oluşturulup oluşturulmadığını kontrol edin. - Nihai ücretlendirme için Kullanım (Usage) ve
billing_transaction_iddeğerlerini kullanın.
Yaygın Hatalar
| Belirti | Olası neden | Çözüm |
|---|---|---|
param: "model" ile 400 | Açık model eksikliği | /v1/models?recommended_for=image sorgusunu yapın ve model gönderin |
| Desteklenmeyen alan | Alan o model için belgelenmemiş | Alanı kaldırın veya onu belgeleyen bir model/endpoint seçin |
Asenkron sonuçta b64_json yok | Asenkron görüntü görevleri URL odaklı sonuçlar döndürür | Base64 çıktısı için senkron modu kullanın |
| Referans görüntü reddedildi | Yanlış endpoint veya özel/süresi dolmuş URL | Modelin belgelenmiş referans yapısıyla eşleştirin ve erişilebilir URL'ler kullanın |
API Referansı
| Konu | Referans |
|---|---|
| Görüntü Oluştur | Görüntü Oluştur |
| Görüntü Düzenle | Görüntü Düzenle |
| Görüntü Varyasyonu Oluştur | Görüntü Varyasyonu Oluştur |
| Görüntü Durumunu Al | Görüntü Durumunu Al |
| Görev Durumunu Al | Görev Durumunu Al |