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

# Streaming Events

> Server-Sent Events (SSE) pushed by the MiniMax-H3-Image text-to-image and image edit endpoints when `stream: true`.

With `stream: true`, the [Text-to-Image](https://platform.minimax.io/docs/api-reference/image-generation-h3-generations.md) and [Image Edit](https://platform.minimax.io/docs/api-reference/image-generation-h3-edits.md) endpoints push results image by image via SSE, followed by a summary event.

* Only `response_format: "url"` is supported
* Events arrive in completion order; use `image_index` to identify each image
* Errors before the response headers are returned (invalid parameters, authentication, rate limiting, insufficient balance, etc.) return a regular HTTP error, the same as non-streaming calls; later errors are returned as an `error` event whose `error.http_code` matches the HTTP status code of the non-streaming call
* While waiting, an SSE comment line `: keepalive` is sent every 15 seconds and can be ignored; the response headers are returned with the first keepalive (about 15 seconds) at the latest
* The stream ends with either `completed` or `error`, both carrying `usage` and `request_id`

## Event Types

Both endpoints use the same event structure; only the `type` prefix differs:

| Event | Text-to-Image (`/v1/images/generations`) | Image Edit (`/v1/images/edits`) |
| - | - | - |
| Single image succeeded | `image_generation.partial_succeeded` | `image_edit.partial_succeeded` |
| Single image failed | `image_generation.partial_failed` | `image_edit.partial_failed` |
| All done | `image_generation.completed` | `image_edit.completed` |
| Request failed | `error` | `error` |

Each event consists of an `event:` line and a `data:` line, where `data` is JSON. Events are separated by a blank line:

```text theme={null}
event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded", ...}

```

### partial\_succeeded

A single image was generated successfully. Pushed once for each successful image.

**type** `string` *required*

Event type: `image_generation.partial_succeeded` or `image_edit.partial_succeeded`.

**created** `integer`

Unix timestamp (seconds) when the event was produced.

**model** `string`

Model name.

**image\_index** `integer` *required*

Image index, starting from 0, range \[0, n-1].

**url** `string` *required*

Image URL. Download the image and store it yourself.

**size** `string`

Actual image size, formatted as `WIDTHxHEIGHT`.

**output\_format** `string`

Image format: `png`, `jpeg`, or `webp`.

**revised\_prompt** `string`

The prompt actually used to generate this image. When prompt enhancement is on, this is the enhanced prompt; when off, it equals the `prompt` in the request.

```json Example theme={null}
{
  "type": "image_generation.partial_succeeded",
  "created": 1792308690,
  "model": "MiniMax-H3-Image",
  "image_index": 1,
  "url": "https://example.com/h3-image/output-1.jpg",
  "size": "2720x1536",
  "output_format": "jpeg",
  "revised_prompt": "An orange cat curled up asleep on a sunlit windowsill, a blurred city street outside the window, warm tones, film texture"
}
```

### partial\_failed

A single image failed or was withheld by the content safety check. Other images are not affected and continue to be pushed.

**type** `string` *required*

Event type: `image_generation.partial_failed` or `image_edit.partial_failed`.

**created** `integer`

Unix timestamp (seconds) when the event was produced.

**model** `string`

Model name.

**image\_index** `integer` *required*

Image index, starting from 0.

**code** `string` *required*

Internal error code, e.g. `1026`. See [Error Codes](https://platform.minimax.io/docs/api-reference/errorcode.md).

**message** `string` *required*

Error detail.

```json Example theme={null}
{
  "type": "image_generation.partial_failed",
  "created": 1792308691,
  "model": "MiniMax-H3-Image",
  "image_index": 2,
  "code": "1027",
  "message": "output image failed content safety check"
}
```

### completed

Pushed after all images are done when at least one image succeeded; it is then the last event in the stream. Carries usage and statistics for the request.

**type** `string` *required*

Event type: `image_generation.completed` or `image_edit.completed`.

**created** `integer`

Unix timestamp (seconds) when the event was produced.

**model** `string`

Model name.

**usage** `object`

Token usage of this request, used for billing.

**properties**

**generated\_images** `integer`

Number of images generated successfully, excluding images that failed or were withheld by the content safety check.

**total\_tokens** `integer`

Total tokens.

**input\_tokens** `integer`

Input tokens (text and reference images).

**output\_tokens** `integer`

Output tokens (generated images).

**input\_tokens\_details** `object`

Input token breakdown: `text_tokens` (text) and `image_tokens` (reference images).

**output\_tokens\_details** `object`

Output token breakdown: `image_tokens` (generated images).

**request\_id** `string`

Request trace ID for troubleshooting.

```json Example theme={null}
{
  "type": "image_generation.completed",
  "created": 1792308695,
  "model": "MiniMax-H3-Image",
  "usage": {
    "generated_images": 2,
    "total_tokens": 13022,
    "input_tokens": 4862,
    "output_tokens": 8160,
    "input_tokens_details": {"text_tokens": 4862, "image_tokens": 0},
    "output_tokens_details": {"image_tokens": 8160}
  },
  "request_id": "021792308678142a2c883cf675b9804d"
}
```

### error

The top-level error of the request; the stream ends after it. Pushed only when no image succeeded; the request is not billed and every `usage` field is 0:

* All images failed after generation was submitted: pushed after the `partial_failed` events for all `n` images. `error.http_code` is `422` if every image was withheld by the content safety check, `402` if every image failed due to insufficient balance, otherwise `500`
* The whole request failed before generation was submitted (e.g. the input failed the content safety check or a reference image could not be processed) after the response headers were returned: the `error` field is the same as `error` in the HTTP error response of a non-streaming request

The `error` event does not include `created` or `data`; the failure reason of each image is in the `partial_failed` events pushed before it.

**type** `string` *required*

Always `error`.

**error** `object` *required*

Error information.

**properties**

**type** `string`

Error type, e.g. `server_error`.

**message** `string`

Error detail; the trailing parenthesis holds the internal error code.

**http\_code** `string`

Corresponding HTTP status code as a string.

**usage** `object`

Token usage of this request; same structure as `usage` in the `completed` event, with every field 0.

**request\_id** `string`

Request trace ID for troubleshooting.

```json Example theme={null}
{
  "type": "error",
  "error": {
    "type": "server_error",
    "message": "internal error (1000)",
    "http_code": "500"
  },
  "usage": {
    "generated_images": 0,
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": {"text_tokens": 0, "image_tokens": 0},
    "output_tokens_details": {"image_tokens": 0}
  },
  "request_id": "021792308678142a2c883cf675b9804d"
}
```

## Full Example

With `n: 3` and `stream: true`, where the third image is withheld by the content safety check:

```bash Request (Text-to-Image) theme={null}
curl https://api.minimax.io/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  --no-buffer \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "size": "2720x1536",
    "n": 3,
    "stream": true
  }'
```

```bash Request (Image Edit) theme={null}
curl https://api.minimax.io/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  --no-buffer \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
    "images": [
      {"image_url": "https://example.com/cat.jpg"},
      {"image_url": "https://example.com/dog.png"}
    ],
    "n": 3,
    "stream": true
  }'
```

```text Response (Text-to-Image) theme={null}
event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","created":1792308690,"model":"MiniMax-H3-Image","image_index":1,"url":"https://example.com/h3-image/output-1.jpg","size":"2720x1536","output_format":"jpeg","revised_prompt":"An orange cat curled up asleep on a sunlit windowsill, a blurred city street outside the window, warm tones, film texture"}

event: image_generation.partial_failed
data: {"type":"image_generation.partial_failed","created":1792308691,"model":"MiniMax-H3-Image","image_index":2,"code":"1027","message":"output image failed content safety check"}

event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","created":1792308695,"model":"MiniMax-H3-Image","image_index":0,"url":"https://example.com/h3-image/output-0.jpg","size":"2720x1536","output_format":"jpeg","revised_prompt":"Warm afternoon light streams through a wooden window frame onto the sill, where an orange cat lies on its side basking in the sun, eyes half-closed, film grain"}

event: image_generation.completed
data: {"type":"image_generation.completed","created":1792308695,"model":"MiniMax-H3-Image","usage":{"generated_images":2,"total_tokens":13022,"input_tokens":4862,"output_tokens":8160,"input_tokens_details":{"text_tokens":4862,"image_tokens":0},"output_tokens_details":{"image_tokens":8160}},"request_id":"021792308678142a2c883cf675b9804d"}
```

```text Response (Image Edit) theme={null}
event: image_edit.partial_succeeded
data: {"type":"image_edit.partial_succeeded","created":1792308690,"model":"MiniMax-H3-Image","image_index":1,"url":"https://example.com/h3-image/output-1.jpg","size":"5440x3072","output_format":"jpeg","revised_prompt":"Replace the orange cat in image 1 with the Shiba Inu from image 2, sitting on the windowsill looking out, keeping the original lighting and background"}

event: image_edit.partial_failed
data: {"type":"image_edit.partial_failed","created":1792308691,"model":"MiniMax-H3-Image","image_index":2,"code":"1027","message":"output image failed content safety check"}

event: image_edit.partial_succeeded
data: {"type":"image_edit.partial_succeeded","created":1792308695,"model":"MiniMax-H3-Image","image_index":0,"url":"https://example.com/h3-image/output-0.jpg","size":"5440x3072","output_format":"jpeg","revised_prompt":"Replace the orange cat lying on the windowsill in image 1 with the Shiba Inu from image 2, lying down, with the windowsill, lighting and background unchanged"}

event: image_edit.completed
data: {"type":"image_edit.completed","created":1792308695,"model":"MiniMax-H3-Image","usage":{"generated_images":2,"total_tokens":80450,"input_tokens":47810,"output_tokens":32640,"input_tokens_details":{"text_tokens":24186,"image_tokens":23624},"output_tokens_details":{"image_tokens":32640}},"request_id":"021792308678142a2c883cf675b9804d"}
```

For a Python example that reads the stream, see [Image Generation Guide - Streaming Output](https://platform.minimax.io/docs/guides/image-generation.md#streaming-output).