MiniMax H3 Image

使用标准版 minimax-h3-image 或极速版 minimax-h3-image-highspeed 进行文生图与参考图编辑。独立提示词增强模型为 minimax-h3-image-context-ir，只返回增强文本，不生成图片。

定价与积分

以下单位为人民币元／百万 Token，适用账户价格组倍率。

模型	文本输入	图片输入	图片输出
标准版	19.50	13.00	32.50
极速版	19.50	26.00	65.00
独立提示词增强	19.50	—	—

生图使用返回的文本输入、图片输入、图片输出 Token 明细；用量已只包含成功图片，并包含内置增强的折算费用，不再乘以图片数量。独立增强仅按 usage.input_tokens 计费，不重复计算输出或思考费用。

4K 限时优惠

北京时间 2026-11-18 00:00 前发出的请求（不含结束时刻），所有成功图片实际面积均达到 16,600,000 像素时，整次请求费用五折。以请求向上游发出的时间锁定时间资格，以返回的实际尺寸判定面积；混合合格／不合格尺寸或尺寸缺失进入账单核对。独立提示词增强不参加活动，截止后恢复常规价。

文生图与图片编辑

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "input": {
      "prompt": "清晨阳光照进安静的阅览室",
      "area": "2K",
      "aspect_ratio": "16:9",
      "n": 2,
      "nsfw_checker": true
    }
  }'

不传 input.image_urls 为文生图；传入 1–16 张参考图 URL 为图片编辑。callback_url 可选，位于请求顶层。

{
  "model": "minimax-h3-image-highspeed",
  "input": {
    "prompt": "保留商品主体，把背景换成明亮的摄影棚",
    "image_urls": ["https://your-storage.example/product.png"],
    "size": "2048x2048",
    "n": 1,
    "output_format": "png"
  }
}

输入参数

字段	说明
`prompt`	必填，去掉首尾空白后为 1–32,000 个 Unicode 字符。
`nsfw_checker`	可选的平台安全检查布尔参数，三个模型均默认 `true`；仅有相应账户权限时可设为 `false`，无权限时仍保持开启。
`image_urls`	可选，1–16 个公开 HTTP(S) 图片 URL；传入即为编辑。文件上传后使用 URL 引用。
`n`	1–10 的整数，默认 1。
`size`	默认 `auto`，也可 `宽x高`。自定义面积 655,360–20,000,000 像素，比例 1:3–3:1，均含边界。
`aspect_ratio`	自动尺寸时可用 `auto` 或 `X:Y`，X、Y 为 1–300 的整数，比例 1:3–3:1。
`area`	自动尺寸时使用 `1K`、`2K`、`4K`，默认 `4K`。目标面积分别为 1024²、2048²、4096²，实际宽高在结果中返回。
`disable_prompt_enhanced`	仅文生图支持，默认 false。设为 true 时必须指定明确尺寸或比例，模型约读取前 4096 个提示词 Token。编辑始终开启增强。
`output_format`	默认 `jpeg`，可选 `jpg`、`png`、`webp`；jpg 统一返回 jpeg。
`output_compression`	0–100 整数，默认 95；PNG 忽略该值。
`aigc_watermark`	是否添加可见水印，默认 false，不影响图片元数据中的隐式标识。

指定自定义 size 时不得同时传入 area 或 aspect_ratio，即使值为 auto 也不允许。Playground 会在输入自定义宽高时去除这些互斥参数。图片 API 的参考图支持 JPG/JPEG/PNG/WebP/HEIC/HEIF，每张最大 64 MiB，每边 128–8192 像素，长短边比不超过 4。Playground 上传器目前支持 JPEG/PNG/WebP，每张不超过 10 MB。平台请求使用 URL 输入和 URL 交付，不在请求体中嵌入大图片。

独立提示词增强

curl -X POST https://api.aivideoapi.ai/v1/images/prompt-enhancements \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-image-context-ir","input":{"prompt":"阳光下的阅览室"}}'

支持 prompt、可选 image_urls、nsfw_checker（默认 true，遵循相同账户权限）以及相同的尺寸控制。尺寸参数影响参考图增强；纯文本增强自行决定构图。独立增强仅支持标准版，提交后返回异步任务 ID；成功结果包含 revised_prompt，以及增强结果提供时才返回的 aspect_ratio。

