Create an image using a text prompt

Table of contents

March 17, 2025 (May 13, 2026)

  1. Model Comparison Matrix
  2. Request Headers
  3. Request Body
  4. Parameters
  5. Responses
  6. Model
  7. Examples
  8. Try It

Use hailuoai.video account to retrieve list of generated images, see Setup MiniMax for details.

Model Comparison Matrix
Model Resolutions Aspect Ratios Ref Images @-mention
image-01 HD 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9 1 via characterFileId —
nano-banana-2 512P, 1K, 2K, 4K auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 1-14 via referenceFileId1…14 ✓
nano-banana-pro 1K, 2K, 4K auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 1-14 via referenceFileId1…14 ✓
gpt-image-1.5 Low, Medium, High auto (default), 1:1, 3:2, 2:3 1-3 via referenceFileId1…3 —
gpt-image-2 1K, 2K, 4K 16:9 (default), 21:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 1-16 via referenceFileId1…16 ✓
seedream-4.5 2K, 4K auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 1-14 via referenceFileId1…14 ✓
seedream-5.0 2K, 3K auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 1-14 via referenceFileId1…14 ✓
midjourney-v7 n/a auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 1-14 via referenceFileId1…14 —
midjourney-niji7 n/a auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 1-14 via referenceFileId1…14 —

Models with @-mention support let you reference uploaded images by slot inside the prompt (e.g. "@Image1 with bokeh background"). The token is @Image<N> where <N> is the slot from referenceFileId<N>. Case-insensitive: @IMAGE1, @image1, @ImAgE001 all canonicalize to @Image1. Unsupported models reject prompts containing @Image<N> tokens.

💲 Credits estimator

Credits are charged per image. Actual costs may change, see hailuoai.video for current pricing.

Model Resolution Credits per image Quantity
image-01 HD 1 1-4
nano-banana-2 512P, 1K 4 1-4
nano-banana-2 2K 5 1-4
nano-banana-2 4K 8 1-4
nano-banana-pro 1K, 2K 6 1-4
nano-banana-pro 4K 10 1-4
gpt-image-1.5 Low 4 1-4
gpt-image-1.5 Medium 8 1-4
gpt-image-1.5 High 15 1-4
gpt-image-2 (quality low) 1K 2 1-4
gpt-image-2 (quality low) 2K 5 1-4
gpt-image-2 (quality low) 4K 10 1-4
gpt-image-2 (quality medium) 1K 8 1-4
gpt-image-2 (quality medium) 2K 20 1-4
gpt-image-2 (quality medium) 4K 40 1-4
gpt-image-2 (quality high) 1K 30 1-4
gpt-image-2 (quality high) 2K 80 1-4
gpt-image-2 (quality high) 4K 160 1-4
seedream-4.5 2K, 4K 4 1-4
seedream-5.0 2K, 3K 4 1-4
midjourney-v7 n/a 3 4 (fixed)
midjourney-niji7 n/a 3 4 (fixed)

To retrieve generated image(s), use:

https://api.useapi.net/v1/minimax/images/create

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
    "account": "Optional MiniMax API account",
    "prompt": "Required text prompt",
    "promptOptimization": true,
    "model": "nano-banana-pro",
    "aspectRatio": "16:9",
    "resolution": "2K",
    "referenceFileId1": "user:…-minimax:…-file:…",
    "referenceFileId2": "user:…-minimax:…-file:…",
    "quantity": 2,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
