Skip to main content
De tool image_generate maakt en bewerkt afbeeldingen via je geconfigureerde providers. In chatsessies wordt de tool asynchroon uitgevoerd: OpenClaw registreert een achtergrondtaak, retourneert onmiddellijk de taak-id en wekt de agent wanneer de provider klaar is. De voltooiingsagent volgt de normale modus voor zichtbare antwoorden van de sessie: automatische aflevering van het definitieve antwoord indien geconfigureerd, of message(action="send") wanneer de sessie de berichtentool vereist. Als de sessie van de aanvrager inactief is of het actief wekken ervan mislukt, verzendt OpenClaw een idempotente directe fallback met de gegenereerde afbeeldingen, zodat het resultaat niet verloren gaat.
De tool wordt alleen weergegeven wanneer ten minste één provider voor het genereren van afbeeldingen beschikbaar is. Als je image_generate niet ziet tussen de tools van je agent, configureer dan agents.defaults.mediaModels.image, stel een API-sleutel van een provider in of meld je aan met OpenAI ChatGPT/Codex OAuth.

Snel aan de slag

1

Authenticatie configureren

Stel een API-sleutel in voor ten minste één provider (bijvoorbeeld OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) of meld je aan met OpenAI Codex OAuth.
2

Een standaardmodel kiezen (optioneel)

ChatGPT/Codex OAuth gebruikt dezelfde modelverwijzing openai/gpt-image-2. Wanneer een OAuth-profiel openai is geconfigureerd, routeert OpenClaw afbeeldingsverzoeken via dat OAuth-profiel in plaats van eerst OPENAI_API_KEY te proberen. Expliciete configuratie van models.providers.openai (API-sleutel, aangepaste/Azure-basis-URL) schakelt weer over op de directe route via de OpenAI Images API.
3

De agent een opdracht geven

“Genereer een afbeelding van een vriendelijke robotmascotte.”De agent roept image_generate automatisch aan. Er is geen toelatingslijst voor tools nodig: de tool is standaard ingeschakeld wanneer een provider beschikbaar is. De tool retourneert een id van een achtergrondtaak, waarna de voltooiingsagent de gegenereerde bijlage via de tool message verzendt zodra deze gereed is.
Behoud voor OpenAI-compatibele LAN-eindpunten zoals LocalAI de aangepaste models.providers.openai.baseUrl en meld je expliciet aan met browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Privé- en interne afbeeldingseindpunten blijven standaard geblokkeerd.

Veelgebruikte routes

Dezelfde tool verwerkt tekst-naar-afbeelding en bewerking met referentieafbeeldingen. Gebruik image voor één referentie of images voor meerdere. Voor Krea 2-modellen op fal worden deze referenties verzonden als stijlreferenties in plaats van als invoer voor bewerking. Door de provider ondersteunde uitvoeraanwijzingen, zoals quality, outputFormat en background, worden doorgestuurd wanneer ze beschikbaar zijn en als genegeerd gemeld wanneer een provider geen ondersteuning declareert. De meegeleverde ondersteuning voor transparante achtergronden is specifiek voor OpenAI; andere providers kunnen PNG-alfa nog steeds behouden als hun backend deze uitvoert.

Ondersteunde providers

Gebruik action: "list" om tijdens runtime beschikbare providers en modellen te bekijken:
Gebruik action: "status" om de actieve taak voor het genereren van afbeeldingen voor de huidige sessie te bekijken:

Providermogelijkheden

Toolparameters

