Geração de imagens

A ferramenta image_generate permite que o agente crie e edite imagens usando seus provedores configurados. Em sessões de chat, a geração de imagens é executada de forma assíncrona: o OpenClaw registra uma tarefa em segundo plano, retorna o id da tarefa imediatamente e desperta o agente quando o provedor termina. O agente de conclusão segue o modo normal de resposta visível da sessão: entrega automática da resposta final quando configurado, ou message(action="send") quando a sessão exige a ferramenta de mensagem. Se a sessão solicitante estiver inativa ou sua ativação ativa falhar, e algumas imagens geradas ainda estiverem ausentes na resposta de conclusão, o OpenClaw envia um fallback direto idempotente apenas com as imagens ausentes.

A ferramenta só aparece quando pelo menos um provedor de geração de imagens está disponível. Se você não vir image_generate nas ferramentas do seu agente, configure agents.defaults.imageGenerationModel, configure uma chave de API do provedor ou entre com OpenAI ChatGPT/Codex OAuth.

Início rápido

Configure auth

Defina uma chave de API para pelo menos um provedor (por exemplo OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) ou entre com OpenAI Codex OAuth.

Pick a default model (optional)

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

ChatGPT/Codex OAuth usa a mesma referência de modelo openai/gpt-image-2. Quando um perfil OAuth openai está configurado, o OpenClaw roteia solicitações de imagem por esse perfil OAuth em vez de primeiro tentar OPENAI_API_KEY. A configuração explícita models.providers.openai (chave de API, URL base personalizada/Azure) volta a optar pela rota direta da OpenAI Images API.

Ask the agent

“Gere uma imagem de um mascote robô amigável.”O agente chama image_generate automaticamente. Não é necessário colocar a ferramenta em uma lista de permissões: ela é habilitada por padrão quando um provedor está disponível. A ferramenta retorna um id de tarefa em segundo plano, então o agente de conclusão envia o anexo gerado pela ferramenta message quando ele estiver pronto.

Para endpoints LAN compatíveis com OpenAI, como LocalAI, mantenha o models.providers.openai.baseUrl personalizado e opte explicitamente com browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Endpoints de imagem privados e internos continuam bloqueados por padrão.

Rotas comuns

Objetivo	Referência do modelo	Autenticação
Geração de imagens OpenAI com cobrança por API	`openai/gpt-image-2`	`OPENAI_API_KEY`
Geração de imagens OpenAI com autenticação de assinatura Codex	`openai/gpt-image-2`	OpenAI ChatGPT/Codex OAuth
PNG/WebP com fundo transparente OpenAI	`openai/gpt-image-1.5`	`OPENAI_API_KEY` ou OpenAI Codex OAuth
Geração de imagens DeepInfra	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
Geração expressiva/direcionada por estilo fal Krea 2	`fal/krea/v2/medium/text-to-image`	`FAL_KEY`
Geração de imagens OpenRouter	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
Geração de imagens LiteLLM	`litellm/gpt-image-2`	`LITELLM_API_KEY`
Geração de imagens Microsoft Foundry MAI	`microsoft-foundry/<deployment-name>`	`AZURE_OPENAI_API_KEY` ou Entra ID
Geração de imagens Google Gemini	`google/gemini-3.1-flash-image-preview`	`GEMINI_API_KEY` ou `GOOGLE_API_KEY`

A mesma ferramenta image_generate lida com texto-para-imagem e edição com imagem de referência. Use image para uma referência ou images para várias referências. Para modelos Krea 2 no fal, essas referências são enviadas como referências de estilo em vez de entradas de edição. Dicas de saída compatíveis com o provedor, como quality, outputFormat e background, são encaminhadas quando disponíveis e relatadas como ignoradas quando um provedor não oferece suporte a elas. O suporte integrado a fundo transparente é específico da OpenAI; outros provedores ainda podem preservar o alfa de PNG se o backend deles o emitir.

Provedores compatíveis

Provedor	Modelo padrão	Suporte a edição	Autenticação
ComfyUI	`workflow`	Sim (1 imagem, configurada por workflow)	`COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` para cloud
DeepInfra	`black-forest-labs/FLUX-1-schnell`	Sim (1 imagem)	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	Sim (limites específicos do modelo)	`FAL_KEY`
Google	`gemini-3.1-flash-image-preview`	Sim	`GEMINI_API_KEY` ou `GOOGLE_API_KEY`
LiteLLM	`gpt-image-2`	Sim (até 5 imagens de entrada)	`LITELLM_API_KEY`
Microsoft Foundry	`<deployment-name>`	Sim (somente modelos MAI-Image-2.5)	`AZURE_OPENAI_API_KEY` ou Entra ID (`az login`)
MiniMax	`image-01`	Sim (referência de assunto)	`MINIMAX_API_KEY` ou MiniMax OAuth (`minimax-portal`)
OpenAI	`gpt-image-2`	Sim (até 4 imagens)	`OPENAI_API_KEY` ou OpenAI ChatGPT/Codex OAuth
OpenRouter	`google/gemini-3.1-flash-image-preview`	Sim (até 5 imagens de entrada)	`OPENROUTER_API_KEY`
Vydra	`grok-imagine`	Não	`VYDRA_API_KEY`
xAI	`grok-imagine-image`	Sim (até 5 imagens)	`XAI_API_KEY`

