TokenLab
API anahtarı al
DokümantasyonAPI ReferansıEntegrasyonlar

Görseller

Görüntü Düzenleme

Bir istem ve kaynak görüntü kullanarak görüntüyü düzenleyin

POST
/v1/images/edits

Genel Bakış

Orijinal bir görüntü ve bir istem verildiğinde, düzenlenmiş veya genişletilmiş bir görüntü oluşturur.

Bu uç nokta şunları destekler:

  • Aşağıda belgelenen OpenAI uyumlu multipart/form-data yükleme akışı
  • Desteklenen görüntüden görüntüye (image-to-image) aileleri için image_url, image_urls veya resmi images referansları sağlayan JSON istekleri

gpt-image-2 burada desteklenmektedir. Multipart image yüklemelerini, JSON image_url / image_urls verilerini ve 16 adede kadar kaynak görüntü ile resmi images[] referanslarını (image_url veya file_id) kabul eder. file_id değerlerini önce /v1/files aracılığıyla oluşturun. Önce bir görev döndürmek için async: true olarak ayarlayın; resmi FLUX/BFL düzenleme modelleri de aynı görev yoklama (polling) akışını kullanır.

gpt-image-2 düzenlemeleri resolution kabul etmez; çıktı boyutları için size kullanın. background parametresi auto veya opaque değerlerini kabul eder; transparent desteklenmez. Çoklu görüntü veya yüksek gecikmeli düzenlemeler için async: true kullanılması ve döndürülen görevin yoklanması önerilir.

Nano Banana referans görüntüsü istekleri (nano-banana-2, nano-banana-2.1, nano-banana-2-lite ve nano-banana-pro), bu /v1/images/edits uç noktasında değil, operation: "image-to-image" ve image_urls ile /v1/images/generations üzerinde sunulur. nano-banana-2, nano-banana-2.1, nano-banana-2-lite ve nano-banana-pro için görüntü düzenleme istekleri de operation: "image-edit" ile /v1/images/generations kullanır.

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image ve gemini-3-pro-image görüntü düzenleme için bu uç noktayı kullanır. Bunların görüntüden görüntüye istekleri, operation: "image-to-image" ile /v1/images/generations kullanır.

xAI Grok Imagine görüntü düzenleme modelleri sınırlı sayıda kaynak görüntü kabul eder: grok-imagine-image-2.0 en fazla 5, grok-imagine-image ve eski grok-imagine-image-pro en fazla 3. Modelin kabul ettiğinden fazla kaynak görüntü içeren istekler, 400 too_many_images hatasıyla giriş doğrulamasından geçemez.

input_fidelity, gpt-image-2 için mevcut TokenLab destekli alanların bir parçası değildir; bunu atlayın, aksi takdirde istek 400 unsupported_parameter döndürür.

İstek Gövdesi

Senkron istek zaman aşımı: Bazı görüntü istekleri, nihai görüntüyü satır içi (inline) olarak döndürür ve oluşturma işleminin bitmesini bekler. Yüksek çözünürlüklü veya yüksek kaliteli istekler bir dakika 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 döndürülen poll_url adresini takip edin.

Uzak görüntü URL'leri: Multipart giriş gerektiğinde, TokenLab JSON image_url, image_urls veya images[].image_url verilerini getirir ve baytları multipart image parçaları olarak gönderir. URL'ler, gömülü kimlik bilgileri veya parçalar içermeyen, herkese açık http/https adresleri olmalı ve localhost, özel veya ayrılmış IP aralıklarına çözümlenmemelidir; her yönlendirme tekrar kontrol edilir. Getirilen yük gerçek bir PNG, JPEG veya WebP görüntüsü olmalıdır. Sınırlar görüntü başına 50 MiB, tek bir istekte URL ile getirilen görüntüler için toplam 200 MiB, 30s getirme zaman aşımı ve en fazla 3 yönlendirmedir.

JSON istekleri için image_url, image_urls veya images alanlarından tam olarak birini sağlayın. Her images[] nesnesi, image_url veya file_id alanlarından tam olarak birini içermelidir. 200 MiB'lık toplam sınır, tüm kaynak görüntüleri ve maskeyi içerir.

imagefile

Multipart kaynak görüntüler. Birden fazla GPT Image kaynağı sağlamak için image alanını tekrarlayın. Dosyalar PNG, JPEG veya WebP olmalı, 16 adede kadar kaynak görüntü ve her biri en fazla 50 MiB olmalıdır. xAI Grok Imagine düzenleme modelleri aynı giriş alanlarını kullanır ancak kaynak görüntüleri sınırlar: grok-imagine-image-2.0 için en fazla 5, diğer xAI düzenleme modelleri için en fazla 3.

promptstringzorunlu

İstenen düzenlemenin metin açıklaması.

maskfile | object

Tamamen şeffaf alanları görüntünün neresinin düzenlenmesi gerektiğini gösteren ek bir görüntü. Geçerli bir PNG dosyası olmalı, 50 MiB'dan küçük olmalı ve image ile aynı boyutlara sahip olmalıdır.