string
vereist
Prompt voor het genereren van afbeeldingen. Vereist voor action: "generate".
"generate" | "status" | "list"
standaard:"generate"
Gebruik "status" om de actieve sessietaak te bekijken of "list" om tijdens runtime beschikbare providers en modellen te bekijken.
string
Overschrijving van provider/model (bijvoorbeeld openai/gpt-image-2). Gebruik openai/gpt-image-1.5 voor transparante OpenAI-achtergronden.
string
Pad of URL van één referentieafbeelding voor de bewerkingsmodus.
string[]
Meerdere referentieafbeeldingen voor de bewerkingsmodus of modellen met stijlreferenties (maximaal 14 via de gedeelde tool; providerspecifieke limieten blijven van toepassing).
string
Grootteaanwijzing: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
string
Beeldverhouding: 1:1, 2:1, 20:9, 19.5:9, 2:3, 3:2, 2.35:1, 3:4, 4:3, 4:5, 5:4, 9:16, 9:19.5, 9:20, 16:9, 21:9, 1:2, 4:1, 1:4, 8:1, 1:8. Providers valideren hun modelspecifieke subset.
"1K" | "2K" | "4K"
Resolutieaanwijzing.
"low" | "medium" | "high" | "auto"
Kwaliteitsaanwijzing wanneer de provider deze ondersteunt.
"png" | "jpeg" | "webp"
Aanwijzing voor de uitvoerindeling wanneer de provider deze ondersteunt.
"transparent" | "opaque" | "auto"
Achtergrondaanwijzing wanneer de provider deze ondersteunt. Gebruik transparent met outputFormat: "png" of "webp" voor providers die transparantie ondersteunen.
number
Aantal te genereren afbeeldingen (1-4).
number
Optionele time-out voor providerverzoeken in milliseconden. Wanneer Codex image_generate aanroept via dynamische tools, overschrijft deze waarde per aanroep nog steeds de geconfigureerde standaardwaarde en wordt deze begrensd op 600000 ms.
string
Aanwijzing voor de uitvoerbestandsnaam.
object
Alleen voor OpenAI geldende aanwijzingen: background, moderation, outputCompression en user.
"raw" | "low" | "medium" | "high"
Creativiteitsregeling voor fal Krea 2. Standaard is medium.
Niet alle providers ondersteunen alle parameters. Wanneer een fallbackprovider een vergelijkbare geometrieoptie ondersteunt in plaats van de exact aangevraagde, wijst OpenClaw deze vóór verzending opnieuw toe aan de dichtstbijzijnde ondersteunde grootte, beeldverhouding of resolutie. Niet-ondersteunde uitvoeraanwijzingen worden verwijderd voor providers die geen ondersteuning declareren en gemeld in het toolresultaat. Toolresultaten melden de toegepaste instellingen; details.normalization legt elke omzetting van aangevraagd naar toegepast vast.

Configuratie

Modelselectie

Selectievolgorde van providers

OpenClaw probeert providers in deze volgorde:
  1. model-parameter uit de toolaanroep (als de agent er een opgeeft).
  2. imageGenerationModel.primary uit de configuratie.
  3. imageGenerationModel.fallbacks in volgorde.
  4. Automatische detectie - alleen standaardproviders met geconfigureerde authenticatie:
    • eerst de huidige standaardprovider;
    • daarna de overige geregistreerde providers voor afbeeldingsgeneratie, gesorteerd op provider-id.
Als een provider mislukt (authenticatiefout, snelheidslimiet enzovoort), wordt de volgende geconfigureerde kandidaat automatisch geprobeerd. Als alle kandidaten mislukken, bevat de fout details van elke poging.
Een model-overschrijving per aanroep probeert alleen die provider/dat model en gaat niet verder met de geconfigureerde primaire provider, fallbackprovider of automatisch gedetecteerde providers.
Een standaardprovider wordt alleen aan de kandidatenlijst toegevoegd wanneer OpenClaw daadwerkelijk bij die provider kan authenticeren. Automatische fallback tussen geauthenticeerde providers is altijd ingeschakeld; een model per aanroep blijft doorslaggevend.
Stel agents.defaults.mediaModels.image.timeoutMs in voor trage backends voor afbeeldingen. Een timeoutMs-toolparameter per aanroep overschrijft de geconfigureerde standaardwaarde, en geconfigureerde standaardwaarden overschrijven de door de Plugin opgegeven standaardwaarden van de provider. Door Google en OpenRouter gehoste afbeeldingsproviders gebruiken standaard 180 seconden; afbeeldingsgeneratie van Microsoft Foundry MAI, xAI en Azure OpenAI gebruikt 600 seconden. Dynamische toolaanroepen van Codex gebruiken standaard een image_generate-brugtime-out van 120 seconden en respecteren hetzelfde geconfigureerde time-outbudget, begrensd door het maximum van 600000 ms voor de dynamische-toolbrug van OpenClaw.
Gebruik action: "list" om de momenteel geregistreerde providers, hun standaardmodellen en hints voor authenticatieomgevingsvariabelen te inspecteren.