Use action: "list" para inspecionar provedores e modelos disponíveis em tempo de execução:

/tool image_generate action=list

Use action: "status" para inspecionar a tarefa ativa de geração de imagens para a sessão atual:

/tool image_generate action=status

Recursos dos provedores

Recurso	ComfyUI	DeepInfra	fal	Google	Microsoft Foundry	MiniMax	OpenAI	Vydra	xAI
Gerar (contagem máxima)	Definido pelo workflow	4	4	4	1	9	4	1	4
Edição / referência	1 imagem (workflow)	1 imagem	Flux: 1; GPT: 10; refs de estilo Krea: 10; NB2: 14	Até 5 imagens	1 imagem	1 imagem (ref de assunto)	Até 5 imagens	-	Até 5 imagens
Controle de tamanho	-	✓	✓	✓	✓	-	Até 4K	-	-
Proporção	-	-	✓	✓	-	✓	-	-	✓
Resolução (1K/2K/4K)	-	-	✓	✓	-	-	-	-	1K, 2K

Parâmetros da ferramenta

prompt

string

obrigatório

Prompt de geração de imagens. Obrigatório para action: "generate".

action

"generate" | "status" | "list"

padrão:"generate"

Use "status" para inspecionar a tarefa ativa da sessão ou "list" para inspecionar provedores e modelos disponíveis em tempo de execução.

model

string

Substituição de provedor/modelo (por exemplo, openai/gpt-image-2). Use openai/gpt-image-1.5 para fundos transparentes da OpenAI.

image

string

Caminho ou URL de uma única imagem de referência para o modo de edição.

images

string[]

Várias imagens de referência para modo de edição ou modelos de referência de estilo (até 10 pela ferramenta compartilhada; limites específicos do provedor ainda se aplicam).

size

string

Dica de tamanho: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.

aspectRatio

string

Proporção: 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. Os provedores validam seu subconjunto específico do modelo.

resolution

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

Dica de resolução.

quality

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

Dica de qualidade quando o provedor oferece suporte.

outputFormat

"png" | "jpeg" | "webp"

Dica de formato de saída quando o provedor oferece suporte.

background

"transparent" | "opaque" | "auto"

Dica de fundo quando o provedor oferece suporte. Use transparent com outputFormat: "png" ou "webp" para provedores compatíveis com transparência.

count

number

Número de imagens a gerar (1-4).

timeoutMs

number

Timeout opcional da solicitação ao provedor em milissegundos. Quando Codex chama image_generate por ferramentas dinâmicas, esse valor por chamada ainda substitui o padrão configurado e é limitado a 600000 ms.

filename

string

Dica de nome de arquivo de saída.

openai

object

Dicas exclusivas da OpenAI: background, moderation, outputCompression e user.

fal.creativity

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

Controle de criatividade do fal Krea 2. O padrão é medium.

Nem todos os provedores oferecem suporte a todos os parâmetros. Quando um provedor de fallback oferece suporte a uma opção de geometria próxima em vez da opção exata solicitada, o OpenClaw remapeia para o tamanho, a proporção ou a resolução compatível mais próxima antes do envio. Dicas de saída sem suporte são descartadas para provedores que não declaram suporte e relatadas no resultado da ferramenta. Os resultados da ferramenta relatam as configurações aplicadas; details.normalization captura qualquer tradução de solicitado para aplicado.

Configuração

Seleção de modelo

{
  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",
        ],
      },
    },
  },
}

Ordem de seleção de provedores

O OpenClaw tenta provedores nesta ordem:

Parâmetro model da chamada de ferramenta (se o agente especificar um).
imageGenerationModel.primary da configuração.
imageGenerationModel.fallbacks em ordem.
Detecção automática - somente padrões de provedor com auth:
- provedor padrão atual primeiro;
- demais provedores de geração de imagens registrados em ordem de ID de provedor.

Se um provedor falhar (erro de auth, limite de taxa etc.), o próximo candidato configurado será tentado automaticamente. Se todos falharem, o erro inclui detalhes de cada tentativa.

Per-call model overrides are exact

