Generazione di immagini

Un override model per chiamata prova esclusivamente quel provider/modello e non prosegue con il provider primario, i fallback configurati o i provider rilevati automaticamente.

Il valore predefinito di un provider entra nell'elenco dei candidati solo quando OpenClaw può effettivamente autenticarsi presso tale provider. Imposta agents.defaults.mediaGenerationAutoProviderFallback: false per utilizzare soltanto le voci esplicite model, primary e fallbacks.

Imposta agents.defaults.imageGenerationModel.timeoutMs per i backend di immagini lenti. Un parametro dello strumento timeoutMs per chiamata sostituisce il valore predefinito configurato, mentre i valori predefiniti configurati sostituiscono quelli del provider definiti dal Plugin. I provider di immagini ospitati da Google e OpenRouter utilizzano valori predefiniti di 180 secondi; la generazione di immagini di Microsoft Foundry MAI, xAI e Azure OpenAI utilizza 600 secondi. Le chiamate agli strumenti dinamici di Codex utilizzano un valore predefinito di 120 secondi per il bridge image_generate e, quando configurato, rispettano lo stesso budget di timeout, entro il limite massimo di 600000 ms del bridge degli strumenti dinamici di OpenClaw.

Usa action: "list" per esaminare i provider attualmente registrati, i relativi modelli predefiniti e i suggerimenti sulle variabili d'ambiente di autenticazione.

La generazione di immagini OpenAI utilizza per impostazione predefinita openai/gpt-image-2. Se è configurato un profilo OAuth openai, OpenClaw riutilizza lo stesso profilo OAuth usato dai modelli di chat dell'abbonamento Codex e invia la richiesta di immagine tramite il backend Codex Responses. Gli URL di base Codex precedenti, come https://chatgpt.com/backend-api, vengono normalizzati in https://chatgpt.com/backend-api/codex per le richieste di immagini. OpenClaw non ripiega automaticamente su OPENAI_API_KEY per tale richiesta: per forzare l'instradamento diretto tramite l'API OpenAI Images, configura esplicitamente models.providers.openai con una chiave API, un URL di base personalizzato o un endpoint Azure.

I modelli openai/gpt-image-1.5, openai/gpt-image-1 e openai/gpt-image-1-mini possono comunque essere selezionati esplicitamente. Usa gpt-image-1.5 per ottenere output PNG/WebP con sfondo trasparente; l'API gpt-image-2 corrente rifiuta background: "transparent".

gpt-image-2 supporta sia la generazione da testo a immagine sia la modifica di immagini di riferimento tramite lo stesso strumento image_generate. OpenClaw inoltra a OpenAI prompt, count, size, quality, outputFormat e le immagini di riferimento. OpenAI non riceve direttamente aspectRatio o resolution; quando possibile, OpenClaw li associa a un valore size supportato, altrimenti lo strumento li segnala come override ignorati.

Le opzioni specifiche di OpenAI si trovano nell'oggetto openai:

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

openai.background accetta transparent, opaque o auto; gli output trasparenti richiedono un outputFormat png o webp e un modello di immagini OpenAI che supporti la trasparenza. OpenClaw instrada le richieste con sfondo trasparente del modello predefinito gpt-image-2 verso gpt-image-1.5. openai.outputCompression si applica agli output JPEG/WebP e viene ignorato per gli output PNG.

Il suggerimento background di primo livello è indipendente dal provider e attualmente viene associato allo stesso campo di richiesta background di OpenAI quando è selezionato il provider OpenAI. I provider che non dichiarano il supporto per lo sfondo lo restituiscono in ignoredOverrides anziché ricevere il parametro non supportato.

Per instradare la generazione di immagini OpenAI tramite una distribuzione Azure OpenAI anziché api.openai.com, consulta Endpoint Azure OpenAI.

La generazione di immagini Microsoft Foundry utilizza i nomi delle distribuzioni di immagini MAI sotto il prefisso provider microsoft-foundry/. Non esiste un modello predefinito a livello di provider perché l'API MAI richiede il nome della distribuzione nel campo model:

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

Il provider utilizza l'API MAI di Microsoft Foundry, non l'API OpenAI Images:

• Endpoint di generazione: /mai/v1/images/generations
• Endpoint di modifica: /mai/v1/images/edits
• Autenticazione: AZURE_OPENAI_API_KEY / chiave API del provider oppure Entra ID tramite az login
• Output: un'immagine PNG
• Dimensioni: valore predefinito 1024x1024; larghezza e altezza devono essere entrambe di almeno 768 px, mentre il numero totale di pixel non deve superare 1.048.576
• Modifiche: un'immagine di riferimento PNG o JPEG, supportata soltanto dalle distribuzioni MAI-Image-2.5-Flash e MAI-Image-2.5

La generazione basata esclusivamente sul prompt può utilizzare un nome di distribuzione personalizzato configurando soltanto l'endpoint Foundry. Le modifiche con nomi di distribuzione personalizzati richiedono metadati di onboarding/modello affinché OpenClaw possa verificare che la distribuzione sia basata su MAI-Image-2.5-Flash o MAI-Image-2.5.

I modelli di immagini MAI correnti sono MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e e MAI-Image-2. Consulta il Plugin Microsoft Foundry per la configurazione e il comportamento dei modelli di chat.

La generazione di immagini OpenRouter utilizza la stessa OPENROUTER_API_KEY e viene instradata tramite l'API per immagini dei completamenti chat di OpenRouter. Seleziona i modelli di immagini OpenRouter con il prefisso openrouter/:

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

OpenClaw inoltra a OpenRouter prompt, count, le immagini di riferimento e i suggerimenti aspectRatio / resolution compatibili con Gemini. Le scorciatoie integrate correnti per i modelli di immagini OpenRouter includono google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview e openai/gpt-5.4-image-2. Usa action: "list" per vedere ciò che espone il Plugin configurato.

I modelli Krea 2 su fal utilizzano lo schema Krea nativo di fal anziché lo schema generico image_size utilizzato da Flux. OpenClaw invia:

• aspect_ratio per i suggerimenti sulle proporzioni
• creativity, con valore predefinito medium
• image_style_references quando vengono forniti image o images

Seleziona Krea 2 Medium per illustrazioni espressive più rapide e Krea 2 Large per risultati fotorealistici e materici più lenti e dettagliati:

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

Attualmente Krea 2 restituisce un'immagine per richiesta. Per Krea è preferibile aspectRatio; OpenClaw associa size alle proporzioni Krea supportate più vicine e rifiuta resolution per Krea anziché ignorarlo. Usa fal.creativity quando desideri un livello di creatività nativo di Krea:

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

La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax inclusi:

• minimax/image-01 per configurazioni con chiave API
• minimax-portal/image-01 per configurazioni OAuth

Il provider xAI incluso utilizza /v1/images/generations per le richieste basate esclusivamente sul prompt e /v1/images/edits quando è presente image o images.

• Modelli: xai/grok-imagine-image, xai/grok-imagine-image-quality
• Numero: fino a 4
• Riferimenti: un image o fino a tre images
• Proporzioni: 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
• Risoluzioni: 1K, 2K
• Output: restituiti come allegati immagine gestiti da OpenClaw

OpenClaw non espone intenzionalmente i parametri nativi xAI quality, mask, user o le proporzioni auto finché tali controlli non saranno presenti nel contratto condiviso tra provider image_generate.