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

OAuth ChatGPT/Codex menggunakan referensi model 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.
Untuk endpoint LAN yang kompatibel dengan OpenAI seperti LocalAI, pertahankan models.providers.openai.baseUrl khusus dan berikan persetujuan eksplisit dengan browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Endpoint gambar privat dan internal tetap diblokir secara default.

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:
Gunakan 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:
  1. Parameter model dari pemanggilan alat (jika agen menentukannya).
  2. imageGenerationModel.primary dari konfigurasi.
  3. imageGenerationModel.fallbacks secara berurutan.
  4. Deteksi otomatis - hanya default penyedia yang didukung autentikasi:
    • penyedia default saat ini terlebih dahulu;
    • penyedia pembuatan gambar terdaftar lainnya berdasarkan urutan ID penyedia.
Jika suatu penyedia gagal (kesalahan autentikasi, batas laju, dan sebagainya), kandidat terkonfigurasi berikutnya akan dicoba secara otomatis. Jika semuanya gagal, kesalahan tersebut menyertakan detail dari setiap percobaan.
Penimpaan model per pemanggilan hanya mencoba penyedia/model tersebut dan tidak melanjutkan ke penyedia utama/cadangan yang dikonfigurasi maupun penyedia yang terdeteksi otomatis.
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.
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.
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 kolom image / images yang sama sebagai referensi gaya, bukan sebagai input pengeditan. Berikan jalur atau URL gambar referensi:
OpenAI, OpenRouter, dan Google mendukung hingga 5 gambar referensi melalui parameter 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

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.
Pembuatan gambar Microsoft Foundry menggunakan nama deployment gambar MAI yang telah diterapkan di bawah prefiks penyedia microsoft-foundry/. Tidak ada model default tingkat penyedia karena API MAI mengharapkan nama deployment Anda di kolom model:
Penyedia menggunakan API MAI milik Microsoft Foundry, bukan OpenAI Images API:
  • Endpoint pembuatan: /mai/v1/images/generations
  • Endpoint pengeditan: /mai/v1/images/edits
  • Autentikasi: AZURE_OPENAI_API_KEY / kunci API penyedia, atau Entra ID melalui az 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-Flash dan MAI-Image-2.5
Pembuatan hanya dengan perintah dapat menggunakan nama deployment khusus hanya dengan endpoint Foundry yang dikonfigurasi. Pengeditan dengan nama deployment khusus memerlukan metadata orientasi awal/model agar OpenClaw dapat memverifikasi bahwa deployment tersebut didukung oleh 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.
Pembuatan gambar OpenRouter menggunakan OPENROUTER_API_KEY yang sama dan dirutekan melalui API gambar penyelesaian percakapan OpenRouter. Pilih model gambar OpenRouter dengan prefiks openrouter/:
OpenClaw meneruskan 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.
Model Krea 2 di fal menggunakan skema Krea native milik fal, bukan skema umum image_size yang digunakan oleh Flux. OpenClaw mengirim:
  • aspect_ratio untuk petunjuk rasio aspek
  • creativity, dengan default medium
  • image_style_references ketika image atau images diberikan
Pilih Krea 2 Medium untuk ilustrasi ekspresif yang lebih cepat dan Krea 2 Large untuk tampilan fotorealistis dan bertekstur yang lebih lambat tetapi lebih mendetail:
Krea 2 saat ini mengembalikan satu gambar per permintaan. Utamakan 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:
Pembuatan gambar MiniMax tersedia melalui kedua jalur autentikasi MiniMax bawaan:
  • minimax/image-01 untuk penyiapan dengan kunci API
  • minimax-portal/image-01 untuk penyiapan dengan OAuth
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 image atau hingga tiga images
  • 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
OpenClaw sengaja tidak mengekspos quality, mask, user native xAI, maupun rasio aspek auto hingga kontrol tersebut tersedia dalam kontrak lintas penyedia bersama image_generate.

Contoh

Flag --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