Uma substituição de model por chamada tenta somente esse provedor/modelo e não continua para provedores primário/substitutos configurados ou detectados automaticamente.

Auto-detection is auth-aware

Um padrão de provedor só entra na lista de candidatos quando o OpenClaw consegue realmente autenticar esse provedor. Defina agents.defaults.mediaGenerationAutoProviderFallback: false para usar somente entradas explícitas de model, primary e fallbacks.

Timeouts

Defina agents.defaults.imageGenerationModel.timeoutMs para backends de imagem lentos. Um parâmetro de ferramenta timeoutMs por chamada substitui o padrão configurado, e padrões configurados substituem padrões de provedor criados por Plugin. Provedores de imagem hospedados do Google e OpenRouter usam padrões de 180 segundos; geração de imagens do Microsoft Foundry MAI, xAI e Azure OpenAI usa 600 segundos. Chamadas de ferramenta dinâmica do Codex usam um padrão de ponte image_generate de 120 segundos e respeitam o mesmo orçamento de timeout quando configurado, limitado pelo máximo de 600000 ms da ponte de ferramenta dinâmica do OpenClaw.

Inspect at runtime

Use action: "list" para inspecionar os provedores registrados atualmente, seus modelos padrão e dicas de variáveis de ambiente de auth.

Edição de imagens

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI e xAI oferecem suporte à edição de imagens de referência. Modelos Krea 2 no fal usam os mesmos campos image / images como referências de estilo em vez de entradas de edição. Passe um caminho ou URL de imagem de referência:

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

OpenAI, OpenRouter, Google e xAI oferecem suporte a até 5 imagens de referência por meio do parâmetro images. fal oferece suporte a 1 imagem de referência para Flux imagem-para-imagem, até 10 para edições do GPT Image 2, até 10 referências de estilo para Krea 2 e até 14 para edições do Nano Banana 2. Microsoft Foundry, MiniMax e ComfyUI oferecem suporte a 1.

Análises detalhadas de provedores

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

A geração de imagens da OpenAI usa openai/gpt-image-2 por padrão. Se um perfil OAuth openai estiver configurado, o OpenClaw reutiliza o mesmo perfil OAuth usado pelos modelos de chat por assinatura do Codex e envia a solicitação de imagem pelo backend Codex Responses. URLs base legadas do Codex, como https://chatgpt.com/backend-api, são canonicalizadas para https://chatgpt.com/backend-api/codex em solicitações de imagem. O OpenClaw não recorre silenciosamente a OPENAI_API_KEY para essa solicitação - para forçar o roteamento direto pela OpenAI Images API, configure models.providers.openai explicitamente com uma chave de API, URL base personalizada ou endpoint do Azure.Os modelos openai/gpt-image-1.5, openai/gpt-image-1 e openai/gpt-image-1-mini ainda podem ser selecionados explicitamente. Use gpt-image-1.5 para saída PNG/WebP com fundo transparente; a API atual de gpt-image-2 rejeita background: "transparent".gpt-image-2 oferece suporte tanto à geração texto-para-imagem quanto à edição com imagem de referência pela mesma ferramenta image_generate. O OpenClaw encaminha prompt, count, size, quality, outputFormat e imagens de referência para a OpenAI. A OpenAI não recebe aspectRatio ou resolution diretamente; quando possível, o OpenClaw mapeia esses valores para um size compatível, caso contrário a ferramenta os relata como substituições ignoradas.Opções específicas da OpenAI ficam no objeto openai:

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

openai.background aceita transparent, opaque ou auto; saídas transparentes exigem outputFormat png ou webp e um modelo de imagem OpenAI compatível com transparência. O OpenClaw roteia solicitações padrão de fundo transparente de gpt-image-2 para gpt-image-1.5. openai.outputCompression se aplica a saídas JPEG/WebP e é ignorado para saídas PNG.A dica de nível superior background é neutra em relação ao provedor e atualmente mapeia para o mesmo campo de solicitação background da OpenAI quando o provedor OpenAI é selecionado. Provedores que não declaram suporte a fundo retornam isso em ignoredOverrides em vez de receber o parâmetro sem suporte.Para rotear a geração de imagens da OpenAI por uma implantação do Azure OpenAI em vez de api.openai.com, consulte endpoints do Azure OpenAI.

Microsoft Foundry MAI image models

A geração de imagens do Microsoft Foundry usa nomes de implantação de imagem MAI implantados sob o prefixo de provedor microsoft-foundry/. Não há modelo padrão em nível de provedor porque a API MAI espera o nome da sua implantação no campo model:

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

O provedor usa a API MAI do Microsoft Foundry, não a OpenAI Images API:

