image_generate membuat dan mengedit gambar melalui penyedia yang telah
Anda konfigurasi. Dalam sesi obrolan, alat ini berjalan secara asinkron: OpenClaw mencatat
tugas latar belakang, segera mengembalikan id tugas, dan membangunkan agen ketika
penyedia selesai. Agen penyelesaian mengikuti mode balasan terlihat normal
sesi: pengiriman balasan akhir otomatis jika dikonfigurasi, atau
message(action="send") jika sesi mengharuskan alat pesan. Jika sesi
peminta tidak aktif atau upaya membangunkan sesi aktifnya gagal, OpenClaw mengirim
fallback langsung idempoten dengan gambar yang dihasilkan agar hasilnya tidak
hilang.
Alat ini hanya muncul jika setidaknya satu penyedia pembuatan gambar
tersedia. Jika
image_generate tidak terlihat dalam alat agen Anda,
konfigurasikan agents.defaults.imageGenerationModel, siapkan kunci API penyedia,
atau masuk dengan OAuth OpenAI ChatGPT/Codex.Mulai cepat
1
Konfigurasikan autentikasi
Tetapkan kunci API untuk setidaknya satu penyedia (misalnya
OPENAI_API_KEY,
GEMINI_API_KEY, OPENROUTER_API_KEY) atau masuk dengan OAuth OpenAI Codex.2
Pilih model default (opsional)
openai/gpt-image-2 yang sama. Ketika
profil OAuth openai dikonfigurasi, OpenClaw merutekan permintaan gambar
melalui profil OAuth tersebut alih-alih terlebih dahulu mencoba OPENAI_API_KEY.
Konfigurasi models.providers.openai eksplisit (kunci API, URL dasar khusus/Azure)
mengaktifkan kembali rute langsung OpenAI Images API.3
Minta agen
“Buat gambar maskot robot yang ramah.”Agen memanggil
image_generate secara otomatis. Tidak diperlukan pencantuman
alat dalam daftar yang diizinkan—alat ini diaktifkan secara default saat penyedia tersedia. Alat
mengembalikan id tugas latar belakang, lalu agen penyelesaian mengirim
lampiran yang dihasilkan melalui alat message setelah siap.Rute umum
Alat yang sama menangani teks-ke-gambar dan pengeditan gambar referensi. Gunakan
image
untuk satu referensi atau images untuk beberapa referensi. Untuk model Krea 2 di fal,
referensi tersebut dikirim sebagai referensi gaya, bukan sebagai masukan pengeditan.
Petunjuk keluaran yang didukung penyedia seperti quality, outputFormat, dan
background diteruskan jika tersedia dan dilaporkan sebagai diabaikan ketika
penyedia tidak menyatakan dukungan. Dukungan latar belakang transparan bawaan
khusus untuk OpenAI; penyedia lain mungkin tetap mempertahankan alfa PNG jika
backend mereka menghasilkannya.
Penyedia yang didukung
Gunakan
action: "list" untuk memeriksa penyedia dan model yang tersedia saat runtime:
action: "status" untuk memeriksa tugas pembuatan gambar aktif bagi
sesi saat ini:
Kemampuan penyedia
Parameter alat
string
wajib
Prompt pembuatan gambar. Wajib untuk
action: "generate"."generate" | "status" | "list"
default:"generate"
Gunakan
"status" untuk memeriksa tugas sesi aktif atau "list" untuk memeriksa
penyedia dan model yang tersedia saat runtime.string
Penggantian penyedia/model (misalnya
openai/gpt-image-2). Gunakan
openai/gpt-image-1.5 untuk latar belakang OpenAI transparan.string
Path atau URL satu gambar referensi untuk mode pengeditan.
string[]
Beberapa gambar referensi untuk mode pengeditan atau model referensi gaya (hingga 14
melalui alat bersama; batas khusus penyedia tetap berlaku).
string
Petunjuk ukuran:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.string
Rasio aspek:
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. Penyedia memvalidasi subset khusus model mereka."1K" | "2K" | "4K"
Petunjuk resolusi.
"low" | "medium" | "high" | "auto"
Petunjuk kualitas jika penyedia mendukungnya.
"png" | "jpeg" | "webp"
Petunjuk format keluaran jika penyedia mendukungnya.
"transparent" | "opaque" | "auto"
Petunjuk latar belakang jika penyedia mendukungnya. Gunakan
transparent dengan
outputFormat: "png" atau "webp" untuk penyedia yang mendukung transparansi.number
Jumlah gambar yang akan dibuat (1-4).
number
Batas waktu opsional permintaan penyedia dalam milidetik. Ketika Codex memanggil
image_generate melalui alat dinamis, nilai per panggilan ini tetap menggantikan
default yang dikonfigurasi dan dibatasi maksimum 600000 ms.string
Petunjuk nama file keluaran.
object
Petunjuk khusus OpenAI:
background, moderation, outputCompression, dan user."raw" | "low" | "medium" | "high"
Kontrol kreativitas fal Krea 2. Defaultnya adalah
medium.Tidak semua penyedia mendukung semua parameter. Ketika penyedia fallback mendukung
opsi geometri terdekat alih-alih opsi persis yang diminta, OpenClaw memetakan ulang ke
ukuran, rasio aspek, atau resolusi terdekat yang didukung sebelum pengiriman.
Petunjuk keluaran yang tidak didukung dibuang untuk penyedia yang tidak menyatakan
dukungan dan dilaporkan dalam hasil alat. Hasil alat melaporkan pengaturan yang
diterapkan;
details.normalization mencatat setiap penerjemahan dari nilai yang diminta
ke nilai yang diterapkan.Konfigurasi
Pemilihan model
Urutan pemilihan penyedia
OpenClaw mencoba penyedia dalam urutan berikut:- Parameter
modeldari pemanggilan alat (jika agen menentukannya). imageGenerationModel.primarydari konfigurasi.imageGenerationModel.fallbackssecara berurutan.- Deteksi otomatis - hanya default penyedia yang didukung autentikasi:
- penyedia default saat ini terlebih dahulu;
- penyedia pembuatan gambar terdaftar lainnya berdasarkan urutan ID penyedia.
Penimpaan model per pemanggilan bersifat persis
Penimpaan model per pemanggilan bersifat persis
Penimpaan
model per pemanggilan hanya mencoba penyedia/model tersebut dan tidak melanjutkan ke penyedia utama/cadangan yang dikonfigurasi maupun penyedia yang terdeteksi otomatis.Deteksi otomatis mempertimbangkan autentikasi
Deteksi otomatis mempertimbangkan autentikasi
Default suatu penyedia hanya dimasukkan ke daftar kandidat ketika OpenClaw benar-benar dapat mengautentikasi penyedia tersebut. Atur
agents.defaults.mediaGenerationAutoProviderFallback: false agar hanya menggunakan entri
model, primary, dan fallbacks yang eksplisit.Batas waktu
Batas waktu
Atur
agents.defaults.imageGenerationModel.timeoutMs untuk backend gambar yang lambat. Parameter alat timeoutMs per pemanggilan menimpa default yang dikonfigurasi, dan default yang dikonfigurasi menimpa default penyedia yang ditentukan oleh plugin. Penyedia gambar yang dihosting Google dan OpenRouter menggunakan default 180 detik; pembuatan gambar Microsoft Foundry MAI, xAI, dan Azure OpenAI menggunakan 600 detik. Pemanggilan alat dinamis Codex menggunakan default jembatan image_generate selama 120 detik dan mematuhi anggaran batas waktu yang sama ketika dikonfigurasi, dibatasi oleh batas maksimum jembatan alat dinamis OpenClaw sebesar 600000 ms.Periksa saat runtime
Periksa saat runtime
Gunakan
action: "list" untuk memeriksa penyedia yang saat ini terdaftar, model defaultnya, dan petunjuk variabel lingkungan autentikasi.Pengeditan gambar
OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI, dan xAI mendukung pengeditan gambar referensi. Model Krea 2 di fal menggunakan kolomimage / images yang sama sebagai referensi gaya, bukan sebagai input pengeditan. Berikan jalur atau URL gambar referensi:
images; xAI mendukung hingga 3. fal mendukung 1 gambar referensi untuk Flux image-to-image, hingga 10 untuk pengeditan GPT Image 2, hingga 10 referensi gaya untuk Krea 2, dan hingga 14 untuk pengeditan Nano Banana 2. Microsoft Foundry, MiniMax, dan ComfyUI mendukung 1.
Pembahasan mendalam penyedia
OpenAI gpt-image-2 (dan gpt-image-1.5)
OpenAI gpt-image-2 (dan gpt-image-1.5)
Pembuatan gambar OpenAI menggunakan
openai/gpt-image-2 secara default. Jika profil OAuth openai dikonfigurasi, OpenClaw menggunakan kembali profil OAuth yang sama dengan yang digunakan oleh model percakapan langganan Codex dan mengirim permintaan gambar melalui backend Codex Responses. URL dasar Codex lama seperti https://chatgpt.com/backend-api dikanonisasi menjadi https://chatgpt.com/backend-api/codex untuk permintaan gambar. OpenClaw tidak secara diam-diam beralih ke OPENAI_API_KEY untuk permintaan tersebut - untuk memaksakan perutean langsung melalui OpenAI Images API, konfigurasikan models.providers.openai secara eksplisit dengan kunci API, URL dasar khusus, atau endpoint Azure.Model openai/gpt-image-1.5, openai/gpt-image-1, dan openai/gpt-image-1-mini masih dapat dipilih secara eksplisit. Gunakan gpt-image-1.5 untuk keluaran PNG/WebP dengan latar belakang transparan; API gpt-image-2 saat ini menolak background: "transparent".gpt-image-2 mendukung pembuatan teks-ke-gambar dan pengeditan gambar referensi melalui alat image_generate yang sama. OpenClaw meneruskan prompt, count, size, quality, outputFormat, dan gambar referensi ke OpenAI. OpenAI tidak menerima aspectRatio atau resolution secara langsung; jika memungkinkan, OpenClaw memetakannya ke size yang didukung. Jika tidak, alat melaporkannya sebagai penimpaan yang diabaikan.Opsi khusus OpenAI berada di bawah objek openai:openai.background menerima transparent, opaque, atau auto; keluaran transparan memerlukan outputFormat png atau webp serta model gambar OpenAI yang mendukung transparansi. OpenClaw merutekan permintaan latar belakang transparan gpt-image-2 default ke gpt-image-1.5. openai.outputCompression berlaku untuk keluaran JPEG/WebP dan diabaikan untuk keluaran PNG.Petunjuk tingkat atas background bersifat netral terhadap penyedia dan saat ini dipetakan ke kolom permintaan OpenAI background yang sama ketika penyedia OpenAI dipilih. Penyedia yang tidak menyatakan dukungan latar belakang mengembalikannya dalam ignoredOverrides, alih-alih menerima parameter yang tidak didukung.Untuk merutekan pembuatan gambar OpenAI melalui deployment Azure OpenAI, bukan api.openai.com, lihat endpoint Azure OpenAI.Model gambar Microsoft Foundry MAI
Model gambar Microsoft Foundry MAI
Pembuatan gambar Microsoft Foundry menggunakan nama deployment gambar MAI yang telah diterapkan di bawah prefiks penyedia Penyedia menggunakan API MAI milik Microsoft Foundry, bukan OpenAI Images API:
microsoft-foundry/. Tidak ada model default tingkat penyedia karena API MAI mengharapkan nama deployment Anda di kolom model:- Endpoint pembuatan:
/mai/v1/images/generations - Endpoint pengeditan:
/mai/v1/images/edits - Autentikasi:
AZURE_OPENAI_API_KEY/ kunci API penyedia, atau Entra ID melaluiaz login - Keluaran: satu gambar PNG
- Ukuran: default
1024x1024; lebar dan tinggi masing-masing harus sedikitnya 768 px, dan jumlah piksel keseluruhan tidak boleh melebihi 1,048,576 - Pengeditan: satu gambar referensi PNG atau JPEG, hanya didukung oleh deployment
MAI-Image-2.5-FlashdanMAI-Image-2.5
MAI-Image-2.5-Flash atau MAI-Image-2.5.Model gambar MAI saat ini adalah MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e, dan MAI-Image-2. Lihat plugin Microsoft Foundry untuk penyiapan dan perilaku model percakapan.Model gambar OpenRouter
Model gambar OpenRouter
Pembuatan gambar OpenRouter menggunakan OpenClaw meneruskan
OPENROUTER_API_KEY yang sama dan dirutekan melalui API gambar penyelesaian percakapan OpenRouter. Pilih model gambar OpenRouter dengan prefiks openrouter/:prompt, count, gambar referensi, serta petunjuk aspectRatio / resolution yang kompatibel dengan Gemini ke OpenRouter. Pintasan model gambar OpenRouter bawaan saat ini mencakup google/gemini-3.1-flash-image, google/gemini-3-pro-image, dan openai/gpt-5.4-image-2. Gunakan action: "list" untuk melihat apa yang diekspos oleh plugin terkonfigurasi Anda.fal Krea 2
fal Krea 2
Model Krea 2 di fal menggunakan skema Krea native milik fal, bukan skema umum Krea 2 saat ini mengembalikan satu gambar per permintaan. Utamakan
image_size yang digunakan oleh Flux. OpenClaw mengirim:aspect_ratiountuk petunjuk rasio aspekcreativity, dengan defaultmediumimage_style_referencesketikaimageatauimagesdiberikan
aspectRatio untuk Krea; OpenClaw memetakan size ke rasio aspek Krea terdekat yang didukung dan menolak resolution untuk Krea, alih-alih mengabaikannya. Gunakan fal.creativity ketika Anda menginginkan tingkat kreativitas native Krea:Autentikasi ganda MiniMax
Autentikasi ganda MiniMax
Pembuatan gambar MiniMax tersedia melalui kedua jalur autentikasi MiniMax bawaan:
minimax/image-01untuk penyiapan dengan kunci APIminimax-portal/image-01untuk penyiapan dengan OAuth
xAI grok-imagine-image
xAI grok-imagine-image
Penyedia xAI bawaan menggunakan
/v1/images/generations untuk permintaan hanya dengan perintah dan /v1/images/edits ketika terdapat image atau images.- Model:
xai/grok-imagine-image,xai/grok-imagine-image-quality - Jumlah: hingga 4
- Referensi: satu
imageatau hingga tigaimages - Rasio aspek:
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 - Resolusi:
1K,2K - Keluaran: dikembalikan sebagai lampiran gambar yang dikelola OpenClaw
quality, mask, user native xAI, maupun rasio aspek auto hingga kontrol tersebut tersedia dalam kontrak lintas penyedia bersama image_generate.Contoh
- Buat (lanskap 4K)
- Buat (PNG transparan)
- Buat (kualitas rendah OpenAI)
- Hasilkan (dua persegi)
- Edit (satu referensi)
- Edit (beberapa referensi)
- Referensi gaya Krea
--output-format, --background, --quality, dan
--openai-moderation yang sama tersedia pada openclaw infer image edit;
--openai-background tetap menjadi alias khusus OpenAI. Saat ini, penyedia
bawaan selain OpenAI tidak mendeklarasikan kontrol latar belakang secara
eksplisit, sehingga background: "transparent" dilaporkan sebagai diabaikan untuk
penyedia tersebut.
Terkait
- Ikhtisar alat - semua alat agen yang tersedia
- ComfyUI - penyiapan alur kerja ComfyUI lokal dan Comfy Cloud
- fal - penyiapan penyedia gambar dan video fal
- Google (Gemini) - penyiapan penyedia gambar Gemini
- Plugin Microsoft Foundry - penyiapan obrolan Microsoft Foundry dan gambar MAI
- MiniMax - penyiapan penyedia gambar MiniMax
- OpenAI - penyiapan penyedia OpenAI Images
- Vydra - penyiapan gambar, video, dan ucapan Vydra
- xAI - penyiapan gambar, video, pencarian, eksekusi kode, dan TTS Grok
- Referensi konfigurasi - konfigurasi
imageGenerationModel - Model - konfigurasi model dan failover