视频生成 · MossHub API 文档

视频是异步任务：提交后拿到任务 ID，轮询到结束，再从结果里的地址下载。

选择接口

视频模型走 MiniMax 视频或火山方舟视频接口，请求体和响应沿用官方格式。MossHub 换掉模型 ID 和任务 ID，其余原样转发。模型走哪个接口，见控制台「模型」详情的「接入」。

操作	MiniMax 视频	火山方舟视频
提交	`POST /minimax/v2/video_generation`	`POST /ark/api/v3/contents/generations/tasks`
查询	`GET /minimax/v2/query/video_generation/{task_id}`	`GET /ark/api/v3/contents/generations/tasks/{id}`
取消	`DELETE /minimax/v2/video_generation/{task_id}`	`DELETE /ark/api/v3/contents/generations/tasks/{id}`

请求头带 Authorization: Bearer <API 密钥>。

提交任务

POST /minimax/v2/video_generation
Authorization: Bearer $MOSSHUB_API_KEY
Content-Type: application/json

{
  "model": "YOUR_MODEL_ID",
  "duration": 5,
  "content": [{ "type": "text", "text": "海边日出的延时摄影" }]
}

火山方舟视频同样用 content 数组传提示词和素材；参考图、视频和音频的写法见输入素材。任务 ID 在响应的 task_id（MiniMax）或 id（火山方舟）里：

{ "task_id": "<MossHub 任务 ID>" }

任务 ID 由 MossHub 签发，替代上游的原始 ID，查询和取消都用它。
只有同一额度归属的密钥能用它：同一成员的个人密钥之间，或同一项目的密钥之间。其他额度归属的密钥、另一个视频接口的路径或上游原始 ID，查询都返回 404。
提交不去重。客户端超时后任务可能已经创建，重试会再建一个。
不支持 callback_url 和 tools，传了返回 400，请改为轮询。

查询与下载

查询返回上游的任务对象，其中的任务 ID 同样换成 MossHub 任务 ID。状态在 task.status（MiniMax）或 status（火山方舟）：succeeded、failed、cancelled、expired 表示已结束，其他状态（如 queued、running）表示仍在进行。

{
  "task": {
    "id": "<MossHub 任务 ID>",
    "status": "succeeded",
    "content": { "url": "https://…/video.mp4" },
    "duration": 5,
    "usage": { "output_seconds": 5, "input_seconds": 0, "input_image_count": 0 }
  }
}

成功后按结果里的视频地址下载，MiniMax 在 task.content.url。MossHub 不保存视频，地址的有效期以上游为准。

取消

只有排队中（queued）的任务可以取消，取消后不计费；运行中的任务返回 400。

火山方舟样片

先提交带 "draft": true 的样片任务，满意后引用样片生成正式视频：

{
  "model": "YOUR_MODEL_ID",
  "content": [{ "type": "draft_task", "draft_task": { "id": "<样片的 MossHub 任务 ID>" } }]
}

样片必须由同一额度归属提交，否则返回 404。

计费

提交时按 duration（没填按 30 秒）和 resolution 从额度里预留一笔费用，样片按 480p 预留。
任务结束后结算：成功按上游报告的用量计费，MiniMax 计输出视频秒数、输入视频秒数和输入图片张数，火山方舟计输出 token；上游没有报告用量时按时长和分辨率估算。失败、取消和过期的任务不计费。
价格可按分辨率、是否带视频输入分档，单价见控制台模型详情的「价格」。
不查询也会结算：MossHub 在后台跟进任务。提交 8 天后仍未结算的任务，按预留金额计费。
额度用完后提交返回 402，已提交的任务仍可查询和取消。

任务结算后，这次调用出现在控制台的调用记录里，请求 ID 与提交时响应头的 X-Request-Id 相同。

常见失败

状态	原因
400	带了 `callback_url`、`tools` 或存放在上游的素材，内容项的 `type` 与素材字段不符，或取消运行中的任务
401	密钥无效或已过期
402	额度已用完
403	这把密钥不能使用该模型
404	模型不存在，或任务 ID 无效、不属于这把密钥的额度归属
413	请求体超过 32 MiB
429	线路繁忙，按 `Retry-After` 等待
502 / 503 / 504	上游出错、暂无可用线路或上游超时

错误体沿用各接口的官方格式，见错误处理。

提交、轮询与下载

先替换密钥、授权模型 ID 与示例输入；不自动执行。

set -eu
: "${MOSSHUB_API_BASE:?请设置 API 根地址}"
: "${MOSSHUB_API_KEY:?请设置 API 密钥}"
API="${MOSSHUB_API_BASE%/}/minimax/v2"
field() {
  python3 -c 'import json, sys
body = sys.stdin.read()
try:
    value = json.loads(body)
    for key in sys.argv[1:]:
        value = value[key]
except (ValueError, KeyError, TypeError):
    sys.exit(body)
print(value)' "$@"
}
TASK=$(curl -sS --max-time 60 "$API/video_generation" \
  -H "Authorization: Bearer $MOSSHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","duration":5,"content":[{"type":"text","text":"海边日出的延时摄影"}]}' \
  | field task_id)
echo "任务 ID：$TASK"
for _ in $(seq 60); do
  sleep 10
  RESULT=$(curl -sS --max-time 60 "$API/query/video_generation/$TASK" \
    -H "Authorization: Bearer $MOSSHUB_API_KEY")
  STATUS=$(printf '%s' "$RESULT" | field task status)
  case "$STATUS" in
    succeeded)
      URL=$(printf '%s' "$RESULT" | field task content url)
      curl -sS --fail -o video.mp4 "$URL"
      echo "已保存 video.mp4"
      exit 0
      ;;
    failed | cancelled | expired)
      echo "$RESULT" >&2
      exit 1
      ;;
  esac
done
echo "本地停止等待，稍后用任务 ID 继续查询" >&2
exit 1