> ## Documentation Index
> Fetch the complete documentation index at: https://easy-peasy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Image

> Generate images from a prompt, or edit supplied images. model selects the text-to-image generator; editModel selects the editor for Edit Image with AI. API-key requests wait for standard generation results. Check every returned image_url. Premium models and available credits depend on the account plan.

## Generate or edit an image

* **Text-to-image** — Provide `prompt` + `model`. The `model` picks the generator (e.g. `Nano Banana 2`, `OpenAI GPT Image 2.5 Flare Medium`).
* **Editing / reference image** — Provide `prompt` + `image` (or `images`). With no explicit `action`, this selects **Edit Image with AI** and uses `editModel` to select the editor. Other actions, such as background removal, have their own behavior.

<Note>
  Send **`editModel` explicitly** when editing. With an image and no `action`, omitting `editModel` selects `OpenAI GPT Image 2 Medium`. If you explicitly set `action: "Edit Image with AI"` and omit `editModel`, the default is `Qwen Image`. To select Qwen Image explicitly, include that action too. Text-to-image defaults to `model: "Nano Banana 2"`.
</Note>

The reference image does not need to be hosted on Easy-Peasy, but it **must be downloadable server-side** — some hosts (e.g. Wikimedia, or sites that block hotlinking / non-browser requests) return **HTTP 403** to automated fetches and will fail. If in doubt, host it on your own public CDN/bucket. Write the `prompt` as an instruction about the image (e.g. "change the color to yellow", "place this product on a marble counter").

### One reference image

```bash theme={null}
curl -X POST https://easy-peasy.ai/api/generate-image \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Place this product on a marble kitchen counter with soft morning light",
    "image": "https://yourcdn.com/product.png",
    "editModel": "Nano Banana 2",
    "dimensions": "1:1"
  }'
```

### Multiple reference images

Pass `images` as a **JSON-encoded string array** (not a JSON array):

```bash theme={null}
curl -X POST https://easy-peasy.ai/api/generate-image \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Put the person from the first image into the room in the second image",
    "images": "[\"https://yourcdn.com/person.png\", \"https://yourcdn.com/room.png\"]",
    "editModel": "Nano Banana 2",
    "dimensions": "1:1"
  }'
```

## Model naming notes

* **GPT Image 2** is exposed as three quality tiers — use the exact strings `OpenAI GPT Image 2 Low`, `OpenAI GPT Image 2 Medium`, or `OpenAI GPT Image 2 High`. There is no bare `"GPT Image 2"` value.
* **GPT Image 2.5** uses exact quality names such as `OpenAI GPT Image 2.5 Flare Medium` and `OpenAI GPT Image 2.5 Sunburst High`. The schemas list all available tiers.
* **New image models** include `Nano Banana 2 Lite`, `Seedream 5.0 Pro`, `Muse Image`, `Grok Imagine 2.0`, `WAN 2.7`, and others listed below. The generation and editing lists differ.
* **Reve** is `REVE` for text-to-image (`model`), and `Reve` / `Reve Fast` for editing (`editModel`). There is no `"Reve 2.0"`.
* Model names are matched **exactly** — always send a value as listed in the schema enums below. An unrecognized `editModel` returns a `400` error; an unrecognized `model` may fall back to a default generator, so a typo can silently produce the wrong model.

## Read the result

The response is an array of image records. Modern model integrations wait for results when you authenticate with an API key; the web-only `waitForResult` flag does not turn that off. Some legacy integrations, including Midjourney, return pending records with empty `image_url` values.

Check each record's `image_url`. If it is empty, save its `id` and poll [Get Image](/docs/api-reference/endpoint/get-image) every 15–30 seconds with the same account's key. Stop after a bounded timeout and retain the ID. A polling timeout does not cancel generation or justify automatically creating another paid job.

`outputs` defaults to one, but actual output count depends on the model. Midjourney returns four records per job. Credit amounts can be fractional.

DALL-E 3 and Imagen titles are no longer in this endpoint's documented catalog. Update older integrations to a listed model instead of relying on fallback behavior.


## OpenAPI

````yaml POST /api/generate-image
openapi: 3.0.1
info:
  title: Easy-Peasy.AI API
  description: >-
    API for Easy-Peasy.AI text, image, video, audio, and chat features.
    Authenticate with an API key from https://easy-peasy.ai/settings/api.
    Individual endpoints document public access and alternative authentication
    methods.
  version: 1.0.5
