星算云 开发者文档

主题

MiniMax H3 视频生成(按秒计费) ​

星算云 MiniMax H3(Hailuo-03)视频网关挂载于 /v2,对外提供 MiniMax-H3 系列模型(多模态参考视频生成,按秒计费)。请求体与响应体沿用 MiniMax 官方格式原样透传,平台仅做鉴权、模型校验与按秒计费;鉴权用 Authorization: Bearer xsk_...。

与 Seedance(火山兼容) 等 /api/v3 视频端点、万相 3.0 等 /api/v1 端点区别:本网关只接 provider 为 MINIMAX 的 VIDEO 模型(MiniMax-H3 / MiniMax-H3-Max);其他模型请走各自端点。

基础信息 ​

项目内容
Base URLhttps://xingsuan.cloud(平台地址)
创建任务POST /v2/video_generation
查询任务GET /v2/query/video_generation/{task_id}
Content-Typeapplication/json
鉴权 HeaderAuthorization: Bearer xsk_...(平台 API Key)

API Key 安全

只在服务端保存 API Key,不要放入浏览器、公开仓库或客户端安装包。

模型 ​

模型代码说明
MiniMax-H3H3 标准档,文生视频 / 图生视频(首帧/尾帧/首尾帧) / 多模态参考生视频(参考图/视频/音频);分辨率 768P / 2K,时长 4~15 秒
MiniMax-H3-MaxH3 极速档,仅文生视频与图生视频(首尾帧),不支持多模态参考;分辨率 480P / 768P,时长 5~15 秒

模型代码即 MiniMax 官方模型名;价格与可用档位以平台「模型市场」展示为准。

计费 ​

按「计量总秒数 × 分辨率·输入类型单价」计费,以平台模型配置价格与 API Key 折扣为准,从账户钱包实时扣减。任务失败不收取费用。

  • 计费秒数:以任务成功后响应 task.usage.total_seconds 为准(官方计量口径 = 输入参考秒数 + 输出秒数,向上取整到整秒)——含参考视频的输入秒数计入计费基数;未回报时按请求 duration。
  • 分辨率档位:以响应 task.resolution 为准;未回报或档位未配价时按请求 resolution(缺省 768P)。
  • 输入类型:仅当 content 含 video_url(参考视频)时用「含参考视频」价;首尾帧图片与参考图/参考音频均按「无参考视频」价。
  • ratio / 水印(aigc_watermark)不影响价格。

具体单价见平台「模型市场」对应模型的价格表。

创建任务 ​

POST /v2/video_generation

bash
API_BASE=https://xingsuan.cloud
curl "$API_BASE/v2/video_generation" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "在天空晴空万里、一望无际的草原上,一群牛羊在悠然的吃草"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'
python
import requests

API_BASE = "https://xingsuan.cloud"
resp = requests.post(
    f"{API_BASE}/v2/video_generation",
    headers={"Authorization": f"Bearer {XSK_KEY}"},
    json={
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": "在天空晴空万里、一望无际的草原上,一群牛羊在悠然的吃草"}],
        "resolution": "768P",
        "duration": 5,
        "ratio": "16:9",
    },
)
data = resp.json()
print(data["task_id"])  # 任务 ID,用于查询

请求参数

参数位置必填说明
AuthorizationHeader是Bearer xsk_...
modelBody是MiniMax-H3 / MiniMax-H3-Max
contentBody是多模态输入数组,见下方类型矩阵;必须含一个非空 text 项(prompt 必填)
resolutionBody是MiniMax-H3:768P / 2K;MiniMax-H3-Max:480P / 768P(不支持 2K)
durationBody是生成时长(秒);MiniMax-H3 为 4~15,MiniMax-H3-Max 为 5~15
ratioBody条件adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;文生视频必填且不能为 adaptive,图生视频恒为 adaptive
callback_urlBody否任务状态变更回调地址(上游直连,平台不代理)
aigc_watermarkBody否是否加 AIGC 水印,默认 false

content 类型矩阵

content 每项通过 type 区分,媒体项通过 role 标注用途:

typerole数量上限说明
text—1(必填)提示词,最多 7000 字符
image_urlfirst_frame(或省略)1首帧图片(图生视频)
image_urllast_frame1尾帧图片(与首帧成对)
image_urlreference_image9参考图片(多模态参考)
video_urlreference_video3参考视频(触发「含参考视频」价)
audio_urlreference_audio3参考音频

互斥约束:first_frame/last_frame(图生视频)与 reference_*(多模态参考)不能混用。

媒体 URL 支持公网 HTTP(S) 地址与 Base64 data URI(请求体总大小 ≤ 64 MB,大文件请用公网 URL)。

创建响应 ​

创建成功(HTTP 200)返回扁平对象:

json
{"task_id": "video_gen_6aaf693eff3f4cd0ba6dcf447cf40432"}

保存 task_id,后续用它查询任务。

查询任务 ​

GET /v2/query/video_generation/{task_id}

bash
curl "$API_BASE/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $XSK_KEY"

响应为 {task: {...}} 信封,task.status 表示任务状态。建议每 5~10 秒轮询一次。

task.status 取值

task.status含义是否终态
queued排队中否
running处理中否
succeeded成功,task.content.url 为视频地址是
failed失败,task.error 含 {code, message}是
cancelled已取消是

成功

json
{
  "task": {
    "id": "video_gen_xxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {"url": "https://xxx/xxx.mp4"},
    "resolution": "768P",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0,
      "total_tokens": 273890,
      "prompt_tokens": 13500,
      "completion_tokens": 260390
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

7 天时效

  • task_id 创建后 7 天内可查询,超出窗口返回 invalid task_id;
  • 视频产物 content.url 为限时下载地址,请及时下载或转存;过期后重新查询可获取新地址。

多模态参考示例 ​

首尾帧(图生视频)

json
{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "镜头从首帧自然过渡到尾帧,动作连贯,真实摄影质感"},
    {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
  ],
  "resolution": "2K",
  "duration": 5
}

视频 + 音频参考(含 video_url,按「含参考视频」价计费)

json
{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "参考视频中人物的动作与音色,生成同风格的口播视频"},
    {"type": "video_url", "video_url": {"url": "https://example.com/motion.mp4"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"}
  ],
  "resolution": "768P",
  "duration": 5
}

参考素材须为公网可直接访问的 HTTP(S) 地址;不支持本地路径或需登录访问的地址。

错误 ​

  • 上游成功/失败响应:原样透传 MiniMax 官方信封。
  • 平台侧错误(鉴权失败 / 模型不存在 / 无权限 / 额度超限 / 钱包余额不足等):统一为 MiniMax 风格错误体 {"type":"error","error":{"type","message"},"request_id":...},如 authorized_error(401)、invalid_request_error(404)、rate_limit_error(429)、insufficient_balance_error(402)。上游 4xx/5xx 错误体原样透传(保留上游 request_id);上游超时 → 504 server_error;连接错误 → 502 server_error。详见 错误码。

路由约束

本网关只接受 provider 为 MINIMAX 的 VIDEO 模型;传入其他供应商模型会返回 400,请改用对应端点。任务查询按任务归属路由:其他端点创建的任务在本端点查询返回 404(反之亦然)。

Copyright © 2026 星算云