JSON istekleri için mask, image_url veya file_id alanlarından tam olarak birini içeren bir nesne de olabilir; file_id değerleri /v1/files üzerinden gelmeli ve aynı görüntü düzenleme yapılandırmasına bağlı kalmalıdır.

modelstringzorunlu

Görüntü düzenlemeleri için kullanılacak model. GPT Image düzenlemeleri için gpt-image-2 veya GET /v1/models?recommended_for=image tarafından döndürülen başka bir güncel görüntü düzenleme modelini kullanın.

nintegervarsayılan: 1

Oluşturulacak görüntü sayısı (1-10, modele bağlıdır).

sizestring

Oluşturulan görüntünün boyutu. gpt-image-2 için auto veya WIDTHxHEIGHT kullanın; boyutlar 16'nın katı olmalı, en uzun kenar en fazla 3840px, uzun/kısa oranı en fazla 3:1 ve toplam piksel sayısı 655,360 ile 8,294,400 arasında olmalıdır.

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image ve gemini-3.1-flash-lite-image için size, modelin boyut tablosundan bir çıktı boyutu veya bir çözünürlük katmanı (1K, 2K veya 4K) kabul eder. TokenLab, bir katmanı resolution olarak gönderir. Modelin desteklemediği veya resolution değerinden farklı bir katman, invalid_image_size_contract koduyla 400 hatası döndürür. Önerilen biçim, resolution ile birlikte aspect_ratio kullanılmasıdır.

response_formatstring

Görüntülerin nasıl döndürüleceği: url veya b64_json.

  • Belirtilmediğinde: Model görüntü baytlarını döndürdüğünde, her görüntü data[].b64_json içindedir ve TokenLab depoladığında data[].url içinde de bulunur. Model bir bağlantı döndürdüğünde, her görüntü data[].url içindedir.
  • url: Her görüntü yalnızca data[].url içindedir.
  • b64_json: Her görüntü yalnızca Base64 verisi olarak data[].b64_json içindedir.

Bağlantılar TokenLab medya sonucu URL'leridir. 30 gün boyunca geçerlidirler. Bkz: Veri saklama.

asyncbooleanvarsayılan: false

Nihai görüntü hazır olmadan önce bir görev döndürmek için gpt-image-2 veya resmi FLUX/BFL düzenleme modelleriyle true olarak ayarlayın. Tamamlanan asenkron düzenlemeler, istenen response_format ne olursa olsun URL döndürür; b64_json verisine ihtiyacınız olduğunda senkron istekleri kullanın.

userstring

Kötüye kullanım izleme için son kullanıcınızı temsil eden benzersiz bir tanımlayıcı.

Yanıt

createdinteger

Görüntülerin oluşturulduğu Unix zaman damgası.

dataarray

Oluşturulan görüntülerin dizisi.

Her nesne şunları içerir:

  • url (string): Düzenlenen görüntünün 30 gün geçerli TokenLab medya sonucu URL'si. response_format b64_json olduğunda mevcut değildir. response_format belirtilmediğinde, TokenLab görüntüyü depolayamadıysa eksiktir.
  • b64_json (string): Base64 görüntü verisi. response_format b64_json olduğunda veya belirtilmediğinde ve model görüntü baytlarını döndürdüğünde mevcuttur.

Asenkron Görev Yanıtı

İstekte düzenlenen görüntüyü beklemek yerine bir görev oluşturmak için gpt-image-2 veya resmi FLUX/BFL düzenleme modelleriyle async: true olarak 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} adresini yoklayın.

Asenkron düzenleme görevleri yalnızca nihai görüntü URL'lerini döndürür. Ham b64_json görüntü verisine ihtiyacınız varsa, senkron bir istek kullanın.

Faturalandırma, görev oluşturulduğunda tahmini tutarı rezerve 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örevler serbest bırakılır veya iade edilir.

İstek

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

Yanıt

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Notlar

Uzak görüntü getirme hataları, oluşturma başlamadan önce giriş hataları olarak döndürülür. Erişilemeyen URL'ler, zaman aşımları, 403/404 yanıtları, özel/dahili ana bilgisayarlar, URL içindeki kimlik bilgileri veya parçalar, görüntü olmayan içerik, desteklenmeyen formatlar ve boyut sınırı ihlalleri 400 veya 413 hatası döndürür ve image_url / image_urls[n] girişini tanımlar. Özel veya başlık korumalı varlıklar için multipart image dosyalarını doğrudan yükleyin veya /v1/files referansları oluşturun.

Hy Image 3.5 Preview, metinden 1024 piksellik kare görüntüler oluşturur ve yazılı talimatları kullanarak referans görüntüleri düzenler. Görseller tasarlamak ve bir kompozisyonu iyileştirmek için kullanışlıdır.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

Yetkilendirme

BearerAuth
AuthorizationBearer <token>

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

X-TokenLab-Delivery-Policy?string

İ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 gövdesi

Yanıt

application/json

application/json

application/json

application/json

application/json

application/json

Görüntü Oluştur

Önceki

Görsel Varyasyonu Oluştur

Sonraki