Görseller
Görseli Düzenle
Bir prompt ve kaynak görsel vererek bir görseli düzenleyin
Genel Bakış
Orijinal bir görsel ve bir prompt verildiğinde düzenlenmiş veya genişletilmiş bir görsel oluşturur.
Bu endpoint her ikisini de destekler:
- aşağıda belgelenen OpenAI uyumlu
multipart/form-datayükleme akışı - desteklenen image-to-image aileleri için
image_url,image_urlsveya resmiimagesreferansları sağlayan JSON istekleri
gpt-image-2 burada desteklenmektedir. Multipart image yüklemelerini, JSON image_url / image_urls ve 16 adede kadar kaynak görsel içeren resmi images[] referanslarını (image_url veya file_id) kabul eder. file_id değerlerini önce /v1/files üzerinden oluşturun. Önce bir görev döndürmek için async: true olarak ayarlayın; gpt-image-2 ve FLUX düzenleme modelleri gibi desteklenen parametreleri arasında async listeleyen her model 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, auto veya opaque kabul eder; transparent desteklenmez. Çoklu görsel veya yüksek gecikmeli düzenlemeler için async: true tercih edin ve döndürülen görevi yoklayın.
Nano Banana referans görsel istekleri (nano-banana-2, nano-banana-2.1, nano-banana-2-lite ve nano-banana-pro), bu /v1/images/edits endpoint'inde 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örsel 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örsel düzenleme için bu endpoint'i kullanır. Bunların image-to-image istekleri operation: "image-to-image" ile /v1/images/generations kullanır.
xAI Grok Imagine görsel düzenleme modelleri sınırlı sayıda kaynak görsel kabul eder: grok-imagine-image-2.0 en fazla 5 ve grok-imagine-image en fazla 3 kabul eder. Modelin kabul ettiğinden daha fazla kaynak görsel içeren istekler 400 too_many_images ile girdi doğrulamasından geçemez. Bunların image-to-image istekleri de bu endpoint'i kullanır.
Her modelin detayları (GET /v1/models/{model}, bkz. Modeli Al), tokenlab.request_format_summary.request_endpoint_by_operation içinde her işlem için endpoint'i ve tokenlab.request_format_details.operation_constraints içinde kabul edilen alanları ve sınırları belirtir. Yanlış endpoint'e gönderilen bir işlem 400 unsupported_endpoint döndürür.
input_fidelity, gpt-image-2 için mevcut TokenLab desteklenen alanlarını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örsel istekleri nihai görseli satır içi (inline) olarak döndürür ve üretimin tamamlanmasını 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} adresini yoklayın.
Uzak görsel URL'leri: multipart girdi gerektiğinde, TokenLab JSON image_url, image_urls veya images[].image_url alanlarını getirir ve baytları multipart image parçaları olarak gönderir. URL'ler genel (public) http/https olmalı, gömülü kimlik bilgileri veya parçalar içermemeli ve localhost, özel (private) veya ayrılmış IP aralıklarına çözümlenmemelidir; her yeniden yönlendirme tekrar kontrol edilir. Getirilen yük gerçek bir PNG, JPEG veya WebP görseli olmalıdır. Sınırlar görsel başına 50 MiB, tek bir istekte URL ile getirilen görseller için toplam 200 MiB, 30s getirme zaman aşımı ve en fazla 3 yeniden yönlendirmedir.
JSON istekleri için image_url, image_urls veya images alanlarından tam olarak birini sağlayın. Her images[] nesnesi tam olarak image_url veya file_id alanlarından birini içermelidir. 200 MiB toplam sınır tüm kaynak görselleri ve maskeyi içerir.
Multipart kaynak görseller. Birden fazla GPT Image kaynağı sağlamak için image alanını tekrarlayın. Dosyalar PNG, JPEG veya WebP olmalı, en fazla 16 kaynak görsel ve her biri en fazla 50 MiB olmalıdır. xAI Grok Imagine düzenleme modelleri aynı girdi alanlarını kullanır ancak kaynak görselleri sınırlar: grok-imagine-image-2.0 için en fazla 5 ve diğer xAI düzenleme modelleri için en fazla 3.
İstenen düzenlemenin metin açıklaması, en fazla 32.000 karakter. Detaylarında prompt listeleyen her model için zorunludur. stability-upscale-fast gibi bir prompt içermeyen araçlar, prompt olmadan çağrılır.
Tamamen şeffaf alanlarının görselin neresinin düzenlenmesi gerektiğini belirttiği ek bir görsel. Geçerli bir PNG dosyası olmalı, 50 MiB'den küçük olmalı ve image ile aynı boyutlara sahip olmalıdır.
JSON istekleri için mask, tam olarak image_url veya file_id alanlarından birini içeren bir nesne de olabilir; file_id değerleri /v1/files üzerinden gelmeli ve aynı görsel düzenleme yapılandırmasına bağlı kalmalıdır.
Görsel 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 güncel bir başka görsel düzenleme modelini kullanın.
1Üretilecek görsel sayısı (modele bağlı olarak 1-10).
Üretilen görselin boyutu. gpt-image-2 için auto veya WIDTHxHEIGHT kullanın; boyutlar 16'nın katları olmalı, en uzun kenar en fazla 3840px, uzun/kısa kenar 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ı boyutunu veya bir çözünürlük katmanını (tier) kabul eder: 1K, 2K veya 4K. TokenLab bir katmanı resolution olarak gönderir. Modelin desteklemediği bir katman veya resolution değerinden farklı bir katman, invalid_image_size_contract koduyla 400 döndürür. Önerilen biçim, resolution ile birlikte aspect_ratio kullanılmasıdır.
Görsellerin nasıl döndürüleceği: url veya b64_json.
- Belirtilmediğinde: model görsel baytlarını döndürdüğünde, her görsel
data[].b64_jsoniçinde yer alır ve TokenLab depoladıysadata[].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.
falseNihai görsel hazır olmadan önce bir görev döndürmek için true olarak ayarlayın. Yalnızca desteklenen parametreleri arasında async listeleyen modeller bunu kabul eder, örneğin gpt-image-2; diğer modeller için istek 400 unsupported_async_mode döndürür. Tamamlanan asenkron düzenlemeler, istenen response_format değerine bakılmaksızın URL döndürür; b64_json gerektiğinde senkron istekleri kullanın.
Kötüye kullanım izleme amacıyla son kullanıcınızı temsil eden benzersiz bir tanımlayıcı.
Yanıt
Görsellerin oluşturulduğu anın Unix zaman damgası.
Üretilen görseller dizisi.
Her nesne şunları içerir:
url(string): Düzenlenen görselin 30 gün boyunca geçerli olan TokenLab medya sonucu URL'si.response_formatb64_jsonolduğunda mevcut değildir.response_formatbelirtilmediğinde, TokenLab görseli depolayamadıysa eksik olur.b64_json(string): Base64 görsel verisi.response_formatb64_jsonolduğunda veya belirtilmediğinde ve model görsel baytları döndürdüğünde mevcuttur.
Uygun olduğunda, gpt-image-2 gibi token fiyatlandırmalı modeller için token sayıları (input_tokens, output_tokens, total_tokens ve bunların detayları).
Asenkron Görev Yanıtı
İstekte düzenlenen görseli beklemek yerine bir görev oluşturmak için destekleyen bir modelde 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ö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ı rezerve edebilir. Tamamlanan görevler fiili kullanıma göre faturalandırılır ve başarısız olan veya zaman aşımına uğrayan görevlerin provizyonu kaldırı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
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Notlar
Uzak görsel getirme hataları, üretim başlamadan önce girdi hataları olarak döndürülür. Ulaşılamayan URL'ler, zaman aşımları, 403/404 yanıtları, özel/dahili ana makineler, URL'deki kimlik bilgileri veya parçalar, görsel olmayan içerik, desteklenmeyen formatlar ve boyut sınırı ihlalleri 400 veya 413 döndürür ve image_url / image_urls[n] girdisini tanımlar. Hata kodu invalid_image_url, unsupported_image_content_type, too_many_images veya 413 ile birlikte image_too_large ya da image_input_too_large şeklindedir. Özel veya başlıkla korunan varlıklar için multipart image dosyalarını doğrudan yükleyin veya /v1/files referansları oluşturun.
Bir zaman aşımından sonra isteği güvenle yeniden denemek için bir Idempotency-Key başlığı gönderin; bkz. Bir idempotency key ile güvenle yeniden deneyin.
Hy Image 3.5 Preview, yazılı bir talimattan referans görseli düzenler. Yalnızca 1024x1024 size ve 1 n değerini alı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 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
application/json