MiniMax-H3 API

MiniMax-H3 使用 MiniMax V2 的请求和任务响应格式，提供视频生成能力。Base URL 为 https://api.seedance.nz，鉴权使用本站 API Key：Authorization: Bearer <API_KEY>。从 MiniMax V2 客户端迁移时，替换 Base URL 和 API Key，并按下面的能力范围调整请求。

机器可读定义：OpenAPI JSON。完整指南和接口定义可从 /docs/minimax-h3-api.md 和 /docs/minimax-h3-openapi.json 下载。

能力与兼容范围

官方当前 MiniMax-H3 的分辨率范围是 768P / 2K、时长为 4–15 秒。本服务的 480P、1080P、drive_audio、audio_control、视频起始偏移、2:3 / 3:2 比例、混合关键帧与参考素材及长驱动音频任务属于扩展。参考站 H3 Gateway 的 /v1/videos、target、conditions、OSS 预签名 PUT 是另一套 SPI，不能直接作为本接口请求体。

价格

按提交请求的输出时长计费，标准零售价如下。参考图片、音频、视频不另加输入费用。

1080P 保留工作流原生对齐尺寸：16:9 输出 1920×1088，其他比例短边同样为 1088 像素。

提交时预扣，任务失败释放相应预扣额度。删除已完成任务的记录不会退款；取消请求返回错误时，原任务继续执行和结算。账户实际价格以控制台适用的分组及折扣为准。

接口

所有任务操作都使用当前 API Key 对应的账户和租户权限。任务 ID 不等于访问授权。已有 /v1/video/generations 入口继续提供本站通用视频协议；MiniMax V2 客户端请使用本节的 /v2/ 路径。

创建任务

请求头：Content-Type: application/json。

支持的固定比例依次为 1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9，其中 2:3、3:2 是扩展比例。纯文本请求必须填写比例。参考请求省略时采用 16:9，显式传 adaptive 或 auto 会报错；这与官方参考模式默认 adaptive 不同。关键帧请求可指定固定比例，或省略/使用 adaptive（也接受扩展别名 auto）读取首帧图比例，仅有尾帧时读取尾帧，并选择 最接近的固定画幅；任务结果返回实际采用的比例。本服务会执行关键帧请求指定的固定比例，而官方会忽略它并使用自适应，因此这部分行为有差异。

内容项格式：

{"type":"text","text":"电影感镜头，人物向镜头挥手。"}

{"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"}

{"type":"video_url","video_url":{"url":"https://example.com/motion.mp4"},"role":"reference_video"}

{"type":"audio_url","audio_url":{"url":"https://example.com/voice.wav"},"role":"reference_audio"}

{"type":"audio_url","audio_url":{"url":"https://example.com/dialogue.wav"},"role":"drive_audio"}

参考图片必须明确使用 reference_image。省略图片角色时按官方规则等同 first_frame；省略音频/视频角色时分别等同 reference_audio / reference_video。本服务允许首帧、尾帧与参考图片、参考音频、参考视频及驱动音频混用，按实际内容自动选择混合模式，无需填写 task_type。关键帧最多各 1 张，额外参考图最多 9 张，其他类别也按各自上限独立计数。这是本服务扩展；官方 V2 将关键帧与参考素材定义为互斥场景。

参考视频内容项还支持扩展字段 start_time_seconds（非负秒数，默认 0），放在 role 同级；服务按 24 FPS 换算起始帧。例如 2.5 秒对应跳过 60 帧。图片和音频不提供这个裁剪参数。

文生视频

export API_KEY='YOUR_API_KEY'
export BASE_URL='https://api.seedance.nz'

curl "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type":"text","text":"航拍薄雾中的山谷，晨光穿过树梢，镜头平稳前进。"}],
    "resolution": "480P",
    "duration": 5,
    "ratio": "16:9"
  }'

HTTP 200 表示已接受任务，不表示视频已完成：

{"task_id":"task_example"}

首帧、尾帧与首尾帧

{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"人物从首帧姿态自然转身，平稳过渡至尾帧构图。"},
    {"type":"image_url","image_url":{"url":"https://example.com/start.jpg"},"role":"first_frame"},
    {"type":"image_url","image_url":{"url":"https://example.com/end.jpg"},"role":"last_frame"}
  ],
  "resolution":"768P",
  "duration":5,
  "ratio":"adaptive"
}

省略尾帧项即为首帧生成；省略首帧项即为尾帧生成。首帧和尾帧最多各一张，角色决定用途，不依赖它们在数组中的顺序。自适应会选择最接近输入图的固定比例，而不是保证任意比例的原尺寸输出。

多模态参考

{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"保持参考图人物的外貌，参考视频中的镜头运动，使用参考音频的声音风格。"},
    {"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"},
    {"type":"video_url","video_url":{"url":"https://example.com/motion.mp4"},"role":"reference_video"},
    {"type":"audio_url","audio_url":{"url":"https://example.com/voice.wav"},"role":"reference_audio"}
  ],
  "resolution":"768P",
  "duration":10,
  "ratio":"16:9"
}

