Skip to main content
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ı)

ChatGPT/Codex OAuth aynı 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.
LocalAI gibi OpenAI uyumlu LAN uç noktalarında özel models.providers.openai.baseUrl değerini koruyun ve browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ile açıkça etkinleştirin. Özel ve dahili görsel uç noktaları varsayılan olarak engellenmeye devam eder.

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:
Geçerli oturumdaki etkin görsel oluşturma görevini incelemek için 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:
  1. Araç çağrısındaki model parametresi (agent bir tane belirtirse).
  2. Yapılandırmadaki imageGenerationModel.primary.
  3. Sırasıyla imageGenerationModel.fallbacks.
  4. 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.
Bir sağlayıcı başarısız olursa (kimlik doğrulama hatası, hız sınırı vb.), yapılandırılmış bir sonraki aday otomatik olarak denenir. Tümü başarısız olursa hata, her denemenin ayrıntılarını içerir.
Ç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.
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.
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.
Ş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:
OpenAI, OpenRouter ve Google, 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 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 görüntü oluşturma, 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:
Sağlayıcı, OpenAI Images API’yi değil Microsoft Foundry’nin MAI API’sini kullanır:
  • 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ı veya az 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-Flash ve MAI-Image-2.5 dağıtımları tarafından desteklenen bir PNG veya JPEG referans görüntüsü
Yalnızca istemle oluşturma, sadece Foundry uç noktası yapılandırılmışken özel bir dağıtım adı kullanabilir. Özel dağıtım adlarıyla yapılan düzenlemelerde, OpenClaw’ın dağıtımın 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ü oluşturma aynı 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:
OpenClaw; 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 üzerindeki Krea 2 modelleri, Flux tarafından kullanılan genel 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 medium olan creativity
  • image veya images sağlandığında image_style_references
Daha hızlı ve etkileyici illüstrasyonlar için Krea 2 Medium’u; daha yavaş, daha ayrıntılı, fotogerçekçi ve dokulu görünümler için Krea 2 Large’ı seçin:
Krea 2 şu anda istek başına bir görüntü döndürür. Krea için 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 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
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 image veya 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
OpenClaw, bu denetimler sağlayıcılar arası ortak 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

Aynı --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ı - imageGenerationModel yapılandırması
  • Modeller - model yapılandırması ve yük devretme