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

# Image Generation

> Generate and edit images using frontier vision models via a single API.

Generate images from text prompts — or edit existing images — using models from OpenAI, Google Vertex AI, and more. The API is compatible with the OpenAI images endpoint, so existing integrations work without modification.

## Generate an image

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/images/generations \
      -H "Authorization: Bearer rsk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/gpt-image-1-mini",
        "prompt": "A children drawing of a veterinarian and a baby otter",
        "response_format": "url"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(api_key="rsk_...", base_url="https://api.meshapi.ai/v1")

    response = client.images.generate(
        model="openai/gpt-image-1-mini",
        prompt="A children drawing of a veterinarian and a baby otter",
        response_format="url",
    )
    print(response.data[0].url)
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "created": 1717200000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

## Request fields

<Warning>
  Not all parameters are supported by every model. Support varies by provider — unsupported fields are silently ignored or return an error depending on the model. Check the model's documentation or test with your target model before relying on a specific parameter.
</Warning>

| Field                | Type    | Description                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `model`              | string  | Image model ID (required)                                                                                   |
| `prompt`             | string  | Text description of the image to generate                                                                   |
| `n`                  | integer | Number of images to generate (default: 1)                                                                   |
| `size`               | string  | Image dimensions — e.g. `"1024x1024"`, `"1792x1024"`, or `"auto"` (default)                                 |
| `quality`            | string  | `"auto"` (default), `"standard"` / `"hd"` (DALL-E 3), or `"low"` / `"medium"` / `"high"` (GPT image models) |
| `response_format`    | string  | `"url"` (default) or `"b64_json"`                                                                           |
| `output_format`      | string  | Output encoding: `"png"`, `"jpeg"`, or `"webp"` — GPT image models only                                     |
| `output_compression` | integer | Compression level 0–100 for `jpeg`/`webp` output — GPT image models only                                    |
| `background`         | string  | Transparency: `"transparent"`, `"opaque"`, or `"auto"` — GPT image models only                              |
| `moderation`         | string  | Content-moderation level: `"low"` or `"auto"` — GPT image models only                                       |
| `partial_images`     | integer | Number of partial images streamed during generation (0–3) — streaming only                                  |

## Edit an image

Transform an existing image — edit it with a prompt (optionally guided by a mask) or remove its background — by uploading it to `POST /v1/images/edits`. Unlike generation, this endpoint uses **`multipart/form-data`** (file upload), not JSON.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/images/edits \
      -H "Authorization: Bearer rsk_YOUR_KEY" \
      -F "model=openai/gpt-image-1" \
      -F "operation=edit" \
      -F "prompt=Add a party hat on the cat" \
      -F "image=@cat.png"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(api_key="rsk_...", base_url="https://api.meshapi.ai/v1")

    response = client.images.edit(
        model="openai/gpt-image-1",
        prompt="Add a party hat on the cat",
        image=open("cat.png", "rb"),
    )
    print(response.data[0].url)
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "created": 1717200000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

<Info>
  `gpt-image-1` always returns the result as a base64 data URI in the `url` field. Pass `response_format=b64_json` for a `b64_json` field instead (supported on DALL·E models).
</Info>

### Operations

The `operation` field selects what to do. Support varies by provider:

| Operation           | Description                                                      | Providers        |
| ------------------- | ---------------------------------------------------------------- | ---------------- |
| `edit` (default)    | Edit guided by `prompt` (+ optional `mask` and reference images) | OpenAI, BytePlus |
| `remove_background` | Strip the background; returns a transparent image                | OpenAI           |

Requesting an operation a provider doesn't support returns `422`. A provider with no image-edit support at all returns `501`.

<Info>
  BytePlus supports `edit` only. `remove_background` is OpenAI-only.
</Info>

### Request fields

`multipart/form-data`:

| Field              | Type    | Description                                                         |
| ------------------ | ------- | ------------------------------------------------------------------- |
| `model`            | string  | Image model ID (required)                                           |
| `image`            | file    | Source image — PNG, JPEG, or WebP, up to 20 MB (required)           |
| `prompt`           | string  | Edit instruction — required for `edit`                              |
| `operation`        | string  | `edit` (default) or `remove_background`                             |
| `mask`             | file    | Region to edit (OpenAI inpainting). Same formats as `image`         |
| `reference_images` | file\[] | Extra reference images (multi-image edit). 20 MB each, 28 MiB total |
| `n`                | integer | Number of images to return (default: 1)                             |
| `size`             | string  | Output dimensions — e.g. `"1024x1024"` or `"auto"` (default)        |
| `response_format`  | string  | `"url"` (default) or `"b64_json"` (DALL·E only)                     |
| `background`       | string  | `"transparent"`, `"opaque"`, or `"auto"`                            |

<Warning>
  The per-file caps sit under a hard **32 MiB** ceiling on the whole request body,
  enforced at the edge — which is why the reference-image aggregate is 28 MiB rather
  than the sum of the per-file limits. An oversized request returns a plain HTML
  `413` page with no Mesh error envelope and no request ID. See
  [Rate Limits & Spend Caps](/docs/getting-started/rate-limits#request-body-size).
</Warning>

### More examples

Remove a background:

```bash theme={null}
curl https://api.meshapi.ai/v1/images/edits \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -F "model=openai/gpt-image-1" \
  -F "operation=remove_background" \
  -F "image=@product.png"
```

Edit with multiple reference images (BytePlus Seedream):

```bash theme={null}
curl https://api.meshapi.ai/v1/images/edits \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -F "model=byteplus/seedream-4-5" \
  -F "operation=edit" \
  -F "prompt=Blend these into one product scene" \
  -F "image=@base.png" \
  -F "reference_images=@ref1.png" \
  -F "reference_images=@ref2.png"
```

## Streaming

Some models support streaming image generation — partial image data is sent as the model renders it. Set `"stream": true`:

```json theme={null}
{
  "model": "openai/gpt-image-1-mini",
  "prompt": "...",
  "stream": true
}
```

The response is a `text/event-stream`. Its main job is to keep the connection open during a long generation: the server emits an initial `processing` chunk, then SSE comment pings until the image is ready. The stream always ends with `data: [DONE]`.

### Keep-alive chunk sequence

```
data: {"id":"img-...","object":"image.chunk","created":...,"model":"...","data":[],"status":"processing"}

: ping

: ping

data: {"id":"...","object":"image.chunk","created":...,"data":[{"url":"..."}]}

data: [DONE]
```

## Available models

| Model                     | Notes                                           |
| ------------------------- | ----------------------------------------------- |
| `openai/gpt-image-1-mini` | Fast, cost-efficient — ideal for most use cases |
| `openai/gpt-image-1`      | Highest quality, instruction-following          |
| `openai/dall-e-3`         | High quality, supports `hd` quality setting     |
| `openai/dall-e-2`         | Legacy, lower cost                              |

<Info>
  Check `GET /v1/models` for the full live list of enabled image models and their pricing.
</Info>