MiniMax H3 文生图

接口

POST /jobs/createTask

完整 URL: https://modelfold.ai/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

使用 MiniMax-H3-Image 根据文本提示词生成图片。

提示词扩写默认开启，建议保持开启，以获得更好的出图效果。

输出尺寸

档位 + 画幅 —— resolution（默认 2K）决定尺寸档位，aspect_ratio 决定画幅。auto 由提示词改写模型根据内容挑选画幅（expand_prompt 为 false 时按 1:1）。

画幅	1K	2K	4K
1:1	1024×1024	2048×2048	4096×4096
5:4 / 4:5	1152×912 / 912×1152	2304×1824 / 1824×2304	4576×3648 / 3648×4576
4:3 / 3:4	1184×880 / 880×1184	2368×1760 / 1760×2368	4736×3552 / 3552×4736
3:2 / 2:3	1248×832 / 832×1248	2496×1664 / 1664×2496	5024×3360 / 3360×5024
16:9 / 9:16	1360×768 / 768×1360	2720×1536 / 1536×2720	5472×3072 / 3072×5472
21:9	1568×672	3136×1344	6272×2688

自定义尺寸 —— width 与 height（像素，各 1–8192），如 width: 1920, height: 1080。总像素 655,360–20,000,000、宽 : 高在 1:3–3:1 之间，输出严格等于该宽高。使用宽高时不能再传 resolution 和 aspect_ratio，不支持这种组合。

按哪个生效

|---|---| | 只传了其中一个 | 不允许：width 和 height 必须同时传 | | 都没传 | 按 resolution（默认 2K）和 aspect_ratio（默认 auto） | | 宽高与 resolution 或 aspect_ratio 同时传 | 不允许：请求会被拒绝 |

每个任务出一张图，PNG（默认）或 JPEG
结果地址约 14 天后失效，需要长期保存请自行转存

查询任务状态

使用 model=minimax-h3/text-to-image 提交任务后，可通过统一的查询接口查看进度并获取结果：

获取任务详情 — 了解如何查询任务状态并获取生成结果

TIP

生产环境中，建议使用 callBackUrl 参数接收生成完成的自动通知，而非轮询状态接口。

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成的模型名称。必填字段。 - 此端点必须使用 `minimax-h3/text-to-image` 默认值：`"minimax-h3/text-to-image"`。可选值：`minimax-h3/text-to-image`。示例：`minimax-h3/text-to-image`。
`callBackUrl`	`string`	否	接收生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当生成完成时，系统将向此 URL POST 任务状态和结果 - 回调包含生成的内容 URL 和任务信息 - 您的回调端点应接受包含结果的 JSON 负载的 POST 请求 - 或者，使用获取任务详情端点轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法示例：`https://your-domain.com/api/callback`。
`input`	`object`	是	生成任务的输入参数
`input.prompt`	`string`	是	必填。文本提示词，1–5000 字符，中英文均可。 minLength: `1`. maxLength: `5000`. 示例：`雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉`。
`input.aspect_ratio`	`string`	否	输出画幅。可选，默认 `auto`。 - `auto`：由提示词改写模型按内容挑选画幅；`expand_prompt` 为 `false` 时 `auto` 按 `1:1` - 各画幅、各档位的输出尺寸见上方说明 - 不能与 `width`/`height` 同时传可选值：`auto` / `1:1` / `5:4` / `4:3` / `3:2` / `16:9` / `21:9` / `4:5` / `3:4` / `2:3` / `9:16`。示例：`auto`。
`input.seed`	`integer`	否	随机种子，0–2147483647。可选，不传则随机，结果中会返回实际使用的 seed。开启提示词改写时每次改写稿不同，只有 `expand_prompt` 为 `false` 时才能用同一 seed 复现结果。 minimum: `0`. maximum: `2147483647`. 示例：`7`。
`input.expand_prompt`	`boolean`	否	是否在出图前把提示词改写成详细的英文描述。可选。提示词扩写默认开启，建议保持开启，以获得更好的出图效果。 - `true`（默认，建议）：把提示词改写成详细的英文描述；`aspect_ratio` 为 `auto` 时还会由改写模型挑选画幅 - `false`：按原文直接出图默认值：`true`。示例：`true`。
`input.output_format`	`string`	否	输出图片格式。可选，默认 `png`。JPEG 质量 95，体积小很多；4K PNG 文件很大，需要小文件时请用 JPEG。默认值：`"png"`。可选值：`png` / `jpeg`。示例：`png`。

请求示例

bash

curl -X POST "https://modelfold.ai/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3/text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }
}'

python

import os
import requests

resp = requests.post(
    "https://modelfold.ai/v1/jobs/createTask",
    headers={
        "Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3/text-to-image",
        "callBackUrl": "https://your-domain.com/api/callback",
        "input": {
            "prompt": "雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉",
            "aspect_ratio": "16:9",
            "resolution": "2K",
            "output_format": "png",
        },
    },
)
print(resp.json())

javascript

const resp = await fetch("https://modelfold.ai/v1/jobs/createTask", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MODELFOLD_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "minimax-h3/text-to-image",
    "callBackUrl": "https://your-domain.com/api/callback",
    "input": {
      "prompt": "雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "output_format": "png"
    }
  }),
});
console.log(await resp.json());

package main

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