Afbeeldingen bewerken

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI en xAI ondersteunen het bewerken van referentieafbeeldingen. Krea 2-modellen op fal gebruiken dezelfde velden image / images als stijlreferenties in plaats van bewerkingsinvoer. Geef een pad of URL van een referentieafbeelding door:
OpenAI, OpenRouter en Google ondersteunen maximaal 5 referentieafbeeldingen via de parameter images; xAI ondersteunt er maximaal 3. fal ondersteunt 1 referentieafbeelding voor Flux-afbeelding-naar-afbeelding, maximaal 10 voor GPT Image 2-bewerkingen, maximaal 10 stijlreferenties voor Krea 2 en maximaal 14 voor Nano Banana 2-bewerkingen. Microsoft Foundry, MiniMax en ComfyUI ondersteunen er 1.

Providers uitgelicht

Afbeeldingsgeneratie van OpenAI gebruikt standaard openai/gpt-image-2. Als een openai-OAuth-profiel is geconfigureerd, hergebruikt OpenClaw hetzelfde OAuth-profiel dat door Codex-chatmodellen met abonnement wordt gebruikt en stuurt het afbeeldingsverzoek via de Codex Responses-backend. Verouderde Codex-basis-URL’s, zoals https://chatgpt.com/backend-api, worden voor afbeeldingsverzoeken gecanonicaliseerd naar https://chatgpt.com/backend-api/codex. OpenClaw valt voor dat verzoek niet stilzwijgend terug op OPENAI_API_KEY - om routering rechtstreeks via de OpenAI Images API af te dwingen, configureer je models.providers.openai expliciet met een API-sleutel, aangepaste basis-URL of Azure-eindpunt.De modellen openai/gpt-image-1.5, openai/gpt-image-1 en openai/gpt-image-1-mini kunnen nog steeds expliciet worden geselecteerd. Gebruik gpt-image-1.5 voor PNG/WebP-uitvoer met transparante achtergrond; de huidige gpt-image-2-API weigert background: "transparent".gpt-image-2 ondersteunt zowel tekst-naar-afbeeldinggeneratie als het bewerken van referentieafbeeldingen via dezelfde image_generate-tool. OpenClaw stuurt prompt, count, size, quality, outputFormat en referentieafbeeldingen door naar OpenAI. OpenAI ontvangt aspectRatio en resolution niet rechtstreeks; waar mogelijk zet OpenClaw deze om naar een ondersteunde size, anders meldt de tool ze als genegeerde overschrijvingen.OpenAI-specifieke opties staan onder het object openai:
openai.background accepteert transparent, opaque of auto; transparante uitvoer vereist outputFormat png of webp en een OpenAI-afbeeldingsmodel dat transparantie ondersteunt. OpenClaw routeert standaard gpt-image-2-verzoeken met een transparante achtergrond naar gpt-image-1.5. openai.outputCompression geldt voor JPEG/WebP-uitvoer en wordt genegeerd voor PNG-uitvoer.De hint background op het hoogste niveau is providerneutraal en wordt momenteel toegewezen aan hetzelfde OpenAI-verzoekveld background wanneer de OpenAI-provider is geselecteerd. Providers die geen ondersteuning voor achtergronden declareren, retourneren deze in ignoredOverrides in plaats van de niet-ondersteunde parameter te ontvangen.Als je afbeeldingsgeneratie van OpenAI via een Azure OpenAI-implementatie wilt routeren in plaats van via api.openai.com, raadpleeg je Azure OpenAI-eindpunten.
Afbeeldingsgeneratie van Microsoft Foundry gebruikt de namen van geïmplementeerde MAI-afbeeldingsimplementaties onder het providerprefix microsoft-foundry/. Er is geen standaardmodel op providerniveau, omdat de MAI-API de naam van jouw implementatie verwacht in het veld model:
De provider gebruikt de MAI-API van Microsoft Foundry, niet de OpenAI Images API:
  • Generatie-eindpunt: /mai/v1/images/generations
  • Bewerkingseindpunt: /mai/v1/images/edits
  • Authenticatie: AZURE_OPENAI_API_KEY / API-sleutel van de provider, of Entra ID via az login
  • Uitvoer: één PNG-afbeelding
  • Grootte: standaard 1024x1024; breedte en hoogte moeten elk minimaal 768 px zijn, en het totale aantal pixels mag maximaal 1.048.576 zijn
  • Bewerkingen: één PNG- of JPEG-referentieafbeelding, alleen ondersteund door implementaties van MAI-Image-2.5-Flash en MAI-Image-2.5