驱动音频与声音参考

reference_audio 提供声音参考；drive_audio 提供目标音频驱动。音色参考不等于强制按照音频逐字对口型。需要按台词生成时，在文字提示中同时写出明文台词。

{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"参考图中的人物正对镜头，口型跟随 <Audio 1>，说：<d>[中文] 今天的天气真好。</d>"},
    {"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"},
    {"type":"audio_url","audio_url":{"url":"https://example.com/dialogue.wav"},"role":"drive_audio"}
  ],
  "resolution":"480P",
  "duration":5,
  "ratio":"16:9",
  "audio_control":{"mode":"lock_source","denoise_strength":0,"add_drive_as_reference":true}
}

有驱动音频时缺省使用 lock_source，无驱动音频时缺省使用 native。denoise_strength 范围 0–1，用于调节 remix_source 的音轨重生成；lock_source 的有效值固定为 0，其他模式缺省 0.35。add_drive_as_reference 决定是否把驱动音频同时提供为声音参考；有驱动且为非 native 模式时默认 true，native 模式默认 false。显式 0 和 false 会保留。希望驱动台词同时使用另一条参考声音时，可以设置：

{"audio_control":{"mode":"remix_source","denoise_strength":0.35,"add_drive_as_reference":false}}

seed、num_inference_steps、flow_shift、audio_flow_shift 和 quality 等不是当前开放参数。旧参考网关的 seed 仅记录和校验，没有控制 采样器，本服务不将它表述为可复现性控制。

查询结果

curl "$BASE_URL/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

{
  "task":{
    "id":"task_example",
    "model":"MiniMax-H3",
    "status":"succeeded",
    "created_at":1788500000,
    "updated_at":1788500080,
    "content":{"url":"https://example.com/generated-video.mp4"},
    "resolution":"480P",
    "duration":5,
    "ratio":"16:9",
    "task_type":"generation",
    "modality":"video",
    "usage":{"amount":0.75,"currency":"CNY"}
  }
}

状态为 queued、running、succeeded、failed 或 cancelled。时间戳单位为 Unix 秒。成功读取 task.content.url，无需调用旧版 file_id 文件检索接口；进行中的任务不会包含成功视频 URL。失败查看 task.error.code / task.error.message。

duration 表示请求用于计费的输出时长。工作流按 24 FPS、17n+5 帧对齐，输出播放时长可能略长；费用仍按请求秒数计算。

任务完成最终结算后，task.usage.amount 与 task.usage.currency 才会出现。amount 与用户实际扣费完全一致，不是提交时的预扣金额；失败或取消任务完成退款后返回 0。响应不会暴露预扣额、内部结算 token 或上游供应商成本字段。任务尚未完成最终结算时省略整个 usage 字段。

建议每 5–10 秒查询一次；遇到查询 429 或暂时性 5xx 时退避重试查询。创建请求超时不代表任务未创建，本接口未承诺参考站 SPI 的 request_id 幂等行为，不应无条件重发生成请求。

网关按固定顺序使用主、备用两组上游凭据。仅在未获得任务编号且上游明确拒绝受理时切换一次备用凭据：HTTP 401、402、403、429，或响应中非零的明确业务错误码。已返回任务编号后始终查询原任务，任务运行失败不会重新创建；网络超时、5xx 或无效 JSON 无法确认是否受理，也不会自动换凭据重发。两次均被拒绝时返回最后一次错误，只有容量限制归类为 429。

如果网关已经尝试提交，但收到超时（包括 HTTP 408）或 5xx 等不确定结果，错误响应可带 X-Task-Id 和 Retry-After: 5。正文仍为 V2 错误格式，不另加 task_id。保存该响应头的公共任务 ID 并查询，网关会暂时保留任务记录和预扣，公开状态为 queued，后台尝试关联 bridge 已保存的任务。此时 queued 不表示上游一定尚未运行。只有 bridge 能按公共任务 ID 找回记录时才能恢复；不保证在 任务已受理、但 bridge 未保存 任务 ID 的情况下自动找回。未收到公共任务 ID 时，不要推断提交失败或盲目重提。明确拒绝的参数、授权、额度或容量类 4xx（不含上述提交超时）不走此恢复路径，并释放相应预扣。

Python 完整调用示例

安装 requests，设置环境变量 API_KEY；此示例只提交一次，查询失败不会重新创建付费任务。

import os
import time
import requests

base = os.environ.get("BASE_URL", "https://api.seedance.nz").rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
payload = {
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "晨光中的森林，镜头缓慢前进。"}],
    "resolution": "480P", "duration": 5, "ratio": "16:9",
}
created = requests.post(f"{base}/v2/video_generation", headers=headers,
                        json=payload, timeout=60)
