API 文档

minimax h3 image API

一个接口,10 个工具。带上 API Key 发送 JSON-RPC 2.0 请求,即可查询积分、浏览模型,并生成图片、视频和音乐。AI 应用通过 MCP 连接的也是这个服务。

接口地址

POSThttps://minimaxh3image.com/api/mcp

认证

把 API Key 作为 Bearer Token 发送。Key 以 sk_ 开头,会消耗你账户的积分,请妥善保管。删除 Key 后立即失效。

HTTP
Authorization: Bearer sk_...

Claude、ChatGPT 等应用也可以改用 OAuth 登录,它们会从 401 响应和以下元数据地址自动发现: https://minimaxh3image.com/.well-known/oauth-protected-resource/api/mcp

发起请求

每个 POST 请求携带一条 JSON-RPC 消息,无需会话,也无需先调用 initialize。用 tools/list 获取工具列表,用 tools/call 调用工具。

curl
curl -X POST https://minimaxh3image.com/api/mcp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_balance","arguments":{}}}'

响应是一次性的事件流,读取 data: 那一行即可。工具结果在 result.structuredContent 中,result.content 里也有一份文本。

响应
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"credits\":1200}"}],"structuredContent":{"credits":1200}}}

生成是异步的

发起生成会立即返回一个 id,轮询它直到结果就绪。

  1. 1estimate_cost

    可选。运行前先查看任务要花多少积分。

  2. 2generate_*

    发起任务,返回生成 id 和本次消耗的积分。

  3. 3wait_for_generation

    每次调用最多等待 50 秒。只要 status 不是 success、failed 或 canceled,就继续调用。

  4. 4url

    status 为 success 时,结果里会带上图片、视频或歌曲的 url。

错误与限制

  • 401缺少 API Key 或 Key 无效。WWW-Authenticate 响应头会引导 OAuth 客户端去登录。
  • 429每个 IP 或账户每分钟超过 120 次请求。请等待 Retry-After 指定的秒数。请求体上限为 200 KB。
  • isError工具已执行但失败,例如积分不足或模型不存在。返回 HTTP 200,result.isError 为 true,原因在 result.content 中。
  • error请求本身无效,例如工具不存在或参数错误。响应中是 JSON-RPC error 对象,而不是 result。

10 个工具

列表实时读取自服务器,始终与 API 实际接受的一致。标有"消耗积分"的工具会从你的账户扣费。

get_balance

只读

Get the remaining credit balance of the account.

参数

无参数。

请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {}
  }
}

list_models

只读

List the available generation models (slug, name, vendor, starting price). Use the slug with get_model, estimate_cost and generate_*.

参数

名称类型说明
type"image" | "video" | "audio"
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_models",
    "arguments": {
      "type": "image"
    }
  }
}

get_model

只读

Get every parameter a model accepts (names, types, allowed values, defaults) so generate_* options can be filled in correctly.

参数

名称类型说明
model必填stringModel slug from list_models
mediaType必填"image" | "video" | "music"
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_model",
    "arguments": {
      "model": "minimax-h3-image",
      "mediaType": "image"
    }
  }
}

estimate_cost

只读

Estimate how many credits a generation will cost without running it.

参数

名称类型说明
mediaType必填"image" | "video" | "music"
model必填stringModel slug from list_models
promptstring≤ 10000 个字符
imageUrlsstring[]≤ 10 项
videoUrlsstring[]≤ 10 项
audioUrlsstring[]≤ 10 项
optionsobjectModel parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts.
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "estimate_cost",
    "arguments": {
      "mediaType": "video",
      "model": "minimax-h3",
      "prompt": "A red sports car drifting through a neon city at night"
    }
  }
}

generate_image

消耗积分

Generate an image from a prompt, or edit / combine reference images (imageUrls). Spends credits.

参数

名称类型说明
model必填stringModel slug from list_models
prompt必填string≤ 10000 个字符
imageUrlsstring[]Optional reference images≤ 10 项
optionsobjectModel parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts.
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_image",
    "arguments": {
      "model": "minimax-h3-image",
      "prompt": "A banana-shaped yellow sofa in a sunny living room"
    }
  }
}

generate_video

消耗积分

Generate a video from a prompt, a start image (imageUrls) or a reference video. Spends credits; call estimate_cost first.

参数

名称类型说明
model必填stringModel slug from list_models
promptstring≤ 10000 个字符
imageUrlsstring[]≤ 10 项
videoUrlsstring[]≤ 10 项
audioUrlsstring[]≤ 10 项
optionsobjectModel parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts.
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_video",
    "arguments": {
      "model": "minimax-h3",
      "prompt": "A red sports car drifting through a neon city at night"
    }
  }
}

generate_music

消耗积分

Generate a song or instrumental from a prompt (style, mood, lyrics). Spends credits.

参数

名称类型说明
model必填stringModel slug from list_models
prompt必填string≤ 10000 个字符
optionsobjectModel parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts.
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_music",
    "arguments": {
      "model": "suno-v6",
      "prompt": "Upbeat synth-pop about a summer road trip"
    }
  }
}

get_generation

只读

Get the status of one generation and its result url once it succeeded.

参数

名称类型说明
id必填string≤ 128 个字符
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_generation",
    "arguments": {
      "id": "GENERATION_ID"
    }
  }
}

wait_for_generation

只读

Wait (up to timeoutSeconds) until a generation finishes, then return its status and url. Call again if it is still running.

参数

名称类型说明
id必填string≤ 128 个字符
timeoutSecondsinteger默认 45 · 5–50
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wait_for_generation",
    "arguments": {
      "id": "GENERATION_ID",
      "timeoutSeconds": 45
    }
  }
}

list_generations

只读

List the most recent generations of the account.

参数

名称类型说明
mediaType"image" | "video" | "music"
limitinteger默认 10 · 1–50
请求体示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_generations",
    "arguments": {
      "mediaType": "video",
      "limit": 5
    }
  }
}