image_generate aracı, yapılandırdığınız sağlayıcılar aracılığıyla görseller oluşturur ve düzenler.
Sohbet oturumlarında eşzamansız çalışır: OpenClaw bir arka plan görevi
kaydeder, görev kimliğini hemen döndürür ve sağlayıcı işlemi tamamladığında
ajanı uyandırır. Tamamlama ajanı, oturumun normal görünür yanıt modunu izler:
yapılandırıldığında nihai yanıtı otomatik olarak teslim eder veya oturum
mesaj aracını gerektiriyorsa message(action="send") kullanır. İstekte bulunan
oturum etkin değilse veya etkin uyandırma işlemi başarısız olursa OpenClaw,
sonucun kaybolmaması için oluşturulan görsellerle birlikte idempotent bir
doğrudan geri dönüş gönderir.
Araç yalnızca en az bir görsel oluşturma sağlayıcısı kullanılabilir olduğunda
görünür. Ajanınızın araçlarında
image_generate öğesini görmüyorsanız
agents.defaults.mediaModels.image yapılandırın, bir sağlayıcı API anahtarı ayarlayın
veya OpenAI ChatGPT/Codex OAuth ile oturum açın.Hızlı başlangıç
1
Kimlik doğrulamayı yapılandırın
En az bir sağlayıcı için bir API anahtarı ayarlayın (örneğin
OPENAI_API_KEY,
GEMINI_API_KEY, OPENROUTER_API_KEY) veya OpenAI Codex OAuth ile oturum açın.2
Varsayılan model seçin (isteğe bağlı)
openai/gpt-image-2 model referansını kullanır. Bir
openai OAuth profili yapılandırıldığında OpenClaw, önce
OPENAI_API_KEY öğesini denemek yerine görsel isteklerini bu OAuth profili
üzerinden yönlendirir. Açık models.providers.openai yapılandırması (API anahtarı,
özel/Azure temel URL’si), doğrudan OpenAI Images API yolunu yeniden etkinleştirir.3
Ajandan isteyin
“Sevimli bir robot maskotun görselini oluştur.”Ajan
image_generate öğesini otomatik olarak çağırır. Araç izin listesine
ekleme gerekmez; bir sağlayıcı kullanılabilir olduğunda varsayılan olarak
etkindir. Araç bir arka plan görevi kimliği döndürür, ardından tamamlama ajanı
hazır olduğunda oluşturulan eki message aracı üzerinden gönderir.Yaygın yollar
Aynı araç, metinden görsel oluşturmayı ve referans görsel düzenlemeyi destekler.
Tek bir referans için
image, birden fazla referans için
images kullanın. fal üzerindeki Krea 2 modellerinde bu referanslar,
düzenleme girdileri yerine stil referansları olarak gönderilir.
quality, outputFormat ve background gibi sağlayıcının
desteklediği çıktı ipuçları, kullanılabilir olduğunda iletilir; sağlayıcı destek
bildirmediğinde ise yok sayılmış olarak raporlanır. Paketlenmiş şeffaf arka plan
desteği OpenAI’a özgüdür; diğer sağlayıcılar, arka uçları bu şekilde çıktı
veriyorsa PNG alfa kanalını koruyabilir.
Desteklenen sağlayıcılar
Çalışma zamanında kullanılabilir sağlayıcıları ve modelleri incelemek için
action: "list" kullanın:
action: "status" kullanın:
Sağlayıcı yetenekleri
Araç parametreleri
string
gerekli
Görsel oluşturma istemi.
action: "generate" için gereklidir."generate" | "status" | "list"
varsayılan:"generate"
Etkin oturum görevini incelemek için
"status", çalışma zamanında
kullanılabilir sağlayıcıları ve modelleri incelemek için "list" kullanın.string
Sağlayıcı/model geçersiz kılma değeri (ör.
openai/gpt-image-2). Şeffaf OpenAI
arka planları için openai/gpt-image-1.5 kullanın.string
Düzenleme modu için tek bir referans görsel yolu veya URL’si.
string[]
Düzenleme modu veya stil referansı modelleri için birden fazla referans görsel
(paylaşılan araç üzerinden en fazla 14; sağlayıcıya özgü sınırlar geçerliliğini korur).
string
Boyut ipucu:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.string
En-boy oranı:
1:1, 2:1, 20:9, 19.5:9, 2:3, 3:2, 2.35:1, 3:4,
4:3, 4:5, 5:4, 9:16, 9:19.5, 9:20, 16:9, 21:9, 1:2, 4:1,
1:4, 8:1, 1:8. Sağlayıcılar kendi modele özgü alt kümelerini doğrular."1K" | "2K" | "4K"
Çözünürlük ipucu.
"low" | "medium" | "high" | "auto"
Sağlayıcı desteklediğinde kalite ipucu.
"png" | "jpeg" | "webp"
Sağlayıcı desteklediğinde çıktı biçimi ipucu.
"transparent" | "opaque" | "auto"
Sağlayıcı desteklediğinde arka plan ipucu. Şeffaflığı destekleyen sağlayıcılar
için
transparent ile outputFormat: "png" veya "webp" kullanın.number
Oluşturulacak görsel sayısı (1-4).
number
Milisaniye cinsinden isteğe bağlı sağlayıcı isteği zaman aşımı. Codex,
dinamik araçlar üzerinden
image_generate çağırdığında bu çağrı başına
değer yine yapılandırılmış varsayılanı geçersiz kılar ve 600000 ms ile sınırlandırılır.string
Çıktı dosya adı ipucu.
object
Yalnızca OpenAI’a özgü ipuçları:
background, moderation, outputCompression ve user."raw" | "low" | "medium" | "high"
fal Krea 2 yaratıcılık denetimi. Varsayılan değer
medium.Tüm sağlayıcılar tüm parametreleri desteklemez. Bir geri dönüş sağlayıcısı,
tam olarak istenen seçenek yerine yakın bir geometri seçeneğini desteklediğinde
OpenClaw, göndermeden önce en yakın desteklenen boyuta, en-boy oranına veya
çözünürlüğe yeniden eşler. Desteklenmeyen çıktı ipuçları, destek bildirmeyen
sağlayıcılar için kaldırılır ve araç sonucunda raporlanır. Araç sonuçları
uygulanan ayarları bildirir;
details.normalization, istenen değerden uygulanan
değere yapılan dönüşümleri içerir.Yapılandırma
Model seçimi
Sağlayıcı seçim sırası
OpenClaw sağlayıcıları şu sırayla dener:- Araç çağrısındaki
modelparametresi (agent bir tane belirtirse). - Yapılandırmadaki
imageGenerationModel.primary. - Sırasıyla
imageGenerationModel.fallbacks. - Otomatik algılama - yalnızca kimlik doğrulama destekli sağlayıcı varsayılanları:
- önce geçerli varsayılan sağlayıcı;
- ardından kalan kayıtlı görüntü oluşturma sağlayıcıları, sağlayıcı kimliği sırasıyla.
Çağrı başına model geçersiz kılmaları kesindir
Çağrı başına model geçersiz kılmaları kesindir
Çağrı başına
model geçersiz kılması yalnızca ilgili sağlayıcıyı/modeli dener ve
yapılandırılmış birincil/yedek ya da otomatik algılanan sağlayıcılarla devam etmez.Otomatik algılama kimlik doğrulamanın farkındadır
Otomatik algılama kimlik doğrulamanın farkındadır
Bir sağlayıcı varsayılanı, yalnızca OpenClaw ilgili sağlayıcıda gerçekten
kimlik doğrulaması yapabiliyorsa aday listesine girer. Kimliği doğrulanmış
sağlayıcılar arasında otomatik yedekleme her zaman etkindir; çağrı başına
model belirleyici olmaya devam eder.Zaman aşımları
Zaman aşımları
Yavaş görüntü arka uçları için
agents.defaults.mediaModels.image.timeoutMs ayarlayın.
Çağrı başına timeoutMs araç parametresi, yapılandırılmış
varsayılanı geçersiz kılar; yapılandırılmış varsayılanlar da plugin tarafından yazılmış sağlayıcı
varsayılanlarını geçersiz kılar. Google ve OpenRouter tarafından barındırılan görüntü sağlayıcıları 180 saniyelik
varsayılanlar kullanır; Microsoft Foundry MAI, xAI ve Azure OpenAI görüntü oluşturma ise
600 saniye kullanır. Codex dinamik araç çağrıları 120 saniyelik image_generate
köprü varsayılanını kullanır ve yapılandırıldığında aynı zaman aşımı bütçesine uyar; bu süre
OpenClaw’ın 600000 ms dinamik araç köprüsü üst sınırıyla sınırlıdır.Çalışma zamanında inceleme
Çalışma zamanında inceleme
Şu anda kayıtlı sağlayıcıları, bunların varsayılan modellerini
ve kimlik doğrulama ortam değişkeni ipuçlarını incelemek için
action: "list" kullanın.Görüntü düzenleme
OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI ve xAI, referans görüntülerini düzenlemeyi destekler. fal üzerindeki Krea 2 modelleri, aynıimage / images alanlarını düzenleme girdileri yerine stil referansı olarak
kullanır. Bir referans görüntüsü yolu veya URL’si iletin:
images parametresi aracılığıyla en fazla 5 referans görüntüsünü;
xAI ise en fazla 3 görüntüyü destekler. fal; Flux görüntüden görüntüye dönüştürme için 1 referans görüntüsünü,
GPT Image 2 düzenlemeleri için en fazla 10 görüntüyü, Krea 2 için en fazla 10 stil referansını
ve Nano Banana 2 düzenlemeleri için en fazla 14 görüntüyü destekler. Microsoft Foundry, MiniMax
ve ComfyUI 1 görüntüyü destekler.
Sağlayıcılara ayrıntılı bakış
OpenAI gpt-image-2 (ve gpt-image-1.5)
OpenAI gpt-image-2 (ve gpt-image-1.5)
OpenAI görüntü oluşturma varsayılan olarak
openai/gpt-image-2 kullanır. Bir
openai OAuth profili yapılandırılmışsa OpenClaw, Codex abonelik sohbet modellerinin
kullandığı aynı OAuth profilini yeniden kullanır ve görüntü isteğini
Codex Responses arka ucu üzerinden gönderir. https://chatgpt.com/backend-api gibi eski Codex temel
URL’leri, görüntü istekleri için https://chatgpt.com/backend-api/codex biçimine
standartlaştırılır. OpenClaw bu istek için sessizce
OPENAI_API_KEY seçeneğine geri dönmez; doğrudan OpenAI Images API yönlendirmesini zorlamak için
models.providers.openai öğesini bir API anahtarı, özel temel URL
veya Azure uç noktasıyla açıkça yapılandırın.openai/gpt-image-1.5, openai/gpt-image-1 ve
openai/gpt-image-1-mini modelleri yine de açıkça seçilebilir. Şeffaf arka planlı
PNG/WebP çıktısı için gpt-image-1.5 kullanın; geçerli
gpt-image-2 API’si background: "transparent" değerini reddeder.gpt-image-2, aynı image_generate aracı üzerinden hem metinden görüntü oluşturmayı hem de
referans görüntüsü düzenlemeyi destekler.
OpenClaw; prompt, count, size, quality, outputFormat
ve referans görüntülerini OpenAI’a iletir. OpenAI, aspectRatio veya
resolution değerlerini doğrudan almaz; mümkün olduğunda OpenClaw bunları
desteklenen bir size değerine eşler, aksi durumda araç bunları yok sayılan
geçersiz kılmalar olarak bildirir.OpenAI’a özgü seçenekler openai nesnesi altında bulunur:openai.background; transparent, opaque veya auto kabul eder;
şeffaf çıktılar için outputFormat değerinin png veya webp olması ve
şeffaflığı destekleyen bir OpenAI görüntü modeli gerekir. OpenClaw, varsayılan
gpt-image-2 şeffaf arka plan isteklerini gpt-image-1.5 modeline yönlendirir.
openai.outputCompression, JPEG/WebP çıktılarına uygulanır ve PNG çıktıları için
yok sayılır.Üst düzey background ipucu sağlayıcıdan bağımsızdır ve OpenAI sağlayıcısı
seçildiğinde şu anda aynı OpenAI background istek alanına eşlenir.
Arka plan desteği bildirmeyen sağlayıcılar, desteklenmeyen parametreyi almak yerine
bunu ignoredOverrides içinde döndürür.OpenAI görüntü oluşturmayı api.openai.com yerine bir Azure OpenAI dağıtımı
üzerinden yönlendirmek için
Azure OpenAI uç noktaları bölümüne bakın.Microsoft Foundry MAI görüntü modelleri
Microsoft Foundry MAI görüntü modelleri
Microsoft Foundry görüntü oluşturma, Sağlayıcı, OpenAI Images API’yi değil Microsoft Foundry’nin MAI API’sini kullanır:
microsoft-foundry/ sağlayıcı öneki altında
dağıtılmış MAI görüntü dağıtımı adlarını kullanır. MAI API, dağıtım adınızı
model alanında beklediğinden sağlayıcı düzeyinde varsayılan
model yoktur:- Oluşturma uç noktası:
/mai/v1/images/generations - Düzenleme uç noktası:
/mai/v1/images/edits - Kimlik doğrulama:
AZURE_OPENAI_API_KEY/ sağlayıcı API anahtarı veyaaz loginüzerinden Entra ID - Çıktı: bir PNG görüntüsü
- Boyut: varsayılan
1024x1024; genişlik ve yüksekliğin her biri en az 768 px olmalı, toplam piksel sayısı ise en fazla 1,048,576 olmalıdır - Düzenlemeler: yalnızca
MAI-Image-2.5-FlashveMAI-Image-2.5dağıtımları tarafından desteklenen bir PNG veya JPEG referans görüntüsü
MAI-Image-2.5-Flash veya MAI-Image-2.5 tarafından desteklendiğini doğrulayabilmesi için
ilk katılım/model meta verileri gerekir.Geçerli MAI görüntü modelleri MAI-Image-2.5-Flash, MAI-Image-2.5,
MAI-Image-2e ve MAI-Image-2 modelleridir. Kurulum
ve sohbet modeli davranışı için Microsoft Foundry plugin bölümüne bakın.OpenRouter görüntü modelleri
OpenRouter görüntü modelleri
OpenRouter görüntü oluşturma aynı OpenClaw;
OPENROUTER_API_KEY öğesini kullanır ve
OpenRouter’ın sohbet tamamlama görüntü API’si üzerinden yönlendirilir.
OpenRouter görüntü modellerini openrouter/ önekiyle seçin:prompt, count, referans görüntüleri ve
Gemini uyumlu aspectRatio / resolution ipuçlarını OpenRouter’a iletir.
Geçerli yerleşik OpenRouter görüntü modeli kısayolları arasında
google/gemini-3.1-flash-image,
google/gemini-3-pro-image ve openai/gpt-5.4-image-2 bulunur. Yapılandırılmış plugin’inizin
neleri sunduğunu görmek için action: "list" kullanın.fal Krea 2
fal Krea 2
fal üzerindeki Krea 2 modelleri, Flux tarafından kullanılan genel
Krea 2 şu anda istek başına bir görüntü döndürür. Krea için
image_size şeması yerine fal’ın yerel Krea şemasını kullanır. OpenClaw şunları gönderir:- En-boy oranı ipuçları için
aspect_ratio - Varsayılan değeri
mediumolancreativity imageveyaimagessağlandığındaimage_style_references
aspectRatio tercih edin;
OpenClaw, size değerini desteklenen en yakın Krea en-boy oranına eşler ve
kaldırmak yerine Krea için resolution değerini reddeder. Yerel bir Krea yaratıcılık düzeyi
istediğinizde fal.creativity kullanın:MiniMax çift kimlik doğrulama
MiniMax çift kimlik doğrulama
MiniMax görüntü oluşturma, paketlenmiş MiniMax
kimlik doğrulama yollarının ikisi üzerinden de kullanılabilir:
- API anahtarı kurulumları için
minimax/image-01 - OAuth kurulumları için
minimax-portal/image-01
xAI grok-imagine-image
xAI grok-imagine-image
Paketlenmiş xAI sağlayıcısı, yalnızca istem içeren istekler için
/v1/images/generations;
image veya images mevcut olduğunda ise /v1/images/edits kullanır.- Modeller:
xai/grok-imagine-image,xai/grok-imagine-image-quality - Sayı: en fazla 4
- Referanslar: bir
imageveya en fazla üçimages - En-boy oranları:
1:1,16:9,9:16,4:3,3:4,3:2,2:3,2:1,1:2,19.5:9,9:19.5,20:9,9:20 - Çözünürlükler:
1K,2K - Çıktılar: OpenClaw tarafından yönetilen görüntü ekleri olarak döndürülür
image_generate sözleşmesinde bulunana kadar
xAI’a özgü quality, mask,
user veya auto en-boy oranını kasıtlı olarak kullanıma sunmaz.Örnekler
- Oluştur (4K yatay)
- Oluştur (şeffaf PNG)
- Oluştur (OpenAI düşük kalite)
- Oluştur (iki kare)
- Düzenle (tek referans)
- Düzenle (birden fazla referans)
- Krea stil referansları
--output-format, --background, --quality ve
--openai-moderation bayrakları openclaw infer image edit üzerinde de kullanılabilir;
--openai-background, OpenAI’ye özgü bir diğer ad olarak kalır. OpenAI dışındaki
paketle gelen sağlayıcılar şu anda açık arka plan denetimi bildirmediğinden,
background: "transparent" bunlar için yok sayılmış olarak bildirilir.
İlgili
- Araçlara genel bakış - kullanılabilir tüm ajan araçları
- ComfyUI - yerel ComfyUI ve Comfy Cloud iş akışı kurulumu
- fal - fal görüntü ve video sağlayıcısı kurulumu
- Google (Gemini) - Gemini görüntü sağlayıcısı kurulumu
- Microsoft Foundry plugin’i - Microsoft Foundry sohbet ve MAI görüntü kurulumu
- MiniMax - MiniMax görüntü sağlayıcısı kurulumu
- OpenAI - OpenAI Images sağlayıcısı kurulumu
- Vydra - Vydra görüntü, video ve konuşma kurulumu
- xAI - Grok görüntü, video, arama, kod yürütme ve TTS kurulumu
- Yapılandırma referansı -
imageGenerationModelyapılandırması - Modeller - model yapılandırması ve yük devretme