Endpoint de geração: /mai/v1/images/generations
Endpoint de edição: /mai/v1/images/edits
Auth: AZURE_OPENAI_API_KEY / chave de API do provedor, ou Entra ID via az login
Saída: uma imagem PNG
Tamanho: padrão 1024x1024; largura e altura devem ter pelo menos 768 px cada, e o total de pixels deve ser no máximo 1.048.576
Edições: uma imagem de referência PNG ou JPEG, compatível somente com implantações MAI-Image-2.5-Flash e MAI-Image-2.5

Geração somente por prompt pode usar um nome de implantação personalizado com apenas o endpoint Foundry configurado. Edições com nomes de implantação personalizados precisam de metadados de onboarding/modelo para que o OpenClaw possa verificar que a implantação é baseada em MAI-Image-2.5-Flash ou MAI-Image-2.5.Os modelos de imagem MAI atuais são MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e e MAI-Image-2. Consulte o Plugin Microsoft Foundry para configuração e comportamento de modelos de chat.

OpenRouter image models

A geração de imagens do OpenRouter usa a mesma OPENROUTER_API_KEY e roteia pela API de imagem de conclusões de chat do OpenRouter. Selecione modelos de imagem OpenRouter com o prefixo openrouter/:

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

O OpenClaw encaminha prompt, count, imagens de referência e dicas compatíveis com Gemini de aspectRatio / resolution para o OpenRouter. Os atalhos atuais integrados de modelo de imagem OpenRouter incluem google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview e openai/gpt-5.4-image-2. Use action: "list" para ver o que seu Plugin configurado expõe.

fal Krea 2

Modelos Krea 2 no fal usam o schema Krea nativo do fal em vez do schema genérico image_size usado pelo Flux. O OpenClaw envia:

aspect_ratio para dicas de proporção
creativity, com padrão medium
image_style_references quando image ou images são fornecidos

Selecione Krea 2 Medium para ilustrações expressivas mais rápidas e Krea 2 Large para visuais fotorrealistas e texturizados mais lentos e detalhados:

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

No momento, Krea 2 retorna uma imagem por solicitação. Prefira aspectRatio para Krea; o OpenClaw mapeia size para a proporção Krea compatível mais próxima e rejeita resolution para Krea em vez de descartá-la. Use fal.creativity quando quiser um nível de criatividade nativo do Krea:

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

MiniMax dual-auth

A geração de imagens MiniMax está disponível pelos dois caminhos de auth MiniMax integrados:

minimax/image-01 para configurações com chave de API
minimax-portal/image-01 para configurações com OAuth

xAI grok-imagine-image

O provedor xAI integrado usa /v1/images/generations para solicitações somente por prompt e /v1/images/edits quando image ou images está presente.

Modelos: xai/grok-imagine-image, xai/grok-imagine-image-quality
Contagem: até 4
Referências: um image ou até cinco images
Proporções: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
Resoluções: 1K, 2K
Saídas: retornadas como anexos de imagem gerenciados pelo OpenClaw

O OpenClaw intencionalmente não expõe quality, mask, user nativos da xAI nem proporções extras apenas nativas até que esses controles existam no contrato compartilhado entre provedores image_generate.

Exemplos

/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 equivalente:

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 equivalente:

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"}'

As mesmas flags --output-format, --background, --quality e --openai-moderation estão disponíveis em openclaw infer image edit; --openai-background permanece como um alias específico da OpenAI. Provedores incluídos além da OpenAI não declaram controle explícito de fundo hoje, então background: "transparent" é informado como ignorado para eles.

Relacionado

Visão geral das ferramentas - todas as ferramentas de agente disponíveis
ComfyUI - configuração de fluxo de trabalho local do ComfyUI e do Comfy Cloud
fal - configuração do provedor de imagem e vídeo fal
Google (Gemini) - configuração do provedor de imagem Gemini
Plugin Microsoft Foundry - configuração de chat do Microsoft Foundry e imagem MAI
MiniMax - configuração do provedor de imagem MiniMax
OpenAI - configuração do provedor OpenAI Images
Vydra - configuração de imagem, vídeo e fala do Vydra
xAI - configuração de imagem, vídeo, pesquisa, execução de código e TTS do Grok
Referência de configuração - configuração imageGenerationModel
Modelos - configuração de modelos e failover

​Início rápido

​Rotas comuns

​Provedores compatíveis

​Recursos dos provedores

​Parâmetros da ferramenta

​Configuração

​Seleção de modelo

​Ordem de seleção de provedores

​Edição de imagens

​Análises detalhadas de provedores

​Exemplos

​Relacionado

Início rápido

Rotas comuns

Provedores compatíveis

Recursos dos provedores

Parâmetros da ferramenta

Configuração

Seleção de modelo

Ordem de seleção de provedores

Edição de imagens

Análises detalhadas de provedores

Exemplos

Relacionado