Генерування зображень

Інструмент image_generate дає змогу агенту створювати й редагувати зображення за допомогою ваших налаштованих провайдерів. У сеансах чату генерація зображень виконується асинхронно: OpenClaw записує фонове завдання, негайно повертає ідентифікатор завдання й пробуджує агента, коли провайдер завершує роботу. Агент завершення дотримується звичайного режиму видимої відповіді сеансу: автоматичне доставлення фінальної відповіді, якщо це налаштовано, або message(action="send"), коли сеанс вимагає інструмент повідомлень. Якщо сеанс запитувача неактивний або його активне пробудження не вдається, а деяких згенерованих зображень усе ще бракує у відповіді завершення, OpenClaw надсилає ідемпотентний прямий резервний варіант лише з відсутніми зображеннями.

Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите image_generate серед інструментів свого агента, налаштуйте agents.defaults.imageGenerationModel, задайте API-ключ провайдера або ввійдіть через OpenAI ChatGPT/Codex OAuth.

Швидкий старт

Налаштуйте автентифікацію

Задайте API-ключ принаймні для одного провайдера (наприклад, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) або ввійдіть через OpenAI Codex OAuth.

Виберіть стандартну модель (необов’язково)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}

ChatGPT/Codex OAuth використовує той самий референс моделі openai/gpt-image-2. Коли налаштовано OAuth-профіль openai, OpenClaw маршрутизує запити зображень через цей OAuth-профіль замість того, щоб спершу пробувати OPENAI_API_KEY. Явна конфігурація models.providers.openai (API-ключ, власний/Azure базовий URL) знову вмикає прямий маршрут OpenAI Images API.

Попросіть агента

“Згенеруй зображення дружнього робота-маскота.”Агент автоматично викликає image_generate. Список дозволених інструментів не потрібен — інструмент увімкнено за замовчуванням, коли доступний провайдер. Інструмент повертає ідентифікатор фонового завдання, а потім агент завершення надсилає згенероване вкладення через інструмент message, коли воно готове.

Для сумісних з OpenAI LAN-ендпоїнтів, таких як LocalAI, залишайте власний models.providers.openai.baseUrl і явно ввімкніть це через browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Приватні та внутрішні ендпоїнти зображень залишаються заблокованими за замовчуванням.

Поширені маршрути

Мета	Референс моделі	Автентифікація
Генерація зображень OpenAI з оплатою через API	`openai/gpt-image-2`	`OPENAI_API_KEY`
Генерація зображень OpenAI з автентифікацією передплати Codex	`openai/gpt-image-2`	OpenAI ChatGPT/Codex OAuth
OpenAI PNG/WebP із прозорим фоном	`openai/gpt-image-1.5`	`OPENAI_API_KEY` або OpenAI Codex OAuth
Генерація зображень DeepInfra	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
fal Krea 2 експресивна/стильово керована генерація	`fal/krea/v2/medium/text-to-image`	`FAL_KEY`
Генерація зображень OpenRouter	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
Генерація зображень LiteLLM	`litellm/gpt-image-2`	`LITELLM_API_KEY`
Генерація зображень Microsoft Foundry MAI	`microsoft-foundry/<deployment-name>`	`AZURE_OPENAI_API_KEY` або Entra ID
Генерація зображень Google Gemini	`google/gemini-3.1-flash-image-preview`	`GEMINI_API_KEY` або `GOOGLE_API_KEY`

Той самий інструмент image_generate обробляє перетворення тексту на зображення та редагування з референсними зображеннями. Використовуйте image для одного референсу або images для кількох референсів. Для моделей Krea 2 на fal ці референси надсилаються як референси стилю, а не як вхідні дані для редагування. Підказки виводу, які підтримує провайдер, як-от quality, outputFormat і background, передаються, коли доступні, і повідомляються як проігноровані, коли провайдер їх не підтримує. Вбудована підтримка прозорого фону специфічна для OpenAI; інші провайдери все ще можуть зберігати PNG-альфа-канал, якщо їхній бекенд його створює.