func main() {
	body := strings.NewReader(`{"model":"minimax-h3/text-to-image","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉","aspect_ratio":"16:9","resolution":"2K","output_format":"png"}}`)
	req, _ := http.NewRequest("POST", "https://modelfold.ai/v1/jobs/createTask", body)
	req.Header.Set("Authorization", "Bearer " + os.Getenv("MODELFOLD_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = "{\"model\":\"minimax-h3/text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉\",\"aspect_ratio\":\"16:9\",\"resolution\":\"2K\",\"output_format\":\"png\"}}";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://modelfold.ai/v1/jobs/createTask"))
            .header("Authorization", "Bearer " + System.getenv("MODELFOLD_API_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}

php

<?php
$ch = curl_init('https://modelfold.ai/v1/jobs/createTask');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv("MODELFOLD_API_KEY"),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{"model":"minimax-h3/text-to-image","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉","aspect_ratio":"16:9","resolution":"2K","output_format":"png"}}',
]);
echo curl_exec($ch);
curl_close($ch);

csharp

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("POST"), "https://modelfold.ai/v1/jobs/createTask");
req.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("MODELFOLD_API_KEY"));
req.Content = new StringContent("{\"model\":\"minimax-h3/text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉\",\"aspect_ratio\":\"16:9\",\"resolution\":\"2K\",\"output_format\":\"png\"}}", Encoding.UTF8, "application/json");
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

json

{
  "model": "minimax-h3/text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }
}

响应

200 —

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient balance; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `401` / `402` / `404` / `422` / `429` / `455` / `500` / `501` / `505`。示例：`200`。
`msg`	`string`	否	Response message, error description when failed 示例：`success`。
`data`	`object`	是	—
`data.taskId`	`string`	否	Task ID, can be used with Get Task Details endpoint to query task status
`data.recordId`	`string`	否	Record ID, can be used to get the record details

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "",
    "recordId": ""
  }
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	请读取响应字段，并根据返回状态处理后重试。
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

回调

onImageGenerated

回调地址：{$request.body#/callBackUrl}（即请求体里的 callBackUrl）。

任务成功或失败时发送回调。

回调体参数

参数	类型	必填	说明
`code`	`integer`	否	200 表示成功；其他值表示失败（例如 501）。可选值：`200` / `501`。示例：`200`。
`msg`	`string`	否	状态消息示例：`Playground task completed successfully.`。
`data`	`object`	否	—
`data.completeTime`	`integer`	否	任务完成时间，Unix 毫秒时间戳示例：`1786417135000`。
`data.costTime`	`integer`	否	处理耗时（秒），成功和失败回调都会返回。示例：`165`。
`data.createTime`	`integer`	否	任务创建时间，Unix 毫秒时间戳示例：`1786416968000`。
`data.model`	`string`	否	图片生成使用的模型示例：`minimax-h3/text-to-image`。
`data.param`	`string`	否	创建任务时提交的参数，JSON 字符串格式示例：`{"input": "{\"prompt\": \"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉\", \"aspect_ratio\": \"16:9\", \"resolution\": \"2K\", \"output_format\": \"png\"}", "callBackUrl": "https://your-domain.com/api/callback", "model": "minimax-h3/text-to-image"}`。
`data.resultJson`	`string`	否	图片生成结果，JSON 字符串格式。resultUrls 为生成图片的 URL 列表。仅在 state 为 success 时出现。示例：`{"resultUrls": ["https://tempfile.aiquickdraw.com/js/y1/9ef89580655a9e961ad0adb2.png"]}`。
`data.state`	`string`	否	任务状态可选值：`success` / `fail`。示例：`success`。
`data.taskId`	`string`	否	任务 ID 示例：`b0e3febbf194d27a345de523d3321555`。
`data.updateTime`	`integer`	否	完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。示例：`1786417135000`。
`data.failCode`	`string`	否	失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。示例：`500`。
`data.failMsg`	`string`	否	失败原因，仅在 state 为 fail 时出现。示例：`<error detail>`。

成功

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "b0e3febbf194d27a345de523d3321555",
    "model": "minimax-h3/text-to-image",
    "state": "success",
    "param": "{\"input\": \"{\\\"prompt\\\": \\\"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉\\\", \\\"aspect_ratio\\\": \\\"16:9\\\", \\\"resolution\\\": \\\"2K\\\", \\\"output_format\\\": \\\"png\\\"}\", \"callBackUrl\": \"https://your-domain.com/api/callback\", \"model\": \"minimax-h3/text-to-image\"}",
    "resultJson": "{\"resultUrls\": [\"https://tempfile.aiquickdraw.com/js/y1/9ef89580655a9e961ad0adb2.png\"]}",
    "completeTime": 1786417135000,
    "createTime": 1786416968000,
    "costTime": 165,
    "updateTime": 1786417135000
  }
}

失败

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "b0e3febbf194d27a345de523d3321555",
    "model": "minimax-h3/text-to-image",
    "state": "fail",
    "param": "{\"input\": \"{\\\"prompt\\\": \\\"雨夜里温馨的书店咖啡馆，暖光透过橱窗，一只橘猫趴在书堆上睡觉\\\", \\\"aspect_ratio\\\": \\\"16:9\\\", \\\"resolution\\\": \\\"2K\\\", \\\"output_format\\\": \\\"png\\\"}\", \"callBackUrl\": \"https://your-domain.com/api/callback\", \"model\": \"minimax-h3/text-to-image\"}",
    "failCode": "500",
    "failMsg": "<error detail>",
    "completeTime": 1786417135000,
    "createTime": 1786416968000,
    "costTime": 165,
    "updateTime": 1786417135000
  }
}

MiniMax H3 文生图 ​

接口 ​

输出尺寸 ​

查询任务状态 ​

相关资源 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — ​

500 — Server error. ​

回调 ​

onImageGenerated ​

MiniMax H3 文生图

接口

输出尺寸

查询任务状态

相关资源

请求参数

请求体 (application/json)

请求示例

响应

200 —

500 — Server error.

回调

onImageGenerated