> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.meshapi.ai/llms.txt.
> For full documentation content, see https://developers.meshapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.meshapi.ai/_mcp/server.

# Image Generation

> Generate images using OpenAI and Vertex AI models.

# Image Generation

Mesh API exposes a standalone OpenAI-compatible image generation endpoint at `POST /v1/images/generations`, supporting models from OpenAI (`gpt-image-*`, `dall-e-3`) and Vertex AI (Imagen).

## Endpoint

`POST /v1/images/generations`

## Parameters

| Field           | Type      | Description                                                                               |
| :-------------- | :-------- | :---------------------------------------------------------------------------------------- |
| `prompt`        | `string`  | Text description of the image. Required.                                                  |
| `model`         | `string`  | Model ID (e.g., `openai/gpt-image-1`, `vertex/imagen-3`). Required.                       |
| `n`             | `integer` | Number of images to generate (1–10). Default: `1`.                                        |
| `size`          | `string`  | Dimensions or aspect ratio (e.g., `1024x1024`, `1792x1024`). Default: `auto`.             |
| `quality`       | `string`  | Rendering quality: `low`, `medium`, `high`, `hd`, `standard`, or `auto`. Default: `auto`. |
| `output_format` | `string`  | Encoding for the returned image: `png`, `jpeg`, or `webp`. OpenAI only.                   |
| `stream`        | `boolean` | Enable SSE keep-alive / native streaming. Default: `false`.                               |

## Streaming

Setting `stream: true` returns a `text/event-stream` response that prevents the connection from closing during long-running generations.

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]
```

## Response

```json
{
  "created": 1715356800,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "..."
    }
  ],
  "background": "opaque",
  "output_format": "webp",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 1000,
    "total_tokens": 1100
  }
}
```

`background`, `output_format`, `quality`, `size`, and `usage` are only present when the upstream provider returns them. Vertex AI (Imagen) does not return token usage. Vertex AI always returns `b64_json` regardless of `response_format`.

## Examples

### Standard generation

```bash
curl -X POST https://api.meshapi.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "A watercolor of a fox in a snowy forest",
    "n": 1,
    "size": "1024x1024",
    "quality": "high",
    "output_format": "webp"
  }'
```

### Streaming

```bash
curl -X POST https://api.meshapi.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "A watercolor of a fox in a snowy forest",
    "stream": true
  }'
```