Streaming Events

With stream: true, the Text-to-Image and Image Edit 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:

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.

string

required

Event type: image_generation.partial_succeeded or image_edit.partial_succeeded.

integer

Unix timestamp (seconds) when the event was produced.

string

Model name.

integer

required

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

string

required

Image URL. Download the image and store it yourself.

string

Actual image size, formatted as WIDTHxHEIGHT.

string

Image format: png, jpeg, or webp.

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.

Example

{
  "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.

string

required

Event type: image_generation.partial_failed or image_edit.partial_failed.

integer

Unix timestamp (seconds) when the event was produced.

string

Model name.

integer

required

Image index, starting from 0.

string

required

Internal error code, e.g. 1026. See Error Codes.

string

required

Error detail.

Example

{
  "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.

string

required

Event type: image_generation.completed or image_edit.completed.

integer

Unix timestamp (seconds) when the event was produced.

string

Model name.

object

Token usage of this request, used for billing.

Show properties

integer

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

integer

Total tokens.

integer

Input tokens (text and reference images).

integer

Output tokens (generated images).

object

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

object

Output token breakdown: image_tokens (generated images).

string

Request trace ID for troubleshooting.

Example

{
  "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.

string

required

Always error.

object

required

Error information.

Show properties

string

Error type, e.g. server_error.

string

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

string

Corresponding HTTP status code as a string.

object

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

string

Request trace ID for troubleshooting.

Example

{
  "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:

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
  }'

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
  }'

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"}

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.

Using the API

Text

Video

Image

Speech

File

Models

Legacy APIs

Event Types

partial_succeeded

partial_failed

completed

error

Full Example

​Event Types

​partial_succeeded

​partial_failed

​completed

​error

​Full Example

Event Types

partial_succeeded

partial_failed

completed

error

Full Example