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 olanEndpointKullanım durumuKullanılmaması gereken durum
Metinden görüntüyePOST /v1/images/generationsKullanıcı sadece metinle başlıyorsaMevcut bir GPT Image dosyasını düzenlemek için
Görüntüden görüntüyePOST /v1/images/generationsModel operation: "image-to-image" ve görüntü URL'lerini kabul ediyorsaMultipart düzenleme girişi gerektiren modeller için
Görüntü düzenlemePOST /v1/images/editsDesteklenen bir düzenleme modeli mevcut bir görüntüyü değiştiriyorsaNano Banana tarzı referans oluşturma için
VaryasyonPOST /v1/images/variationsMevcut bir entegrasyon zaten variations API'sini kullanıyorsaYeni bir referans-görüntü özelliği için
DurumGET /v1/tasks/{id}Oluşturma yanıtı task_id, status: "pending" veya poll_url döndürüyorsaOluş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-image veya image-edit gibi desteklenen işlem.
  • Modelin beklediği istek endpoint'i.
  • Referansların nasıl gönderileceği: image_url, image_urls, reference_image_urls, multipart image veya JSON images[].
  • Modelin size, aspect_ratio, resolution, quality, background, output_format veya response_format kabul edip etmediği.

Modele özgü alanlar

  • gpt-image-2 tarzı istekler, OpenAI benzeri size, quality ve düzenleme alanlarını kullanır. Bu modelle oluşturma ve düzenleme işlemleri için background alanı auto veya opaque değerlerini kabul eder; transparent desteklenmez. 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_ratio kullanır; resolution değerini yalnızca model detaylarında belirtilmişse gönderin. Çözünürlük katmanlarına sahip modellerde, 1K, 2K veya 4K boyutundaki bir size değeri resolution olarak gönderilir; resolution değ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üzey images[] veya file_id kabul etmez; bunlar düzenleme akışı yapılarıdır.
  • Uzak görüntü referansları herkese açık http veya https URL'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, url veya b64_json içeren nihai data[] değerini döndürür.
  • Asenkron yanıtlar id, task_id, status ve genellikle poll_url döndürür. Görüntüyü beklemek yerine bir görev almak için, genel asenkron yürütmeyi destekleyen bir modelde "async": true gönderin.
  • Asenkron bir görevi kontrol etmek için, döndürülen id veya task_id ile GET /v1/tasks/{id} çağrısı yapın.
  • b64_json değ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: true kullanı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-Key oluş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 veya idempotent_response_not_replayable hatasıyla 409 dö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_id değerlerini kullanın.

Yaygın Hatalar

BelirtiOlası nedenÇözüm
param: "model" ile 400Açık model eksikliği/v1/models?recommended_for=image sorgusunu yapın ve model gönderin
Desteklenmeyen alanAlan o model için belgelenmemişAlanı kaldırın veya onu belgeleyen bir model/endpoint seçin
Asenkron sonuçta b64_json yokAsenkron görüntü görevleri URL odaklı sonuçlar döndürürBase64 çıktısı için senkron modu kullanın
Referans görüntü reddedildiYanlış endpoint veya özel/süresi dolmuş URLModelin belgelenmiş referans yapısıyla eşleştirin ve erişilebilir URL'ler kullanın

API Referansı

KonuReferans
Görüntü OluşturGörüntü Oluştur
Görüntü DüzenleGörüntü Düzenle
Görüntü Varyasyonu OluşturGörüntü Varyasyonu Oluştur
Görüntü Durumunu AlGörüntü Durumunu Al
Görev Durumunu AlGörev Durumunu Al

Bu sayfada