Text-to-Image

curl --request POST \
  --url https://api.minimax.io/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "MiniMax-H3-Image",
  "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
  "size": "2720x1536",
  "n": 2,
  "response_format": "url"
}
'

import requests

url = "https://api.minimax.io/v1/images/generations"

payload = {
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "size": "2720x1536",
    "n": 2,
    "response_format": "url"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'MiniMax-H3-Image',
    prompt: 'An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture',
    size: '2720x1536',
    n: 2,
    response_format: 'url'
  })
};

fetch('https://api.minimax.io/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.minimax.io/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'MiniMax-H3-Image',
    'prompt' => 'An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture',
    'size' => '2720x1536',
    'n' => 2,
    'response_format' => 'url'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.minimax.io/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.minimax.io/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.minimax.io/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}"

response = http.request(request)
puts response.read_body

{
  "created": 1792308678,
  "data": [
    {
      "url": "https://example.com/h3-image/output-0.jpg",
      "size": "2720x1536",
      "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, its fur rimmed with golden light, blurred indoor plants in the background, film grain, soft warm tones"
    },
    {
      "error": {
        "code": "1027",
        "message": "output image failed content safety check"
      }
    }
  ],
  "output_format": "jpeg",
  "usage": {
    "generated_images": 1,
    "total_tokens": 7254,
    "input_tokens": 3174,
    "output_tokens": 4080,
    "input_tokens_details": {
      "text_tokens": 3174,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "image_tokens": 4080
    }
  },
  "request_id": "021792308678142a2c883cf675b9804d"
}

POST

images

generations

Text-to-Image

curl --request POST \
  --url https://api.minimax.io/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "MiniMax-H3-Image",
  "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
  "size": "2720x1536",
  "n": 2,
  "response_format": "url"
}
'

import requests

url = "https://api.minimax.io/v1/images/generations"

payload = {
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "size": "2720x1536",
    "n": 2,
    "response_format": "url"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'MiniMax-H3-Image',
    prompt: 'An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture',
    size: '2720x1536',
    n: 2,
    response_format: 'url'
  })
};

