Image Generation AI Agents

Generate high-quality images using PraisonAI Image Agents with both synchronous and asynchronous capabilities.

Generate images from natural language descriptions with PraisonAI Image Agents — sync or async, with OpenAI GPT image models out of the box.

from praisonaiagents import ImageAgent

agent = ImageAgent()  # defaults to gpt-image-2.5-flare
agent.chat("A minimalist logo for a coffee shop")

The user describes an image; the image agent calls the generation API and returns the image (base64 for GPT image models).

Default models

ImageAgent picks an image-capable default when you don’t pass llm=. Pass llm= to override.

OpenAI retired dall-e-2/dall-e-3 on 2026-05-12 and gpt-image-1 on 2026-10-23. gpt-image-2.6-flare and gpt-image-2.6-sunburst exist but are not yet available on every OpenAI project — use them via llm= once rolled out to yours.

References: PR #6262, fixes #6259. Earlier: PR #5948, fixes #5944.

How It Works

Quick Start

1. Simplest Usage

   from praisonaiagents import ImageAgent
   
   agent = ImageAgent()
   result = agent.chat("A cute baby sea otter playing with a laptop")
   print(result)

   Set OPENAI_API_KEY in your environment before running. Uses gpt-image-2.5-flare by default.

2. With Explicit Model

   from praisonaiagents import ImageAgent
   
   agent = ImageAgent(llm="openai/gpt-image-2.5-flare")
   result = agent.chat("A cute baby sea otter playing with a laptop")
   print(result)

   Swap in any image model, e.g. llm="openai/gpt-image-2.5-sunburst".

3. With Configuration

   import os
   from praisonaiagents import ImageAgent
   
   agent = ImageAgent(
       name="ImageCreator",
       llm="openai/gpt-image-2.5-flare",
   )
   
   result = agent.chat("A minimalist logo for a coffee shop", quality="high")
   print(result)

4. Async

   import asyncio
   import os
   from praisonaiagents import ImageAgent
   
   async def main():
       agent = ImageAgent(name="ImageCreator")
       result = await agent.achat("A cute baby sea otter playing with a laptop")
       print(result)
   
   asyncio.run(main())

Install with LLM support: pip install "praisonaiagents[llm]"

Non-blocking async (PR #5219)

ImageAgent.agenerate_image, agenerate, aedit, avariation, and (transitively) achat now offload the synchronous image call via asyncio.to_thread, so awaiting one no longer freezes the event loop for the 10–60 second image round-trip.

Reference: PR #5219, fixes #5162.

Run an ImageAgent and a text-only Agent side by side — the text agent keeps streaming while the image generates:

import asyncio
from praisonaiagents import Agent, ImageAgent

img_agent = ImageAgent(name="ImageCreator")
text_agent = Agent(name="Writer", instructions="Write a short product blurb.")

async def main():
    # Before PR #5219 the image call ran inline on the loop thread and
    # silently starved the text agent for the whole 10–60s round-trip.
    # Now both run concurrently.
    image, blurb = await asyncio.gather(
        img_agent.achat("A minimalist logo for a coffee shop"),
        text_agent.achat("Describe a cozy neighbourhood coffee shop"),
    )
    print(image)
    print(blurb)

asyncio.run(main())

Supported image models

ImageAgent works with any image model exposed through LiteLLM. The capability layer (image_generate / image_edit) automatically drops parameters the target model rejects — notably response_format on dall-e-3 and gpt-image-* — so you do not have to special-case them yourself.

ImageAgent also drops style on OpenAI image models other than dall-e-3 (such as the gpt-image-* family), which reject it. Put style cues in the prompt instead.

Extra keyword arguments — quality ("low", "medium", "high", "xhigh", "max", "auto") and Images 2.5/2.6 params such as frame_count, frame_duration_ms, complexity, output_format — pass straight through to the request:

from praisonaiagents import ImageAgent

agent = ImageAgent(llm="openai/gpt-image-2.6-flare")
agent.generate("A bouncing ball", quality="low", frame_count=4, frame_duration_ms=100, output_format="gif")

Default style on dall-e-3 — ImageAgent no longer sends style="natural" by default. If you do not pass style=, the provider picks its own default. To keep the previous output, pass style="natural" explicitly. This also lets ImageAgent work with newer image endpoints that reject style outright with HTTP 400 unknown_parameter: style.

References: PR #5346 (response_format), PR #6077 (style dropped on non-dall-e-3), PR #6097 (style only sent when explicitly set), fixes #5339, #6076, and #6096.

Editing with markup= is rejected

edit() accepts mask= but not markup=. LiteLLM only uploads image and mask as files, so a markup image would be silently ignored — ImageAgent.edit now raises instead:

from praisonaiagents import ImageAgent

agent = ImageAgent()
agent.edit("photo.png", "Make the circled cup blue", markup="markup.png")
# ValueError: 'markup' is not supported through LiteLLM's image_edit yet (it is not
# uploaded as a file). Use 'mask' or call the OpenAI SDK's images.edit directly.

Use a mask instead (transparent areas are edited):

agent.edit("photo.png", "Make the cup blue", mask="mask.png")

If you need markup, call the OpenAI SDK’s images.edit directly.

Reference: PR #6262, fixes #6259.

Features

Best Practices

Related