servers:
  - url: https://easy-peasy.ai
security:
  - apiKeyAuth: []
paths:
  /api/generate-image:
    post:
      summary: Generate Image
      description: >-
        Generate images from a prompt, or edit supplied images. model selects
        the text-to-image generator; editModel selects the editor for Edit Image
        with AI. API-key requests wait for standard generation results. Check
        every returned image_url. Premium models and available credits depend on
        the account plan.
      operationId: generateImage
      requestBody:
        description: The prompt and model to generate the image
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
      responses:
        '200':
          description: Successful image generation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '400':
          description: Bad request - missing required fields or invalid values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid input
        '401':
          description: Missing or invalid authentication, or blocked account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient credits or model unavailable on the current plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Server error
components:
  schemas:
    ImageGenerationRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: The textual description of the image to be generated
          example: neon cat
        model:
          type: string
          description: >-
            Exact text-to-image model title. Defaults to Nano Banana 2. For Edit
            Image with AI, choose editModel instead. Unknown titles may fall
            back to another generator; use a listed value.
          enum:
            - Nano Banana 2 Lite
            - Nano Banana 2
            - OpenAI GPT Image 2 Low
            - OpenAI GPT Image 2 Medium
            - OpenAI GPT Image 2 High
            - OpenAI GPT Image 2.5 Flare Low
            - OpenAI GPT Image 2.5 Flare Medium
            - OpenAI GPT Image 2.5 Flare High
            - OpenAI GPT Image 2.5 Sunburst Medium
            - OpenAI GPT Image 2.5 Sunburst High
            - Nano Banana Pro
            - Nano Banana Flash
            - Z-Image Turbo
            - ImagineArt 1.5
            - Mai Image 2.5
            - Muse Image
            - FLUX.2 [max]
            - FLUX.2 [flex]
            - FLUX.2 [pro]
            - FLUX.2 [dev]
            - Seedream 4.0
            - Seedream 4.5
            - Seedream 5.0 Lite
            - Seedream 5.0 Pro
            - Qwen Image Max
            - Qwen Image 2.0
            - WAN 2.7 Pro
            - WAN 2.7
            - Krea v2 Large
            - Krea v2 Medium
            - Krea v2 Medium Turbo
            - Luma Uni v1
            - Boogu Image
            - Cosmos 3 Super
            - P-Image
            - HunyuanImage 3.0
            - REVE
            - Recraft v4.1
            - Recraft v4.1 Pro
            - Recraft v4.1 Vector
            - Recraft v4.1 Pro Vector
            - Recraft v3
            - Stable Diffusion XL
            - FLUX.1
            - Stable Diffusion 3.5
            - Bria 3.2
            - HiDream
            - WAN 2.2
            - WAN 2.5 Preview
            - Dreamina 3.1
            - Qwen-Image
            - Grok Imagine 2.0
            - Grok
            - Grok Pro
            - Kandinsky 3.0
            - Kandinsky 2.2
            - Kandinsky 2
            - MiniMax Image 01
            - FLUX 1.1 Pro Ultra
            - Ideogram v4
            - Ideogram v3
            - Flux Kontext Pro
            - Flux Kontext Max
            - Seedream 3.0
            - Nano Banana
            - OpenAI GPT Image 1
            - OpenAI GPT Image 1.5
            - Midjourney V6
            - Midjourney V7
            - FLUX 1.1 Pro
            - Flux.1 Krea
            - Stable Diffusion 3.0
          example: Nano Banana 2
          default: Nano Banana 2
        style:
          type: string
          description: >-
            Style for the image (e.g. Cyberpunk, Watercolor). Not all models
            support this parameter.
          example: Cyberpunk
        artist:
          type: string
          description: >-
            Artist style to emulate (e.g. Van Gogh). Not all models support this
            parameter.
          example: Van Gogh
        dimensions:
          type: string
          description: >-
            Size or aspect ratio, depending on the selected generator or editor.
            Nano Banana 2 accepts ratios such as 1:1, 16:9, and 9:16; OpenAI GPT
            Image accepts sizes such as 1024x1024, 1536x1024, and 1024x1536.
            Support differs by model. The request default is 1024x1024; send a
            value appropriate to your chosen model.
          example: 1024x1024
          default: 1024x1024
        useHD:
          type: boolean
          description: Use HD quality. Supported by select models.
          default: false
          example: false
        image:
          type: string
          format: uri
          description: >-
            Public input image URL. With no action, selects Edit Image with AI.
            Choose editModel to select the editor. For several reference images
            use images.
        images:
          type: string
          description: >-
            JSON-encoded array of reference image URLs, for edit models that
            accept several inputs (e.g. combine subjects/scenes). Example:
            `"[\"https://.../a.png\", \"https://.../b.png\"]"`. When set, takes
            precedence over `image`.
          example: >-
            ["https://media.easy-peasy.ai/a.png",
            "https://media.easy-peasy.ai/b.png"]
        action:
          type: string
          description: >-
            Action to perform on the image. If not specified when `image` is
            provided, defaults to `Edit Image with AI` (which then uses
            `editModel`). "Character Reference" / "Style Reference" generate new
            scenes that keep a subject/style rather than editing the source
            image.
          enum:
            - Edit Image with AI
            - Remove Background
            - Replace Background
            - Colorize
            - Relight
            - Stylization
            - Realistic Photos
            - Hyper Realistic Photos
            - Sketch to Image
            - Ghiblify
            - Caricature
            - Muppets
            - Halloween
            - Professional Headshot
            - Character Reference
            - Consistent Character
            - Style Reference
            - Style Reference SD3
            - Find and Replace
            - Visualize What Happens Next
        editModel:
          type: string
          description: >-
            Editor used with action: Edit Image with AI. Without an explicit
            action, image/images selects OpenAI GPT Image 2 Medium when
            editModel is omitted or Qwen Image. With an explicit Edit Image with
            AI action, the omitted editModel defaults to Qwen Image. Send
            editModel explicitly for predictable behavior.
          enum:
            - Nano Banana 2 Lite
            - Nano Banana 2
            - Nano Banana Pro
            - Grok
            - Grok Pro
            - Grok Imagine 2.0
            - Muse Image
            - OpenAI GPT Image 1.5
            - OpenAI GPT Image 2 Low
            - OpenAI GPT Image 2 Medium
            - OpenAI GPT Image 2 High
            - OpenAI GPT Image 2.5 Flare Low
            - OpenAI GPT Image 2.5 Flare Medium
            - OpenAI GPT Image 2.5 Flare High
            - OpenAI GPT Image 2.5 Sunburst Medium
            - OpenAI GPT Image 2.5 Sunburst High
            - Seedream 4.5
            - Seedream 5.0 Lite
            - Seedream 5.0 Pro
            - FLUX.2 [max]
            - FLUX.2 [pro]
            - FLUX.2 [flex]
            - Seedream 4.0
            - Nano Banana
            - Qwen Image
            - Reve
            - Reve Fast
            - Mai Image 2.5
            - Flux Kontext Pro
            - Flux Kontext Max
            - OpenAI GPT Image 1
            - Ideogram v3 Character
        outputs:
          type: integer
          description: Number of images to generate.
          default: 1
          example: 1
        resolution:
          type: string
          description: >-
            Model-specific image resolution tier (uppercase K). Nano Banana 2
            defaults to 1K; Nano Banana Pro/Flash default to 2K. Not every model
            supports every tier. This does not use the lowercase video
            resolution values.
          enum:
            - 0.5K
            - 1K
            - 2K
            - 4K
          example: 1K
        recraftStyle:
          type: string
          description: Style preset for Recraft v3 model.
          default: any
          example: any
    ImageGenerationResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            description: Unique identifier for the generated image
            example: 545135
          image_url:
            type: string
            description: URL of the generated image
            example: https://yourcdn.com/generated-image.png
          model:
            type: string
            description: The model used for the image generation
            example: Nano Banana 2
          used_credits:
            type: number
            description: Credits used, which may be fractional.
            example: 2
          prompt:
            type: string
            description: The prompt used for image generation
            example: neon cat
    Error:
      type: object
      properties:
        error:
          oneOf:
            - type: string
            - type: object
              properties:
                message:
                  type: string
                status:
                  type: integer
          description: >-
            Error text, or an object with message and optional status for some
            provider integrations.
          example: Invalid API key
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key for authentication. Get yours at
        https://easy-peasy.ai/settings/api

````