MiniMax H3 Image 圖像生成 | ToAPIs Documentation

POST

/v1/images/generations

中國大陸用戶請注意： 中國大陸用戶請使用 https://toapis.cn 作為接口地址（Base URL）。文檔示例中的 https://toapis.com 請替換為 https://toapis.cn。

使用 minimax-h3-image 生成圖片, 或傳入參考圖進行編輯. 接口先返回任務 id, 再通過圖片任務狀態獲取結果.

Authorizations

Authorizationstring請求頭必填

使用平台訪問令牌, 請求頭格式為 Authorization: Bearer <token>. 令牌可在所在站點的控制台管理.

Body

請求類型為 application/json. 以下模型選項均可在請求體頂層傳入.

modelstring請求體必填預設值: minimax-h3-image

固定為 minimax-h3-image.

promptstring請求體必填

文字描述或編輯指令. 去除首尾空白後須包含 1-32000 個 Unicode 字符, 不能僅包含空白.

ninteger請求體預設值: 1

請求生成的圖片數量, 範圍為 1-10. 實際成功數量可能小於請求數量.

sizestring請求體預設值: auto

省略或設為 auto 時, 使用 resolution 和 aspect_ratio 決定尺寸. 也可傳 1024x1024 等顯式像素尺寸, 寬高為正整數, 總像素範圍為 655360-20000000, 寬高比須在 1:3 到 3:1 之間.

顯式像素尺寸不能同時傳 resolution 或 aspect_ratio, 即使後者為 auto 也不允許. 此時不補默認 4K.

兼容 16:9 等比例寫法, 等價於 aspect_ratio. 若兩個字段都填寫比例, 必須一致. 分辨率檔位請使用 resolution, 不要填寫 size: "4K".

aspect_ratiostring請求體預設值: auto

支持 auto 或 寬:高 比例, 如 1:1, 4:3, 16:9. 寬高分量分別為 1-300 的整數, 比例須在 1:3 到 3:1 之間. 不能與顯式像素 size 同時使用.

resolutionstring請求體預設值: 4K

僅支持大寫 1K, 2K, 4K. 這是分辨率檔位, 不是固定寬高, 實際尺寸以結果的 size 為準. 不能與顯式像素 size 同時使用.

image_urlsstring[]請求體

可選的參考圖 URL 列表, 最多 16 張. 使用可訪問的 HTTP(S) URL, 不允許 URL 內嵌用戶名或密碼, 不支持 Base64 或 data URI. 傳入參考圖時按編輯處理, 始終開啟提示詞增強.

地址須可由圖片處理服務訪問, 不能依賴本地網絡或瀏覽器登錄狀態. 瀏覽器中能打開圖片不代表編輯一定成功; 提交後仍須檢查最終任務狀態和錯誤信息.

output_formatstring請求體預設值: jpeg

支持 jpeg, jpg, png, webp. jpg 等價於 jpeg.

response_formatstring請求體預設值: url

僅支持 url. 結果中的圖片 URL 在任務完成後返回, 不在提交響應中返回圖片內容.

output_compressioninteger請求體預設值: 95

範圍為 0-100, 數值越大畫質越高, 文件通常越大. 僅對 JPEG 和 WebP 生效, PNG 忽略此選項.

disable_prompt_enhancedboolean請求體預設值: false

是否關閉提示詞增強. 僅純文生圖可以設為 true, 且必須同時提供顯式像素 size 或固定比例. 傳入參考圖時不能設為 true.

aigc_watermarkboolean請求體預設值: false

是否添加可見 AIGC 水印. 此開關不控制圖片文件元數據中的標識.

webhookstring請求體

可選的任務完成回調地址, 詳見任務 Webhook.

不支持的參數

不要傳入 area, mask, mask_url, background, quality, partial_images, preview, previous_task_id, image_size, seed, watermark, prompt_extend, 包括同名 metadata 字段. 分辨率使用 resolution, 可見水印使用 aigc_watermark.

不支持 stream=true, Base64 輸入或輸出及 multipart 文件上傳. 請勿套用其他圖片模型的參數或默認值.

請求示例

curl --request POST \
  --url 'https://toapis.com/v1/images/generations' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "一座臨海的小屋, 水彩插畫風格",
    "n": 1,
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "response_format": "url"
  }'

顯式像素尺寸示例, 不再傳分辨率或比例:

{
  "model": "minimax-h3-image",
  "prompt": "一座臨海的小屋, 水彩插畫風格",
  "size": "1536x1024",
  "n": 1,
  "output_format": "webp",
  "output_compression": 90
}

提交響應

以下僅為響應結構示例:

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "minimax-h3-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1794355200
}

保存 id, 通過 GET /v1/images/generations/{task_id} 查詢; 也可使用 GET /v1/tasks/{task_id}. 輪詢至少間隔 5-10 秒並加入抖動, 遇到 429 時遵循 Retry-After. 本地停止等待不代表任務已取消, 請繼續查詢原任務, 避免重複提交.

結果與計費

result.data 只包含成功圖片, 每項的 image_index 是從 0 開始的原始張序, 不是成功數組的下標. size, output_format, revised_prompt 描述該圖片的實際結果.
部分成功時, result.failed_images 包含失敗項的 image_index 和 error; 全部成功時省略該字段. completed 不保證請求的所有圖片都成功.
result.request_id 是結果追蹤標識, 不能替代任務 id 查詢.
usage.generated_images 表示實際成功圖片數量, 在有效的已結算用量中返回. 費用按實際文本輸入, 圖片輸入和圖片輸出 tokens 分別計算, 不按請求 n 乘固定單價.
當前售價通過控制台報價查詢, 最終金額以 billing.status=settled 時的 billing 為準. 不要把預扣金額或缺失用量當成最終消費.

完整響應和結算字段見圖片任務狀態.