Підтримувані провайдери

Провайдер	Стандартна модель	Підтримка редагування	Автентифікація
ComfyUI	`workflow`	Так (1 зображення, налаштовано workflow)	`COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари
DeepInfra	`black-forest-labs/FLUX-1-schnell`	Так (1 зображення)	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	Так (обмеження залежать від моделі)	`FAL_KEY`
Google	`gemini-3.1-flash-image-preview`	Так	`GEMINI_API_KEY` або `GOOGLE_API_KEY`
LiteLLM	`gpt-image-2`	Так (до 5 вхідних зображень)	`LITELLM_API_KEY`
Microsoft Foundry	`<deployment-name>`	Так (лише моделі MAI-Image-2.5)	`AZURE_OPENAI_API_KEY` або Entra ID (`az login`)
MiniMax	`image-01`	Так (референс об’єкта)	`MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`)
OpenAI	`gpt-image-2`	Так (до 4 зображень)	`OPENAI_API_KEY` або OpenAI ChatGPT/Codex OAuth
OpenRouter	`google/gemini-3.1-flash-image-preview`	Так (до 5 вхідних зображень)	`OPENROUTER_API_KEY`
Vydra	`grok-imagine`	Ні	`VYDRA_API_KEY`
xAI	`grok-imagine-image`	Так (до 5 зображень)	`XAI_API_KEY`

Використовуйте action: "list", щоб переглянути доступних провайдерів і моделі під час виконання:

/tool image_generate action=list

Використовуйте action: "status", щоб переглянути активне завдання генерації зображень для поточного сеансу:

/tool image_generate action=status

Можливості провайдерів

Можливість	ComfyUI	DeepInfra	fal	Google	Microsoft Foundry	MiniMax	OpenAI	Vydra	xAI
Генерація (макс. кількість)	Визначено workflow	4	4	4	1	9	4	1	4
Редагування / референс	1 зображення (workflow)	1 зображення	Flux: 1; GPT: 10; референси стилю Krea: 10; NB2: 14	До 5 зображень	1 зображення	1 зображення (референс об’єкта)	До 5 зображень	-	До 5 зображень
Керування розміром	-	✓	✓	✓	✓	-	До 4K	-	-
Співвідношення сторін	-	-	✓	✓	-	✓	-	-	✓
Роздільна здатність (1K/2K/4K)	-	-	✓	✓	-	-	-	-	1K, 2K

Параметри інструмента

prompt

string

обов'язково

Запит для генерації зображення. Обов’язковий для action: "generate".

action

"generate" | "status" | "list"

за замовчуванням:"generate"

Використовуйте "status", щоб переглянути активне завдання сеансу, або "list", щоб переглянути доступних провайдерів і моделі під час виконання.

model

string

Перевизначення провайдера/моделі (наприклад, openai/gpt-image-2). Використовуйте openai/gpt-image-1.5 для прозорих фонів OpenAI.

image

string

Шлях або URL одного референсного зображення для режиму редагування.

images

string[]

Кілька референсних зображень для режиму редагування або моделей із референсами стилю (до 10 через спільний інструмент; обмеження конкретного провайдера все одно застосовуються).

size

string

Підказка розміру: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.

aspectRatio

string

Співвідношення сторін: 1:1, 2:3, 3:2, 2.35:1, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 4:1, 1:4, 8:1, 1:8. Провайдери перевіряють власну підмножину для конкретної моделі.

resolution

"1K" | "2K" | "4K"

Підказка роздільної здатності.

quality

"low" | "medium" | "high" | "auto"

Підказка якості, коли провайдер її підтримує.

outputFormat

"png" | "jpeg" | "webp"

Підказка формату виводу, коли провайдер її підтримує.

background

"transparent" | "opaque" | "auto"

Підказка фону, коли провайдер її підтримує. Використовуйте transparent з outputFormat: "png" або "webp" для провайдерів із підтримкою прозорості.

count

number

Кількість зображень для генерації (1-4).

timeoutMs

number

Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Коли Codex викликає image_generate через динамічні інструменти, це значення для окремого виклику все одно перевизначає налаштоване стандартне значення й обмежується 600000 мс.

filename

string

Підказка імені вихідного файлу.

openai

object

Підказки лише для OpenAI: background, moderation, outputCompression і user.

fal.creativity

"raw" | "low" | "medium" | "high"

Керування креативністю fal Krea 2. Стандартне значення — medium.

Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням зіставляє його з найближчим підтримуваним розміром, співвідношенням сторін або роздільною здатністю. Непідтримувані підказки виводу відкидаються для провайдерів, які не заявляють підтримку, і про це повідомляється в результаті інструмента. Результати інструмента повідомляють застосовані налаштування; details.normalization фіксує будь-яке перетворення із запитаного в застосоване.

Конфігурація

Вибір моделі

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
        fallbacks: [
          "openrouter/google/gemini-3.1-flash-image-preview",
          "google/gemini-3.1-flash-image-preview",
          "fal/fal-ai/flux/dev",
        ],
      },
    },
  },
}

Порядок вибору провайдера

OpenClaw пробує провайдерів у такому порядку:

Параметр model з виклику інструмента (якщо агент його вказує).
imageGenerationModel.primary з конфігурації.
imageGenerationModel.fallbacks за порядком.
Автовиявлення - лише типові значення провайдера, підкріплені автентифікацією:
- поточний типовий провайдер першим;
- решта зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів.

Якщо провайдер зазнає невдачі (помилка автентифікації, ліміт частоти запитів тощо), автоматично пробується наступний налаштований кандидат. Якщо всі зазнають невдачі, помилка містить подробиці з кожної спроби.

Перевизначення моделі для окремого виклику є точними

Перевизначення model для окремого виклику пробує лише цей провайдер/модель і не переходить до налаштованих основного/резервного чи автоматично виявлених провайдерів.

Автовиявлення враховує автентифікацію

Типове значення провайдера потрапляє до списку кандидатів лише тоді, коли OpenClaw може фактично автентифікувати цей провайдер. Установіть agents.defaults.mediaGenerationAutoProviderFallback: false, щоб використовувати лише явні записи model, primary і fallbacks.

Тайм-аути

Установіть agents.defaults.imageGenerationModel.timeoutMs для повільних бекендів зображень. Параметр інструмента timeoutMs для окремого виклику перевизначає налаштоване типове значення, а налаштовані типові значення перевизначають типові значення провайдерів, задані Plugin. Провайдери зображень, розміщені в Google і OpenRouter, використовують типові значення 180 секунд; генерація зображень Microsoft Foundry MAI, xAI і Azure OpenAI використовує 600 секунд. Виклики динамічних інструментів Codex використовують типове значення мосту image_generate 120 секунд і, коли налаштовано, дотримуються того самого бюджету тайм-ауту, обмеженого максимальним значенням мосту динамічних інструментів OpenClaw у 600000 мс.

Перевірка під час виконання

Використовуйте action: "list", щоб перевірити поточно зареєстрованих провайдерів, їхні типові моделі та підказки щодо змінних середовища для автентифікації.

Редагування зображень

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI і xAI підтримують редагування еталонних зображень. Моделі Krea 2 на fal використовують ті самі поля image / images як стильові референси замість вхідних даних для редагування. Передайте шлях до еталонного зображення або URL:

"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"

OpenAI, OpenRouter, Google і xAI підтримують до 5 еталонних зображень через параметр images. fal підтримує 1 еталонне зображення для Flux image-to-image, до 10 для редагувань GPT Image 2, до 10 стильових референсів для Krea 2 і до 14 для редагувань Nano Banana 2. Microsoft Foundry, MiniMax і ComfyUI підтримують 1.

Поглиблений огляд провайдерів

OpenAI gpt-image-2 (і gpt-image-1.5)

Генерація зображень OpenAI типово використовує openai/gpt-image-2. Якщо налаштовано профіль OAuth openai, OpenClaw повторно використовує той самий профіль OAuth, який застосовується моделями чату за підпискою Codex, і надсилає запит зображення через бекенд Codex Responses. Застарілі базові URL Codex, як-от https://chatgpt.com/backend-api, канонізуються до https://chatgpt.com/backend-api/codex для запитів зображень. OpenClaw не повертається непомітно до OPENAI_API_KEY для цього запиту - щоб примусово спрямувати через прямий OpenAI Images API, налаштуйте models.providers.openai явно з API-ключем, користувацьким базовим URL або кінцевою точкою Azure.Моделі openai/gpt-image-1.5, openai/gpt-image-1 і openai/gpt-image-1-mini усе ще можна вибрати явно. Використовуйте gpt-image-1.5 для виводу PNG/WebP із прозорим фоном; поточний API gpt-image-2 відхиляє background: "transparent".gpt-image-2 підтримує як генерацію зображень із тексту, так і редагування за еталонним зображенням через той самий інструмент image_generate. OpenClaw пересилає prompt, count, size, quality, outputFormat і еталонні зображення до OpenAI. OpenAI не отримує aspectRatio або resolution напряму; коли можливо, OpenClaw зіставляє їх із підтримуваним size, інакше інструмент повідомляє про них як про проігноровані перевизначення.Специфічні для OpenAI параметри містяться в об’єкті openai:

{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}

openai.background приймає transparent, opaque або auto; прозорий вивід вимагає outputFormat png або webp і моделі зображень OpenAI з підтримкою прозорості. OpenClaw спрямовує типові запити gpt-image-2 із прозорим фоном до gpt-image-1.5. openai.outputCompression застосовується до виводу JPEG/WebP та ігнорується для виводу PNG.Підказка верхнього рівня background є нейтральною щодо провайдера і наразі зіставляється з тим самим полем запиту OpenAI background, коли вибрано провайдера OpenAI. Провайдери, які не оголошують підтримку фону, повертають її в ignoredOverrides замість отримання непідтримуваного параметра.Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість api.openai.com, див. кінцеві точки Azure OpenAI.

Моделі зображень Microsoft Foundry MAI

Генерація зображень Microsoft Foundry використовує назви розгорнутих розгортань зображень MAI під префіксом провайдера microsoft-foundry/. Типової моделі на рівні провайдера немає, оскільки MAI API очікує назву вашого розгортання в полі model:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}

Провайдер використовує MAI API Microsoft Foundry, а не OpenAI Images API:

Кінцева точка генерації: /mai/v1/images/generations
Кінцева точка редагування: /mai/v1/images/edits
Автентифікація: AZURE_OPENAI_API_KEY / API-ключ провайдера або Entra ID через az login
Вивід: одне зображення PNG
Розмір: типовий 1024x1024; ширина й висота мають бути щонайменше 768 px кожна, а загальна кількість пікселів має бути не більш ніж 1,048,576
Редагування: одне еталонне зображення PNG або JPEG, підтримується лише розгортаннями MAI-Image-2.5-Flash і MAI-Image-2.5

Генерація лише за промптом може використовувати користувацьку назву розгортання, якщо налаштовано тільки кінцеву точку Foundry. Редагування з користувацькими назвами розгортань потребують метаданих онбордингу/моделі, щоб OpenClaw міг перевірити, що розгортання підтримується MAI-Image-2.5-Flash або MAI-Image-2.5.Поточні моделі зображень MAI: MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e і MAI-Image-2. Див. Plugin Microsoft Foundry для налаштування і поведінки чат-моделей.

Моделі зображень OpenRouter

Генерація зображень OpenRouter використовує той самий OPENROUTER_API_KEY і маршрутизується через API зображень chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом openrouter/:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

OpenClaw пересилає prompt, count, еталонні зображення та сумісні з Gemini підказки aspectRatio / resolution до OpenRouter. Поточні вбудовані скорочення моделей зображень OpenRouter включають google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview і openai/gpt-5.4-image-2. Використовуйте action: "list", щоб побачити, що надає ваш налаштований Plugin.

fal Krea 2

Моделі Krea 2 на fal використовують власну схему Krea від fal замість загальної схеми image_size, яку використовує Flux. OpenClaw надсилає:

aspect_ratio для підказок співвідношення сторін
creativity, типово medium
image_style_references, коли надано image або images

Виберіть Krea 2 Medium для швидшої виразної ілюстрації та Krea 2 Large для повільнішого, детальнішого фотореалістичного й текстурованого вигляду:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}

Krea 2 наразі повертає одне зображення на запит. Для Krea надавайте перевагу aspectRatio; OpenClaw зіставляє size з найближчим підтримуваним співвідношенням сторін Krea і відхиляє resolution для Krea, а не пропускає його. Використовуйте fal.creativity, коли потрібен власний рівень креативності Krea:

{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}

Подвійна автентифікація MiniMax

Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax:

minimax/image-01 для налаштувань з API-ключем
minimax-portal/image-01 для налаштувань OAuth

xAI grok-imagine-image

Вбудований провайдер xAI використовує /v1/images/generations для запитів лише за промптом і /v1/images/edits, коли наявний image або images.

Моделі: xai/grok-imagine-image, xai/grok-imagine-image-quality
Кількість: до 4
Референси: одне image або до п’яти images
Співвідношення сторін: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
Роздільності: 1K, 2K
Вивід: повертається як вкладення зображень, керовані OpenClaw

OpenClaw навмисно не надає xAI-власні quality, mask, user або додаткові лише нативні співвідношення сторін, доки ці елементи керування не існуватимуть у спільному міжпровайдерному контракті image_generate.

Приклади

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1

/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Еквівалент CLI:

openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Low-cost draft poster for a quiet productivity app" quality=low openai='{"moderation":"low"}'

Еквівалент CLI:

openclaw infer image generate \
  --model openai/gpt-image-2 \
  --quality low \
  --openai-moderation low \
  --prompt "Low-cost draft poster for a quiet productivity app" \
  --json

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024

/tool image_generate action=generate model=fal/krea/v2/medium/text-to-image prompt="An expressive editorial portrait using this color palette and print texture" images='["/path/to/palette.png","/path/to/texture.jpg"]' aspectRatio=9:16 fal='{"creativity":"high"}'

Ті самі прапорці --output-format, --background, --quality і --openai-moderation доступні в openclaw infer image edit; --openai-background залишається специфічним для OpenAI псевдонімом. Постачальники в комплекті, крім OpenAI, наразі не оголошують явного керування тлом, тому background: "transparent" для них повідомляється як проігнорований.

Пов’язане

Огляд інструментів - усі доступні інструменти агента
ComfyUI - налаштування локального робочого процесу ComfyUI і Comfy Cloud
fal - налаштування постачальника зображень і відео fal
Google (Gemini) - налаштування постачальника зображень Gemini
Plugin Microsoft Foundry - налаштування чату Microsoft Foundry і зображень MAI
MiniMax - налаштування постачальника зображень MiniMax
OpenAI - налаштування постачальника OpenAI Images
Vydra - налаштування зображень, відео й мовлення Vydra
xAI - налаштування зображень, відео, пошуку, виконання коду й TTS Grok
Довідник із конфігурації - конфігурація imageGenerationModel
Моделі - конфігурація моделей і аварійне перемикання

​Швидкий старт

​Поширені маршрути

​Підтримувані провайдери

​Можливості провайдерів

​Параметри інструмента

​Конфігурація

​Вибір моделі

​Порядок вибору провайдера

​Редагування зображень

​Поглиблений огляд провайдерів

​Приклади

​Пов’язане

Швидкий старт

Поширені маршрути

Підтримувані провайдери

Можливості провайдерів

Параметри інструмента

Конфігурація

Вибір моделі

Порядок вибору провайдера

Редагування зображень

Поглиблений огляд провайдерів

Приклади

Пов’язане