if created.ok:
    task_id = created.json()["task_id"]
else:
    task_id = created.headers.get("X-Task-Id")
    if not task_id:
        created.raise_for_status()
    print("提交结果待确认，仅查询已有任务：", task_id)
print("task_id:", task_id)  # 保存此 ID，之后可恢复查询
deadline = time.monotonic() + 1800
delay = 10
while time.monotonic() < deadline:
    time.sleep(delay)
    try:
        response = requests.get(f"{base}/v2/query/video_generation/{task_id}",
                                headers=headers, timeout=30)
    except requests.RequestException:
        delay = min(delay * 2, 60)
        continue
    if response.status_code == 429 or response.status_code >= 500:
        delay = min(delay * 2, 60)
        continue
    response.raise_for_status()
    try:
        task = response.json()["task"]
    except (ValueError, KeyError) as exc:
        raise RuntimeError(f"查询响应无效；保留任务 ID {task_id}") from exc
    delay = 10
    if task["status"] == "succeeded":
        print("video URL:", task["content"]["url"])
        print("actual charge:", task["usage"]["amount"], task["usage"]["currency"])
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error", task))
else:
    raise TimeoutError(f"本地等待超时，任务可能仍在执行：{task_id}")

列表与删除

curl "$BASE_URL/v2/query/video_generation?page_num=1&page_size=20&filter.model=MiniMax-H3&filter.status=succeeded" \
  -H "Authorization: Bearer $API_KEY"

查询最近 7 天的任务。使用 page_num / page_size 分页，本网关默认第 1 页、每页 10 条；页码范围 1–10000，每页 1–100 条。支持 filter.status、重复的 filter.task_ids（最多 100 个）、filter.model、filter.task_type。本模型的 filter.task_type 为 generation。返回 items 数组和符合条件的 total。

curl -X DELETE "$BASE_URL/v2/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

已成功、失败或已取消的记录可以删除；允许删除已取消记录是本服务扩展。删除只隐藏公开记录，不重复退款。正在运行的任务不能删除。排队任务的取消只有在上游确认可取消时才能成功；该接口无法确认取消时返回错误，原任务仍有效，也不会提前退款。不能把客户端停止轮询当作任务取消。

回调

设置 callback_url 后，网关先发送包含 challenge 的验证请求；回调服务须在 3 秒内以 HTTP 200 返回同值的 JSON challenge（也接受纯文本同值）。验证成功后通知任务终态，正文与查询接口的 {"task":{...}} 格式一致，并附带 X-MiniMax-Task-Id 请求头。终态通知收到任意 2xx 即视为送达，最多尝试 5 次，失败后的等待间隔依次为 1、2、4、8 分钟；可能重复投递，请按任务 ID 和终态幂等消费。查询接口仍是状态和最终结果的依据。

与官方所有状态变化的推送不同，本实现不承诺每个排队/运行中间状态都有回调。禁止把 API Key 放进回调 URL。

素材

媒体 HTTP(S) URL 必须能由服务端直接读取。可以先使用本站已有的 POST /v1/files/upload 获取临时 URL，再填入 image_url.url / audio_url.url / video_url.url。图片和音频也可使用标准 data:<mime>;base64,...，服务校验后转为临时 URL；不接受裸 Base64、本机路径或浏览器 blob: URL。大文件建议先上传。

curl "$BASE_URL/v1/files/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'file=@/path/to/person.png'

{"url":"https://example.com/temporary-person.png","file_type":"image","size":3490,"expires_in":86400}

上传为 multipart/form-data，字段名 file；通用上传限制单文件不超过 50 MB，临时 URL 约 24 小时有效。上传成功不代表素材已满足生成模型的全部约束。

参考视频每条应为 2–15 秒；按 24 FPS 解码后必须为 48–360 帧，起始偏移后的素材也须满足此范围。这约束输入参考视频，不限制带驱动音频的输出时长。使用兼容的常见格式：图片 JPEG/PNG/WebP、音频 MP3/WAV、视频 MP4。实际解码和媒体约束由上游工作流检查；无法读取或解析的素材会使请求或任务失败。不要把其他 MiniMax 官方模型的最大尺寸/文件大小保证直接套用到此 服务。

错误

HTTP 错误使用 MiniMax V2 风格的外层 envelope，http_code 为字符串：

{
  "type":"error",
  "error":{"type":"bad_request_error","message":"invalid request parameters","http_code":"400"},
  "request_id":"request_example"
}

参数错误应修正后再提交；401 检查本站 API Key，402 检查额度，429 按响应提示退避，5xx 先查询已有任务。任务自身失败出现在 HTTP 200 的 task.error 中，与请求失败的 envelope 不同。

官方协议参考

• 创建视频任务
• 查询任务
• 任务列表
• 取消或删除任务

这些链接用于核对协议；实际可调用范围以本页的能力、参数和扩展说明为准。