Image Generation

Generate and edit images with the OpenAI-compatible /v3/images endpoints.

Generate and edit images through Eden AI’s OpenAI-compatible image endpoints. Point any OpenAI client at https://api.edenai.run/v3 and the images API works as a drop-in replacement.

Overview

Image models are served by dedicated image endpoints — not the chat completions endpoint:

Method	Path	Purpose
POST	/v3/images/generations	Generate one or more images from a text prompt
POST	/v3/images/edits	Edit an existing image with a prompt (optional mask)
GET	/v3/images/models	List the image models available in your region

Both endpoints return the standard OpenAI image shape — data: [{ url \| b64_json }] — plus Eden’s cost (USD) and provider fields.

Image models are only available on /v3/images/*. Sending one to /v3/chat/completions returns 400 — Model(s) do not support /chat/completions.

This is different from Expert Model image generation, which wraps Eden’s feature API for providers like DALL-E and Stable Diffusion. Use the /v3/images endpoints when you want an OpenAI-compatible, drop-in image surface.

Models

The image surface spans many providers. A few common model strings:

Provider	Model string
Google	google/gemini-2.5-flash-image, google/gemini-3-pro-image-preview, google/imagen-4.0-generate-001
OpenAI	openai/gpt-image-1, openai/gpt-image-1-mini
Stability	stabilityai/sd3.5-large
Amazon	amazon/amazon.nova-canvas-v1:0

Call GET /v3/images/models for the full, region-aware list (image models also appear in GET /v3/models, so the OpenAI SDK’s client.models.list() returns them too).

Generating images

Python

import requests

url = "https://api.edenai.run/v3/images/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "google/gemini-2.5-flash-image",
    "prompt": "A nano banana dish in a fancy restaurant, cinematic lighting",
    "size": "1024x1024",
    "n": 1,
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

# Each item carries either a hosted `url` or an inline base64 `b64_json`
image = result["data"][0]
print(image["url"] or image["b64_json"][:60])

curl -X POST https://api.edenai.run/v3/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "prompt": "A nano banana dish in a fancy restaurant, cinematic lighting",
    "size": "1024x1024",
    "n": 1
  }'

Because the surface is OpenAI-compatible, the official OpenAI SDK works unchanged — just set base_url:

OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="https://api.edenai.run/v3", api_key="YOUR_API_KEY")

result = client.images.generate(
    model="google/gemini-2.5-flash-image",
    prompt="A nano banana dish in a fancy restaurant, cinematic lighting",
    size="1024x1024",
    n=1,
)
print(result.data[0].url or result.data[0].b64_json[:60])

Request parameters

Field	Required	Description
model	yes	provider/model, e.g. google/gemini-2.5-flash-image
prompt	yes	Text description of the image to generate (1–32,000 chars)
n	no	Number of images to generate (1–10)
size	no	Output resolution, e.g. 1024x1024, 1536x1024, auto. Allowed values depend on the model
quality	no	standard, hd, auto — accepted values depend on the model
response_format	no	url or b64_json, forwarded to providers that honor it

Unknown fields are forwarded to the provider unchanged.

Response format

{
  "created": 1779792103,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "url": null,
      "revised_prompt": null
    }
  ],
  "output_format": "png",
  "size": "1024x1024",
  "usage": {
    "total_tokens": 291,
    "input_tokens": 19,
    "output_tokens": 272
  },
  "cost": 0.010975,
  "provider": "google"
}

Saving the image to disk

Python

import base64

# Assuming `result` is the response from POST /v3/images/generations above
image = result["data"][0]

if image["b64_json"]:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(image["b64_json"]))
else:
    # The provider returned a hosted URL instead of inline base64
    import requests
    with open("output.png", "wb") as f:
        f.write(requests.get(image["url"]).content)

Some providers return a hosted url instead of inline b64_json. Download the image if you want to keep it, since those URLs can expire.

Editing images

POST /v3/images/edits takes the same fields as generations plus an images array. Each entry sets exactly one of file_id (returned by Eden’s /v3/upload/... endpoints) or image_url (an https:// URL or a data:image/...;base64,... URL). An optional mask (same shape) marks the regions to edit.

The endpoint dispatches on Content-Type: send application/json for the images[] form below, or multipart/form-data for the classic OpenAI SDK file-upload form.

Python

import requests

url = "https://api.edenai.run/v3/images/edits"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "google/gemini-2.5-flash-image",
    "prompt": "Add a small red hat",
    "images": [
        {"image_url": "https://example.com/photo.png"}
    ],
    "size": "1024x1024",
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result["data"][0]["b64_json"][:60])

image_url with an https:// URL works for providers that accept remote URLs (e.g. Gemini). For openai/gpt-image-*, pass a data: URL or upload the file via /v3/upload/... and reference it by file_id instead — those models do not accept remote URLs.

Listing image models

cURL

curl https://api.edenai.run/v3/images/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Limitations

• No streaming. stream: true is forwarded to the provider but the partial-image pipeline is not wired up.
• No @edenai router or fallbacks. Specify a single explicit provider/model.
• /v3/images/variations is not implemented.

Next Steps

Expert Image Generation

Use Eden’s feature API for DALL-E, Stable Diffusion, and more

Chat Completions

Standard text chat completions reference