fetch('https://api.minimax.io/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.minimax.io/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'MiniMax-H3-Image',
    'prompt' => 'An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture',
    'size' => '2720x1536',
    'n' => 2,
    'response_format' => 'url'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.minimax.io/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.minimax.io/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.minimax.io/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"MiniMax-H3-Image\",\n  \"prompt\": \"An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture\",\n  \"size\": \"2720x1536\",\n  \"n\": 2,\n  \"response_format\": \"url\"\n}"

response = http.request(request)
puts response.read_body

{
  "created": 1792308678,
  "data": [
    {
      "url": "https://example.com/h3-image/output-0.jpg",
      "size": "2720x1536",
      "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, its fur rimmed with golden light, blurred indoor plants in the background, film grain, soft warm tones"
    },
    {
      "error": {
        "code": "1027",
        "message": "output image failed content safety check"
      }
    }
  ],
  "output_format": "jpeg",
  "usage": {
    "generated_images": 1,
    "total_tokens": 7254,
    "input_tokens": 3174,
    "output_tokens": 4080,
    "input_tokens_details": {
      "text_tokens": 3174,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "image_tokens": 4080
    }
  },
  "request_id": "021792308678142a2c883cf675b9804d"
}

Supported models: MiniMax-H3-Image, MiniMax-H3-Image-Highspeed; both take the same parameters and limits.

The server waits up to 600 seconds; set the client timeout to at least 600 seconds. This endpoint is not idempotent: once a request is sent, the server finishes generation and charges for successful images even if the client times out or disconnects, and a retry generates and charges again. With the OpenAI SDK, set max_retries=0 to turn off its default automatic retries.

Authorizations

Authorization

string

header

required

HTTP: Bearer Auth

Security Scheme Type: http
HTTP Authorization Scheme: Bearer API_key, used to verify account information, can be found in Account Management>API Keys.

Body

application/json

model

enum<string>

required

Model name. Supported values: MiniMax-H3-Image, MiniMax-H3-Image-Highspeed; both take the same parameters and limits

Available options:

MiniMax-H3-Image,

MiniMax-H3-Image-Highspeed

prompt

string

required

Text description of the image, up to 32000 characters (counted as Unicode characters, excluding leading and trailing whitespace); an empty or whitespace-only prompt returns 400. With prompt enhancement disabled (disable_prompt_enhanced is true), the model reads only about the first 4096 tokens; the rest has no effect.

Maximum string length: 32000

disable_prompt_enhanced

boolean

default:false

Whether to disable prompt enhancement, default false (enhancement on); see data[].revised_prompt for the enhanced prompt.

When true, the original prompt is used and the request must specify the aspect ratio in one of two ways:

size is WIDTHxHEIGHT
size is omitted or auto, and aspect_ratio is X:Y (area is optional, default 4K)

If size is not WIDTHxHEIGHT and aspect_ratio is omitted or auto, 400 is returned.

integer

default:1

Number of images, range [1, 10], default 1.

Required range: 1 <= x <= 10

size

string

default:auto

Output image size, default auto; see Output Size. Use one of two forms:

WIDTHxHEIGHT: set the width and height directly, e.g. 2720x1536; both are positive integers. The area (width × height) must be between 655,360 and 20,000,000 pixels and the aspect ratio between 1:3 and 3:1, bounds inclusive; otherwise 400 is returned, and the size is never scaled or rounded. In this form, do not set aspect_ratio or area (not even to auto); otherwise 400 is returned
auto or omitted: width and height are determined by aspect_ratio (default auto) and area (default 4K); either can be set on its own

aspect_ratio

string

default:auto

Output aspect ratio, default auto.

Cannot be set when size is WIDTHxHEIGHT (not even as auto); otherwise 400 is returned
Must be X:Y when size is omitted or auto and disable_prompt_enhanced is true; omitting it or passing auto returns 400

Values:

auto: decided by prompt enhancement based on the content
X:Y: X and Y are integers from 1 to 300 and the ratio is between 1:3 and 3:1 (bounds inclusive), e.g. 16:9, 3:4, 21:9, 3:1

Example:

"16:9"

area

enum<string>

default:4K

Output area level, default 4K. Can only be set when size is omitted or auto; setting it while size is WIDTHxHEIGHT returns 400.

1K, 2K and 4K target areas of 1024 × 1024, 2048 × 2048 and 4096 × 4096 pixels. The server calculates width and height from the aspect ratio; for example, 2K with 16:9 outputs 2720 × 1536. See data[].size for each image's actual width and height.

Available options:

1K,

2K,

4K

output_format

enum<string>

default:jpeg

Output image format, default jpeg. Available values: png, jpeg, jpg, webp. jpg is equivalent to jpeg; output_format in the response is returned as jpeg.

Available options:

png,

jpeg,

jpg,

webp

response_format

enum<string>

default:url

Return format, default url.

url: image URL. Download the image and store it yourself; the URL is not guaranteed to remain available
b64_json: Base64-encoded image data, not supported with streaming

Total output area (n × width × height) limits for b64_json; exceeding returns 400 (with size = auto, each image counts as its area level, e.g. 4096 × 4096 for 4K):

`output_format`	Total area limit	Example
`png`	20,000,000 px	1 image of any size
`jpeg` / `webp`	80,000,000 px	Up to 4 images at `4K`, or 10 at `2K`

Available options:

url,

b64_json

stream

boolean

default:false

Whether to stream results, default false. When enabled, the response is text/event-stream (SSE), and only response_format = url is supported:

One event is pushed as each image finishes: image_generation.partial_succeeded on success, image_generation.partial_failed on failure. Events are pushed in completion order; use image_index to match images
image_generation.completed is pushed after all images finish, with usage and request_id
After the response headers are sent, an error event is pushed if all images fail or the request fails before generation is submitted
Errors before the response headers are sent (invalid parameters, authentication, rate limiting, insufficient balance, etc.) are returned as regular HTTP errors, the same as non-streaming calls; check the HTTP status code before parsing SSE

See Streaming Events for event structures.

output_compression

integer

default:95

Compression quality, range [0, 100], default 95; higher values give better quality and larger files. Only applies to jpeg / webp and is ignored for png; values outside the range return 400.

Required range: 0 <= x <= 100

Response

Returns application/json when stream is false (default). When stream is true, returns text/event-stream (SSE); the data of each event is JSON, defined under the text/event-stream response. See Streaming Events for event details and a full example.

created

integer

Time the response was generated, as a Unix timestamp in seconds.

data

object[]

Images, always n items in image order (matching image_index in streaming events). Successful items contain url (or b64_json), size and revised_prompt; failed items, including those withheld by the content safety check, contain only error.

If at least one image succeeds, the HTTP status is 200, so check data[].error for every item; if all images fail, a 402, 422 or 500 error response is returned. Only successful images are charged.

Show child attributes

output_format

enum<string>

Format of the generated images.

Available options:

png,

jpeg,

webp

usage

object

Token usage of this request, counting successful images only; billing is based on it. total_tokens is the sum of input_tokens and output_tokens.

Show child attributes

request_id

string

Request ID (the trace ID). Provide it when reporting an issue.

Using the API

Text

Video

Image

Speech

File

Models

Legacy APIs

Text-to-Image

Authorizations

Body

Response