Geração de imagens

A ferramenta image_generate permite que o agente crie e edite imagens usando seus provedores configurados. As imagens geradas são entregues automaticamente como anexos de mídia na resposta do agente.

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 de provedor ou entre com OpenAI Codex OAuth.

Início rápido

Configurar autenticação

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.

Escolher um modelo padrão (opcional)

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

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

Pedir ao agente

“Gere uma imagem de um mascote robô amigável.”O agente chama image_generate automaticamente. Não é necessário adicionar a ferramenta a uma lista de permissões - ela é habilitada por padrão quando um provedor está disponível.

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

Rotas comuns

Objetivo	Referência de modelo	Autenticação
Geração de imagem OpenAI com cobrança por API	`openai/gpt-image-2`	`OPENAI_API_KEY`
Geração de imagem OpenAI com autenticação de assinatura Codex	`openai/gpt-image-2`	OpenAI Codex OAuth
PNG/WebP com fundo transparente OpenAI	`openai/gpt-image-1.5`	`OPENAI_API_KEY` ou OpenAI Codex OAuth
Geração de imagem DeepInfra	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
Geração de imagem OpenRouter	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
Geração de imagem LiteLLM	`litellm/gpt-image-2`	`LITELLM_API_KEY`
Geração de imagem 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. 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 as suporta. O suporte incluído a fundo transparente é específico da OpenAI; outros provedores ainda podem preservar o alfa 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 pelo workflow)	`COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` para nuvem
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`
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 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

Capacidades dos provedores

Capacidade	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
Gerar (contagem máx.)	Definido pelo workflow	4	4	4	9	4	1	4
Editar / referência	1 imagem (workflow)	1 imagem	Flux: 1; GPT: 10; NB2: 14	Até 5 imagens	1 imagem (referência 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 imagem. Obrigatório para action: "generate".

action

"generate" | "list"

padrão:"generate"

Use "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 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 o modo de edição (até 5 em provedores compatíveis).

size

string

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

aspectRatio

string

Proporção: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

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 com suporte a transparência.

count

number

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

timeoutMs

number

Tempo limite 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 somente para OpenAI: background, moderation, outputCompression e user.

Nem todos os provedores oferecem suporte a todos os parâmetros. Quando um provedor de fallback suporta uma opção de geometria próxima em vez da 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 não compatíveis 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 os provedores nesta ordem:

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

Se um provedor falhar (erro de autenticação, limite de taxa etc.), o próximo candidato configurado é tentado automaticamente. Se todos falharem, o erro inclui detalhes de cada tentativa.

Substituições de modelo por chamada são exatas

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

A detecção automática considera a autenticação

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.

Tempos limite

Defina agents.defaults.imageGenerationModel.timeoutMs para backends de imagem lentos. Um parâmetro de ferramenta timeoutMs por chamada substitui o padrão configurado. Chamadas de ferramentas dinâmicas do Codex respeitam o mesmo orçamento de tempo limite, limitado pelo máximo de 600000 ms da ponte de ferramentas dinâmicas do OpenClaw.

Inspecionar em tempo de execução

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

Edição de imagens

OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI e xAI oferecem suporte à edição de imagens de referência. 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 aceitam até 5 imagens de referência por meio do parâmetro images. A fal aceita 1 imagem de referência para Flux image-to-image, até 10 para edições do GPT Image 2 e até 14 para edições do Nano Banana 2. MiniMax e ComfyUI aceitam 1.

Análises detalhadas de provedores

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

A geração de imagens da OpenAI usa openai/gpt-image-2 por padrão. Se um perfil OAuth openai-codex 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 API OpenAI Images, configure models.providers.openai explicitamente com uma chave de API, URL base personalizada ou endpoint 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 gpt-image-2 rejeita background: "transparent".gpt-image-2 oferece suporte tanto à geração texto-para-imagem quanto à edição com imagens 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 nem resolution diretamente; quando possível, o OpenClaw mapeia esses campos para um size compatível; caso contrário, a ferramenta os relata como substituições ignoradas.As 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 da OpenAI com suporte a 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.A dica de nível superior background é neutra em relação ao provedor e, no momento, mapeia para o mesmo campo de solicitação background da OpenAI quando o provedor OpenAI está selecionado. Provedores que não declaram suporte a fundo a retornam em ignoredOverrides em vez de receberem o parâmetro sem suporte.Para rotear a geração de imagens da OpenAI por uma implantação Azure OpenAI em vez de api.openai.com, consulte endpoints Azure OpenAI.

Modelos de imagem do OpenRouter

A geração de imagens do OpenRouter usa a mesma OPENROUTER_API_KEY e é roteada pela API de imagens de chat completions do OpenRouter. Selecione modelos de imagem do 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 de aspectRatio / resolution compatíveis com Gemini para o OpenRouter. Os atalhos atuais integrados de modelos de imagem do 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.

Autenticação dupla do MiniMax

A geração de imagens do MiniMax está disponível por ambos os caminhos de autenticação 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 com prompt e /v1/images/edits quando image ou images está presente.

Modelos: xai/grok-imagine-image, xai/grok-imagine-image-pro
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 exclusivas do provedor até que esses controles existam no contrato compartilhado entre provedores image_generate.

Exemplos

Gerar (paisagem 4K)
Gerar (PNG transparente)
Gerar (duas quadradas)
Editar (uma referência)
Editar (várias referências)

/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="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

As mesmas flags --output-format e --background estão disponíveis em openclaw infer image edit; --openai-background permanece como um alias específico da OpenAI. Provedores integrados diferentes da OpenAI não declaram controle explícito de fundo hoje, portanto background: "transparent" é relatado como ignorado para eles.

Relacionados

Visão geral das ferramentas - todas as ferramentas de agente disponíveis
ComfyUI - configuração de fluxo de trabalho local do ComfyUI e Comfy Cloud
fal - configuração do provedor de imagem e vídeo fal
Google (Gemini) - configuração do provedor de imagens Gemini
MiniMax - configuração do provedor de imagens 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 de imageGenerationModel
Modelos - configuração de modelos e failover

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Geração de imagens

Início rápido

Rotas comuns

Provedores compatíveis

Capacidades 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

Relacionados

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Início rápido

​Rotas comuns

​Provedores compatíveis

​Capacidades 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

​Relacionados

Início rápido

Rotas comuns

Provedores compatíveis

Capacidades 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

Relacionados