Geração de imagens

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

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

Defina agents.defaults.imageGenerationModel.timeoutMs para backends lentos de imagem. Um parâmetro timeoutMs da ferramenta por chamada substitui o padrão configurado, e os padrões configurados substituem os padrões do provedor definidos pelo Plugin. Os provedores de imagem hospedados pelo Google e pelo OpenRouter usam padrões de 180 segundos; a geração de imagens do Microsoft Foundry MAI, xAI e Azure OpenAI usa 600 segundos. As chamadas de ferramentas dinâmicas do Codex usam um padrão de 120 segundos para a ponte image_generate e respeitam o mesmo limite de tempo quando configurado, limitado ao máximo de 600000 ms da ponte de ferramentas dinâmicas do OpenClaw.

Use action: "list" para inspecionar os provedores registrados no momento, seus modelos padrão e as indicações de variáveis de ambiente para autenticação.

A geração de imagens da OpenAI usa openai/gpt-image-2 por padrão. Se um perfil OAuth openai estiver configurado, o OpenClaw reutilizará o mesmo perfil OAuth usado pelos modelos de chat da assinatura do Codex e enviará a solicitação de imagem pelo backend Codex Responses. URLs base antigas do Codex, como https://chatgpt.com/backend-api, são normalizadas para https://chatgpt.com/backend-api/codex nas solicitações de imagem. O OpenClaw não recorre silenciosamente a OPENAI_API_KEY nessa 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 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 gerar PNG/WebP com fundo transparente; a API atual do gpt-image-2 rejeita background: "transparent".

O gpt-image-2 oferece suporte tanto à geração de texto para imagem quanto à edição de imagens de referência por meio da mesma ferramenta image_generate. O OpenClaw encaminha prompt, count, size, quality, outputFormat e as imagens de referência para a OpenAI. A OpenAI não recebe aspectRatio nem resolution diretamente; quando possível, o OpenClaw os converte em um size compatível. Caso contrário, a ferramenta os informa 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 igual a png ou webp e um modelo de imagem da OpenAI compatível com transparência. O OpenClaw encaminha solicitações de fundo transparente do gpt-image-2 padrão para o gpt-image-1.5. openai.outputCompression aplica-se às saídas JPEG/WebP e é ignorado nas saídas PNG.

A indicação background no nível superior é independente de provedor e, atualmente, é mapeada para o mesmo campo background da solicitação da OpenAI quando esse provedor está selecionado. Os provedores que não declaram suporte a fundos retornam essa indicação em ignoredOverrides, em vez de receberem o parâmetro não compatível.

Para encaminhar 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.

A geração de imagens do Microsoft Foundry usa os nomes das implantações de imagem MAI sob o prefixo de provedor microsoft-foundry/. Não há um modelo padrão no nível do 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 API OpenAI Images:

• Endpoint de geração: /mai/v1/images/generations
• Endpoint de edição: /mai/v1/images/edits
• Autenticação: AZURE_OPENAI_API_KEY / chave de API do provedor ou Entra ID por meio de 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 de, 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

A geração somente por prompt pode usar um nome de implantação personalizado tendo apenas o endpoint do Foundry configurado. Edições com nomes de implantação personalizados precisam de metadados de integração/modelo para que o OpenClaw possa verificar se a implantação usa 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 do Microsoft Foundry para saber como configurar e entender o comportamento dos modelos de chat.

A geração de imagens do OpenRouter usa a mesma OPENROUTER_API_KEY e é encaminhada pela API de imagens de conclusões de chat 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 as indicações aspectRatio / resolution compatíveis com o Gemini para o OpenRouter. Os atalhos integrados atuais para 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 o Plugin configurado disponibiliza.

Os modelos Krea 2 no fal usam o esquema Krea nativo do fal, em vez do esquema genérico image_size usado pelo Flux. O OpenClaw envia:

• aspect_ratio para indicações de proporção
• creativity, usando medium por padrão
• 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",      },    },  },}

Atualmente, o Krea 2 retorna uma imagem por solicitação. Prefira aspectRatio para o Krea; o OpenClaw mapeia size para a proporção compatível mais próxima do Krea e rejeita resolution para o 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"  }}

A geração de imagens do MiniMax está disponível pelos dois métodos de autenticação integrados do MiniMax:

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

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
• Quantidade: até 4
• Referências: um image ou até três images
• Proporções: 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
• Resoluções: 1K, 2K
• Saídas: retornadas como anexos de imagem gerenciados pelo OpenClaw

O OpenClaw não disponibiliza intencionalmente quality, mask e user nativos do xAI, nem a proporção auto, até que esses controles existam no contrato compartilhado e independente de provedor de image_generate.