Generatie met alleen een prompt kan een aangepaste implementatienaam gebruiken wanneer alleen het Foundry-eindpunt is geconfigureerd. Voor bewerkingen met aangepaste implementatienamen zijn onboarding-/modelmetadata nodig, zodat OpenClaw kan verifiëren dat de implementatie wordt ondersteund door MAI-Image-2.5-Flash of MAI-Image-2.5.De huidige MAI-afbeeldingsmodellen zijn MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e en MAI-Image-2. Zie Microsoft Foundry-Plugin voor configuratie en het gedrag van chatmodellen.
Afbeeldingsgeneratie van OpenRouter gebruikt dezelfde OPENROUTER_API_KEY en wordt gerouteerd via de afbeeldings-API voor chatvoltooiingen van OpenRouter. Selecteer OpenRouter-afbeeldingsmodellen met het prefix openrouter/:
OpenClaw stuurt prompt, count, referentieafbeeldingen en Gemini-compatibele hints voor aspectRatio / resolution door naar OpenRouter. De huidige ingebouwde snelkoppelingen voor OpenRouter-afbeeldingsmodellen omvatten google/gemini-3.1-flash-image, google/gemini-3-pro-image en openai/gpt-5.4-image-2. Gebruik action: "list" om te zien wat je geconfigureerde Plugin beschikbaar stelt.
Krea 2-modellen op fal gebruiken het systeemeigen Krea-schema van fal in plaats van het algemene image_size-schema dat Flux gebruikt. OpenClaw verzendt:
  • aspect_ratio voor hints voor de beeldverhouding
  • creativity, standaard ingesteld op medium
  • image_style_references wanneer image of images wordt opgegeven
Selecteer Krea 2 Medium voor snellere, expressieve illustraties en Krea 2 Large voor tragere, gedetailleerdere fotorealistische en gestructureerde resultaten:
Krea 2 retourneert momenteel één afbeelding per verzoek. Geef voor Krea de voorkeur aan aspectRatio; OpenClaw wijst size toe aan de dichtstbijzijnde ondersteunde Krea-beeldverhouding en weigert resolution voor Krea in plaats van deze weg te laten. Gebruik fal.creativity wanneer je een systeemeigen Krea-creativiteitsniveau wilt:
Afbeeldingsgeneratie van MiniMax is beschikbaar via beide gebundelde authenticatiepaden van MiniMax:
  • minimax/image-01 voor configuraties met API-sleutel
  • minimax-portal/image-01 voor configuraties met OAuth
De gebundelde xAI-provider gebruikt /v1/images/generations voor verzoeken met alleen een prompt en /v1/images/edits wanneer image of images aanwezig is.
  • Modellen: xai/grok-imagine-image, xai/grok-imagine-image-quality
  • Aantal: maximaal 4
  • Referenties: één image of maximaal drie images
  • Beeldverhoudingen: 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
  • Resoluties: 1K, 2K
  • Uitvoer: geretourneerd als door OpenClaw beheerde afbeeldingsbijlagen
OpenClaw stelt de systeemeigen xAI-opties quality, mask, user en de beeldverhouding auto bewust niet beschikbaar totdat deze besturingselementen deel uitmaken van het gedeelde provideroverschrijdende image_generate-contract.

Voorbeelden

Dezelfde vlaggen --output-format, --background, --quality en --openai-moderation zijn beschikbaar voor openclaw infer image edit; --openai-background blijft beschikbaar als een OpenAI-specifieke alias. Gebundelde providers anders dan OpenAI bieden momenteel geen expliciete achtergrondregeling, waardoor background: "transparent" voor deze providers als genegeerd wordt gemeld.

Gerelateerd

  • Overzicht van tools - alle beschikbare agenttools
  • ComfyUI - workflowconfiguratie voor lokale ComfyUI en Comfy Cloud
  • fal - configuratie van fal als provider voor afbeeldingen en video
  • Google (Gemini) - configuratie van Gemini als afbeeldingsprovider
  • Microsoft Foundry-plugin - configuratie van Microsoft Foundry-chat en MAI-afbeeldingen
  • MiniMax - configuratie van MiniMax als afbeeldingsprovider
  • OpenAI - configuratie van OpenAI Images als provider
  • Vydra - configuratie van Vydra voor afbeeldingen, video en spraak
  • xAI - configuratie van Grok voor afbeeldingen, video, zoeken, code-uitvoering en TTS
  • Configuratiereferentie - configuratie van imageGenerationModel
  • Modellen - modelconfiguratie en failover