Parameters

  • account is optional when only one account configured. However, if you have multiple accounts configured, this parameter becomes required.

  • prompt is required, describe your image. Maximum length depends on model: 1,250 characters for image-01, gpt-image-1.5, gpt-image-2, seedream-4.5; 5,000 characters for nano-banana-2, nano-banana-pro, seedream-5.0, midjourney-v7, midjourney-niji7.

    @-mention syntax (supported by gpt-image-2, nano-banana-pro, nano-banana-2, seedream-4.5, seedream-5.0): use @Image1…@Image16 in the prompt to reference uploaded images by slot — @Image1 binds to referenceFileId1, @Image2 to referenceFileId2, etc. Tokens are case-insensitive (@IMAGE1, @image1, @ImAgE001 all canonicalize to @Image1). Models without @-mention support (image-01, gpt-image-1.5, midjourney-v7, midjourney-niji7) reject prompts containing @Image<N> tokens with a 400.

  • promptOptimization is optional. Supported values: true (default), false.

  • model is optional. Supported values:
    • image-01 (default) - Character-focused image generation with HD resolution. Supports character reference via characterFileId.
    • nano-banana-2 - Image generation (512P/1K/2K/4K) with up to 14 reference images. Lower cost flash variant.
    • nano-banana-pro - High-resolution image generation (1K/2K/4K) with up to 14 reference images.
    • gpt-image-1.5 - High-resolution image generation (Low/Medium/High) with up to 3 reference images and limited aspect ratios.
    • gpt-image-2 - GPT Image 2 (1K/2K/4K, quality = low/medium/high) with 10 aspect ratios and up to 16 reference images via referenceFileId1…16 (with @-mention support).
    • seedream-4.5 - High-resolution image generation (2K/4K) with up to 14 reference images.
    • seedream-5.0 - High-resolution image generation (2K/3K) with up to 14 reference images.
    • midjourney-v7 - Midjourney V7 image generation. Always generates 4 images per request (ignores quantity). Up to 14 reference images.
    • midjourney-niji7 - Midjourney NiJi 7 anime-focused image generation. Always generates 4 images per request (ignores quantity). Up to 14 reference images.
  • resolution is optional, model-specific.
    • image-01: Only HD supported (default).
    • nano-banana-2: 512P (default), 1K, 2K, 4K.
    • nano-banana-pro: 1K (default), 2K, 4K.
    • gpt-image-1.5: Low (default), Medium, High.
    • gpt-image-2: 1K (default), 2K, 4K.
    • seedream-4.5: 2K (default), 4K.
    • seedream-5.0: 2K (default), 3K.
    • midjourney-v7: Not applicable (no resolution parameter).
    • midjourney-niji7: Not applicable (no resolution parameter).
  • aspectRatio is optional, model-specific.
    • image-01: 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9.
    • nano-banana-2: auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9.
    • nano-banana-pro: auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9.
    • gpt-image-1.5: auto (default), 1:1, 3:2, 2:3.
    • gpt-image-2: 16:9 (default), 21:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16. (No auto — model doesn’t accept it.)
    • seedream-4.5: auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9.
    • seedream-5.0: auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16.
    • midjourney-v7: auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16.
    • midjourney-niji7: auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16.

  • quality is optional, only for gpt-image-2. Supported values: low (default), medium, high. Credit cost varies by quality × resolution — see the credits estimator above. Other models reject the quality parameter with a 400.

  • characterFileId is optional, only for image-01:
    • fileID of the character image uploaded via POST /files. Upload a clear front-facing photo for best result. Avoid side angles and obstructions.
    • Cannot be used with other models (use referenceFileId1…16 instead).
  • referenceFileId1 … referenceFileId16 are optional, for all models except image-01:
    • fileID(s) of reference images uploaded via POST /files.
    • gpt-image-2: Supports 1-16 reference images (referenceFileId1…16). Supports @-mention syntax in prompt.
    • nano-banana-2, nano-banana-pro, seedream-4.5, seedream-5.0: Supports 1-14 reference images. Supports @-mention syntax in prompt.
    • midjourney-v7, midjourney-niji7: Supports 1-14 reference images. Does not support @-mention syntax — @ImageN tokens in prompt return 400.
    • gpt-image-1.5: Supports 1-3 reference images (referenceFileId1…3 only). Does not support @-mention syntax.
    • image-01: Use characterFileId instead.
    • Slots must be contiguous starting at 1 — sending referenceFileId3 without referenceFileId1/2 returns 400.
    • All reference files must belong to the same account.

  • quantity is optional. Supported range: 1…4, default 1. Note: midjourney-v7 and midjourney-niji7 always generate exactly 4 images per request. The quantity parameter is ignored for these models.

  • replyUrl is optional. Callback URL for job completion notifications. API will call the provided replyUrl once MiniMax image completed or failed. Maximum length 1024 characters. We recommend using sites like webhook.site to test callback URL functionality.

  • replyRef is optional, place here your reference id which will be stored and returned along with this MiniMax image response/result. Maximum length 1024 characters.
Responses

  • 200 OK

    Use returned in array imageIds values to retrieve image status and results using GET images/imageId. Check videoURL and/or downloadURL (paid account, no watermarks) for generated image with the status 2 (Completed).

    If you specify the optional parameter replyUrl the API will call the provided replyUrl with image progress updates until the image is complete or fails.

    {
    "id": "<image_id_1>",
    "task": {
        "batchID": "<batch_id>",
        "videoIDs": [
            "<image_id_1>",
            "<image_id_2>",
            "<image_id_3>",
            "<image_id_4>"
        ]
    },
    "isFirstGenerate": false,
    "imageIds": [
        "user:<user>-minimax:<account>-image:<image_id_1>",
        "user:<user>-minimax:<account>-image:<image_id_2>",
        "user:<user>-minimax:<account>-image:<image_id_3>",
        "user:<user>-minimax:<account>-image:<image_id_4>"
    ],
    "replyUrl": "https://webhook.site/…",
    "replyRef": "2025-03-11T17:23:05.795Z",
    "code": 200
}

  • 400 Bad Request

    {
  "error": "<Error message>"
}

  • 401 Unauthorized

    {
  "error": "Unauthorized"
}

  • 412 Insufficient credits

    Insufficient credits. Please recharge to get more credits or try again next day.

    {
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}

  • 422 Unprocessable Content

    Moderated message.

    {
  "error": "Your prompt is too short, please provide more details"
}

  • 429 Too Many Requests

    Wait in a loop for at least 10..30 seconds and retry again.

    {
    "error": "There are currently multiple tasks in the queue, and only <number> can be generated at once"
}

  • 596 Pending mod message

    Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord support channel or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours.

    {
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
Model 
{ // TypeScript, all fields are optional
  id: string
  task: {
    batchID: string
    videoIDs: string[]
  }
  isFirstGenerate: boolean
  imageIds: string[]
  replyUrl: string
  replyRef: string
  code: number
}
Examples 
  • curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/images/create" \
     -d '{"prompt": "…"}'

  • const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/images/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

  • import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/images/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
Try It