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.

python
from praisonaiagents import ImageAgent

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

The user describes an image; the image agent calls the generation API and returns a result you can .save() straight to disk.

Diagram

.save

User prompt

ImageAgent

Image API

Image result

Image file

Save to a file

Every generate(), edit() and variation() result (and their async versions) has .save(path):

python
from praisonaiagents import ImageAgent

agent = ImageAgent()
agent.generate("A cartoon cat waving hello").save("cat.png")

.save() decodes b64_json or downloads an http(s) URL (30s timeout, 50 MB cap) and writes the bytes unchanged — so PNG, JPEG, WebP, GIF and SVG all work, and switching between URL and base64 models needs no code change. It returns the path.

.save() raises ValueError when:

  • No image in response — No image data in response (usually a failed generation), or Image has neither b64_json nor url.
  • Non-http(s) URL — Image URL must be http(s) (e.g. file:// is refused).
  • Download over 50 MB — Image exceeds maximum download size. Read result.data[0].url and download it with your own client instead.

Multiple images (n>1)

python
result = agent.generate("Three logo concepts", n=3)
for i, _ in enumerate(result.images):
    result.save(f"logo-{i}.png", index=i)

.images is the list of returned images (one per n); pass index= to save a specific one.

Choose how to save

Diagram

One image

n > 1

Raw payload

What do you need?

result.save(path)

result.save(path, index=i)

result.data[i].b64_json / .url

The raw provider response is still there: result.data[0].b64_json, result.data[0].url, result.usage, result.model and result["data"] keep working.

Reference: PR #6261, fixes #6260.

Default models

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

MethodDefault modelWhy
generate() / chat()gpt-image-2.5-flareCurrent OpenAI image model
edit()gpt-image-2.5-flareCurrent OpenAI image model
variation()dall-e-2Only model with a variations endpoint — no GPT image replacement

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

Diagram
Local fileImage APIImageAgentUserLocal fileImage APIImageAgentUseralt[b64_json present][url present]generate(“…”).save(“out.gif”)Image requestb64_json or urlDecode base64GET url (30s timeout, 50 MB cap)BytesWrite bytes to pathpath

Quick Start

  1. Simplest Usage
    python
    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
    python
    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
    python
    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
    python
    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:

python
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:

python
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:

python
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):

python
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.

Images 2.5 / 2.6 formats

Provider options such as output_format, frame_count and frame_duration_ms pass straight through to the image API — no extra setup.

Animated GIF

python
from praisonaiagents import ImageAgent

img = ImageAgent(llm="openai/gpt-image-2.5-flare")
img.generate(
    "A cartoon cat waving hello",
    output_format="gif",
    frame_count=8,
    frame_duration_ms=120,
).save("cat.gif")

Vector SVG

python
from praisonaiagents import ImageAgent

img = ImageAgent(llm="openai/gpt-image-2.5-flare")
img.generate("A flat fox logo, two colours", output_format="svg").save("fox.svg")

Edit with mask

python
from praisonaiagents import ImageAgent

img = ImageAgent(llm="openai/gpt-image-2.5-flare")
img.edit("photo.png", "make the cup blue", mask="mask.png").save("cup.png")

Quick draft

python
from praisonaiagents import ImageAgent

img = ImageAgent(llm="openai/gpt-image-2.5-flare")
img.generate("A cafe menu that reads COFFEE 3", quality="low").save("menu.png")

Reference: PR #6261, fixes #6260.

Features

Best Practices

Use environment variables for API keys

Read OPENAI_API_KEY from the environment — never hardcode keys in source files.

Pick the right model

Omit llm= to use the built-in default (gpt-image-2.5-flare for generate/edit, dall-e-2 for variation). Tune cost vs. detail with quality= ("low" … "max"), or switch models via llm=.

Prefer async in web apps

Use achat() when serving multiple concurrent image requests from a FastAPI or gateway handler.

Describe style explicitly

Pass style="natural" or style="vivid" on dall-e-3 for consistent visual output across runs. For other OpenAI image models (gpt-image-*), put style cues in the prompt instead — style is not supported there and ImageAgent drops it automatically.

If you don’t pass style=, ImageAgent sends nothing and the provider picks the default.

Related