分两步文生图时，可将 revised_prompt 作为新请求的 prompt，设置 disable_prompt_enhanced: true，并指定明确的尺寸或宽高比。图片编辑始终再次增强，即使输入的是已经增强过的提示词，也会计算本次增强费用。

任务结果与恢复

创建任务返回示例

图片生成、图片编辑和独立提示词增强提交成功后，均返回任务 ID：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "b89c7408-2e66-4cb8-9c39-9f4699a6834f"
  }
}

使用该 ID 查询任务：

curl https://api.aivideoapi.ai/v1/tasks/b89c7408-2e66-4cb8-9c39-9f4699a6834f \
  -H "Authorization: Bearer sk-your-api-key"

以下为任务查询响应示例，图片地址、提示词、用量和积分仅用于展示返回结构。时间戳单位为秒。

图片生成／编辑成功

{
  "id": "b89c7408-2e66-4cb8-9c39-9f4699a6834f",
  "status": "completed",
  "model": "minimax-h3-image",
  "credits_consumed": 8.38,
  "created_at": 1794362400,
  "settlement_status": "settled",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "completed_at": 1794362460,
  "output": {
    "urls": [
      "https://your-storage.example/reading-room-1.jpeg",
      "https://your-storage.example/reading-room-2.jpeg"
    ],
    "images": [
      {
        "image_index": 0,
        "url": "https://your-storage.example/reading-room-1.jpeg",
        "size": "2736x1536",
        "revised_prompt": "清晨的暖光穿过落地窗，照亮安静阅览室中的木质书桌与整齐书架。"
      },
      {
        "image_index": 1,
        "url": "https://your-storage.example/reading-room-2.jpeg",
        "size": "2736x1536",
        "revised_prompt": "清晨的暖光穿过落地窗，照亮安静阅览室中的木质书桌与整齐书架。"
      }
    ],
    "requested_count": 2,
    "succeeded_count": 2
  },
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 8000,
    "total_tokens": 9000,
    "generated_images": 2,
    "text_input_tokens": 1000,
    "image_input_tokens": 0,
    "image_output_tokens": 8000
  }
}

标准版、极速版和图片编辑使用相同的结果结构。image_index 从 0 开始。部分成功时，任务仍为 completed，urls 和 images 仅包含成功图片，并保留原始序号；例如请求 2 张、仅第 2 张成功时，requested_count 为 2、succeeded_count 和 usage.generated_images 为 1，唯一图片的 image_index 为 1。usage 为成功图片的汇总用量，credits_consumed 为最终积分，最多两位小数。

独立提示词增强成功

{
  "id": "a510fa06-ddd5-474e-9395-809208c754d6",
  "status": "completed",
  "model": "minimax-h3-image-context-ir",
  "credits_consumed": 2.04,
  "created_at": 1794362400,
  "settlement_status": "settled",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "completed_at": 1794362415,
  "output": {
    "revised_prompt": "一间安静的阅览室，柔和阳光穿过高大的窗户洒在木质书桌上，书架排列整齐，画面温暖自然，采用宽幅构图。",
    "aspect_ratio": "16:9"
  },
  "usage": {
    "input_tokens": 3489,
    "total_tokens": 3489
  }
}

独立增强不返回图片 URL；aspect_ratio 仅在增强结果提供时出现。

待核对任务

{
  "id": "b89c7408-2e66-4cb8-9c39-9f4699a6834f",
  "status": "processing",
  "model": "minimax-h3-image",
  "credits_consumed": 0,
  "created_at": 1794362400,
  "settlement_status": "reconciliation_required",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "progress": null
}

此时尚无最终账单，credits_consumed: 0 不代表免费，查询响应暂不包含 output 和 usage。

请求可能运行最长 600 秒。已提交任务不可取消，超时或断流后也可能继续生成，因此不会自动重新提交生成。已保存结果只恢复交付、结算或回调，不再次生成。缺失用量、结果冲突或优惠资格不明时，任务保持 processing，返回 settlement_status: "reconciliation_required"；不猜测最终费用，也不展示为免费。完成的任务不会进入失败退款流程。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。