接口一览

01鉴权与约定

Base URL: https://api.456.com.cn
Authorization: Bearer <API_KEY>
Content-Type: application/json

• 金额一律以微元（1 元 = 1e6）给整数，另给展示串；展示串不要参与运算。
• 时间为 ISO 8601 UTC。
• 写操作支持 Idempotency-Key 头，同键返回同一任务、不重复计费。
• 速率限制超出时返回 429 并带 Retry-After。

02端点

创建任务的请求体

H3 不支持反向提示词，请勿依赖旧字段 negative_prompt。控制台高级参数的可见性和默认值由管理后台配置；Context IR 在提示词下方单独选择，账户可保存其默认状态。

任务返回

下例为 5 秒 768P 标准档、未开启 Context IR 的成功任务，按当前价格合计 ¥0.45；完整价目可通过 GET /v1/pricing 查询。

{
  "id": "vid_...",
  "object": "video.task",
  "status": "succeeded",
  "progress": 1,
  "mode": "text_to_video",
  "resolution": "768p",
  "duration": 5,
  "created_at": "...", "started_at": "...", "completed_at": "...",
  "accelerated": true,
  "output": {
    "video_uri": "...", "width": 1344, "height": 768,
    "duration": 5, "has_audio": true, "watermarked": true,
    "expires_at": "..."
  },
  "usage": { "billed_seconds": 5, "amount_micro": 450000, "amount": "0.45", "currency": "CNY" }
}

官方 Context IR

官方 Context IR 是 MiniMax 提供的托管预处理服务，会在编码前改写并补充提示词，使其更贴合模型的理解方式。 它与生成必需的 H3 编码器是两个不同功能，默认关闭。

启用方式

创建任务时在请求体中传入 "use_context_ir": true：

curl -X POST $H3_BASE/v1/videos \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只猫在雨中的霓虹街头行走，倒影，电影感",
    "duration": 5,
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "use_context_ir": true
  }'

• 不传该字段或传 false 均不启用。控制台账户中的 Context IR 默认设置仅作用于控制台下单，不影响 API 调用。
• 处理内容为提示词、成片时长与画幅；当前不向该服务发送上传的素材。
• n>1 时每个任务各自处理、各自计费。

计费

• 单价 ¥0.05 / 次，以 GET /v1/pricing 返回的 official_context_ir_micro 为准。
• 创建任务时按启用状态一并冻结该项额度；服务不可用或处理未成功时，任务使用原提示词继续生成，该项不收费，冻结额度在结算时释放。
• 任务 failed 时不计费；任务 cancelled 或 rejected 时，若 Context IR 已处理完成，该项按已完成部分结算。

确认是否生效

任务成功后，usage.items 中出现 kind 为 official_context_ir 的条目，即表示本次已应用 Context IR； 无此条目表示未应用，且未收取该项费用。

"usage": {
  "items": [
    { "kind": "output", "label": "768P 输出", "qty": 5, ... },
    { "kind": "official_context_ir", "label": "Context IR", "qty": 1, "amount_micro": 50000, ... }
  ],
  ...
}

已有作品超分到 2K

仅支持自己已完成且原视频仍可读取的 768P 作品。先调用 GET /v1/videos/{id}/upscale 获取报价；返回中的 amount_micro 必须原样提交。报价按原视频实际时长计算。

# 1) 获取报价，读取响应 amount_micro
curl $H3_BASE/v1/videos/vid_xxx/upscale -H "Authorization: Bearer $H3_API_KEY"

# 2) 将 AMOUNT_MICRO 替换为上一步返回的整数
curl -X POST $H3_BASE/v1/videos/vid_xxx/upscale \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_micro": AMOUNT_MICRO}'

创建成功返回 202 和新任务。若返回 existing，表示已有进行中或完成的超分任务，直接使用该任务。价格变化会返回 409，需重新获取报价。

超分保留原作品，只收超分阶段费用，不重复收基础生成、编码器和素材费。2K、4K 作品不支持再次调用此入口。

03素材

POST /v1/files 以 multipart 上传，purpose 取input_image（起始帧）、end_image（结束帧） 或 reference（参考素材）。返回含 expires_at；过期后字节会被真正删除，此后再以该文件创建任务将被拒绝。

reference 收三类：图（png/jpeg/webp）、视频（mp4/mov）、音频（mp3/wav/m4a/flac）。 上传时平台会从容器头里读出时长（视频、音频）与像素尺寸（图、视频）—— 前者是计费与 15 秒累计闸的依据， 后者给 aspect_ratio: "auto" 用。音频读不出时长会被 400 拒：15 秒时长限制以该元数据为唯一依据， 接受无法解析时长的文件将使该限制失效。

⚠️ 参考视频会被模型截断到成片帧数：出 5 秒片时， 一段 15 秒的参考视频只有前 5.17 秒进得去（帧数还要向下对齐到 17k+5 栅格）。 这不是平台的选择，是模型本身的行为（ComfyUI 节点里的硬截断，没有开关）。但计费按你上传的时长算 —— 字节我们全都收下、存下、要传给编码器， 成本在上传那一刻就发生了。想让整段素材都生效，把 duration调到不小于素材时长。

参考视频的处理：创建任务时，平台按平台设置为每条参考视频确定使用压缩版或原视频； 平台不允许自行选择时，reference_video_mode、reference_video_keep_audio、reference_video_options 均不生效。压缩版保留整段内容，按平台设置降低分辨率、统一为 24 帧，默认不保留原声， 由算力节点在送入模型前处理，不影响创建任务的响应速度；任务中引用的仍是你上传的文件，计费按原视频时长。 此外，无论使用哪一份，参考视频进入模型前短边超过平台上限的部分都会按比例缩小。

03b提示词优化

POST /v1/prompt/optimize 把一句话改写成适合 H3 的提示词。provider 为 qwen 时， 由平台的千问按电影与漫剧手法拆分镜，返回官方格式的英文和一份中文分镜表；不填时使用官方 Context IR 改写 （与创建任务的 use_context_ir 是两笔独立的费用）。千问优化需管理员开启，未开启返回 403， 服务暂时不可用返回 503。按次计费，单价见 GET /v1/pricing 的 prompt_opt_micro，不要在客户端写死价格。

返回的 prompt 是发给模型的提示词，original 是原话；qwen 另返回 storyboard（中文分镜表：概述、风格、各镜头的时间、景别、运镜、内容、台词与声音，以及识别出的素材 materials）。 创建任务时把原话放在 prompt、把返回的 prompt 放在 model_prompt。 本账户在控制台「角色库」保存的角色，其图片出现在 reference_files 中时，外貌与台词音色按角色卡统一写法，多集保持一致。

三条与钱有关的行为：余额不足返回 402 且不扣费； 优化服务出错返回 502 且不扣费；只有成功返回时才扣一笔，在流水里记作 prompt_optimize。 这一笔不挂在任何任务上 —— 你可以优化完不发任务。

04余额

GET /v1/credits 返回余额与近期流水。权威余额是流水求和；返回中的余额快照仅供对账参考，并发写入下可能不是最新值。

05API Key

列表只返回掩码。创建时明文只出现一次，平台仅存哈希 —— 丢了只能吊销重建。

06任务状态机

07错误结构

{
  "error": {
    "type": "invalid_request_error",
    "code": "task_not_cancellable",
    "message": "…",
    "param": "duration",
    "request_id": "req_..."
  }
}

反馈问题时请附上 request_id。各状态码的含义见错误码。