视频生成

平台提供视频生成能力：通过文字提示、参考图 / 参考视频等素材生成视频。视频任务是异步的——提交后立即返回 task_id，你需要轮询查询任务状态，完成后获取成片下载地址。

目前提供两个视频模型族：

模型族	提交入口	说明
MiniMax H3（`MiniMax-H3`）	OpenAI 兼容（`/v1/videos`）+ MiniMax v2 / v1 原生	MiniMax Video Generation V2 协议（多模态 `content` 结构）
Seedance 系列（`doubao-seedance-*`）	仅 OpenAI 兼容	火山方舟视频模型，按 token 计价

视频生成为异步任务：提交接口只负责"接单"，成片生成需要数十秒到数分钟，请通过查询接口轮询直至 completed。切勿把提交接口当同步接口阻塞等待。

一、OpenAI 兼容接口

两个模型族都可通过 OpenAI 兼容入口提交；POST /v1/videos 与 POST /v1/video/generations 完全等价。

1.1 提交视频任务

POST https://confluia.com/v1/videos
Authorization: Bearer sk-你的密钥
Content-Type: application/json

纯文生视频（text-to-video）：

json

{
  "model": "MiniMax-H3",
  "prompt": "一位宇航员漫步在火星表面，远处是蔚蓝色的地球，电影级光影，4K 高清",
  "size": "1280x720"
}

size 可以填像素尺寸（1280x720 = 768P + 16:9），也可以只填画幅比例（16:9，此时分辨率取默认 768P）；两者都不填时默认 16:9 + 768P。画幅比例也可用 ratio 字段单独指定。

图生视频 / 首帧（image-to-video）：

json

{
  "model": "MiniMax-H3",
  "prompt": "让这张图片中的人物缓缓转身并微笑",
  "image": "https://example.com/input.jpg"
}

首尾帧生成（第一帧 + 最后一帧）：

json

{
  "model": "MiniMax-H3",
  "prompt": "镜头从白天缓缓过渡到夜晚，光线自然变化",
  "first_frame_image": "https://example.com/first.jpg",
  "last_frame_image": "https://example.com/last.jpg",
  "size": "1280x720",
  "duration": 8
}

角色参考生成（多张参考图，≤9 张）：

json

{
  "model": "MiniMax-H3",
  "prompt": "参考图中的人物在海边散步，保持人物形象一致",
  "images": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"],
  "duration": 8
}

首帧文件上传（multipart，适合本地图片）：

bash

curl -s https://confluia.com/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -F "model=MiniMax-H3" \
  -F "prompt=镜头缓慢推进，光影流动" \
  -F "size=1280x720" \
  -F "input_reference=@first_frame.png"

首帧有四种等价提供方式：JSON 字段 image、first_frame_image、input_reference（接 URL / Base64），或 multipart 表单中的 input_reference 文件。同时提供多个时按 multipart 文件 > first_frame_image > input_reference > image 取用。
提供首 / 尾帧时画幅比例固定为 adaptive（跟随输入画面）；首尾帧与角色参考图（images / subject_reference）不要同时提交——扁平入口下参考图会被静默忽略；v2 原生入口处显式混用会返回 400 invalid_content。

提交响应（立即返回任务信息，不是成片）：

json

{
  "id": "1860e25a08ed7aebd0a1430d4b611b9g",
  "task_id": "1860e25a08ed7aebd0a1430d4b611b9g",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1690000000
}

1.2 查询任务状态

GET https://confluia.com/v1/videos/{task_id}
Authorization: Bearer sk-你的密钥

进行中：

json

{
  "id": "1860e25a08ed7aebd0a1430d4b611b9g",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1690000000,
  "completed_at": 1690000060
}

完成： status 变为 completed，metadata.url 为成片下载地址：

json

{
  "id": "1860e25a08ed7aebd0a1430d4b611b9g",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "completed",
  "progress": 100,
  "created_at": 1690000000,
  "completed_at": 1690000120,
  "metadata": {
    "url": "https://.../output_xxx.mp4"
  }
}

失败： error 携带失败原因与上游错误码：

json

{
  "id": "1860e25a08ed7aebd0a1430d4b611b9g",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "failed",
  "progress": 100,
  "created_at": 1690000000,
  "completed_at": 1690000120,
  "error": {
    "message": "content moderation rejected ...",
    "code": "1026"
  }
}

1.3 下载视频

bash

# 方式一：直接访问结果 URL（限时有效）
curl -L -o output.mp4 "$(metadata.url 的值)"

# 方式二：平台代理下载（不受结果链接时效影响，要求任务已 completed）
curl -sL https://confluia.com/v1/videos/{task_id}/content \
  -H "Authorization: Bearer sk-你的密钥" -o output.mp4

metadata.url 由上游生成、限时有效。若链接过期（返回 404 / 403），重新调用查询接口 GET /v1/videos/{task_id} 获取新链接，或使用代理下载。代理下载需要任务已 completed，否则返回 400。

1.4 状态流转与进度

`status`	说明
`queued`	已受理，等待上游调度
`in_progress`	正在生成
`completed`	生成成功，可下载
`failed`	生成失败，`error` 含原因
`unknown`	内部罕见状态（例如任务刚入库、尚未完成首轮同步），可继续轮询

状态机是单向的：queued → in_progress → completed（或 failed）。

关于 progress

progress 是按状态推导的近似值，不是上游真实生成百分比，且数值随模型不同：

模型	排队	生成中	完成
MiniMax H3	20	30	100
Seedance	10	50	100

请用 status 判断任务进展，不要用 progress 绘制精确进度条。建议轮询间隔 5~15 秒。

1.5 完整调用示例（提交 → 轮询 → 下载）

第 1 步：提交任务

bash

curl -s https://confluia.com/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "一位宇航员漫步在火星表面，电影级光影",
    "size": "1280x720",
    "duration": 4
  }'

返回 {"id":"task_xxx","task_id":"task_xxx","status":"queued", ...}，后续用其中的 task_id 查询。

第 2 步：轮询任务状态（每 5~15 秒一次，直到 completed / failed）

bash

curl -s https://confluia.com/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-你的密钥"

第 3 步：下载成片

bash

curl -sL https://confluia.com/v1/videos/task_xxx/content \
  -H "Authorization: Bearer sk-你的密钥" -o output.mp4

完整 Python 脚本（替换域名与密钥后可直接运行）：

python

import time
import requests

BASE = "https://confluia.com"       # 替换为你的 API 地址
KEY = "sk-你的密钥"
headers = {"Authorization": f"Bearer {KEY}"}

# 1. 提交任务（异步：此处只返回 task_id）
resp = requests.post(f"{BASE}/v1/videos", headers=headers, json={
    "model": "MiniMax-H3",
    "prompt": "一位宇航员漫步在火星表面，电影级光影",
    "size": "1280x720",   # 也可写 "16:9"（只指定比例，分辨率取默认 768P）
    "duration": 4,        # MiniMax H3：4~15 秒，缺省 4
}, timeout=60)
if resp.status_code != 200:
    raise SystemExit(f"提交失败 {resp.status_code}: {resp.text}")
task_id = resp.json()["task_id"]
print("task_id:", task_id)

# 2. 轮询（通常需要数十秒到几分钟）
while True:
    data = requests.get(f"{BASE}/v1/videos/{task_id}", headers=headers, timeout=60).json()
    print("status:", data["status"])
    if data["status"] == "completed":
        print("video:", data["metadata"]["url"])
        break
    if data["status"] == "failed":
        raise SystemExit(f"生成失败: {data.get('error')}")
    time.sleep(10)

# 3. 代理下载（不受结果链接时效影响）
with requests.get(f"{BASE}/v1/videos/{task_id}/content",
                  headers=headers, stream=True, timeout=300) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(1 << 20):
            f.write(chunk)
print("saved:", f"{task_id}.mp4")

二、MiniMax v2 / v1 原生接口

若希望严格按 MiniMax 官方协议提交（多模态 content 数组），可使用原生入口。适合已有 MiniMax 官方客户端、希望协议完全对齐的用户。

2.1 v2 提交任务

POST https://confluia.com/v2/video_generation
Authorization: Bearer sk-你的密钥
Content-Type: application/json

请求体（首尾帧场景示例）：

json

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "prompt，必填，≤7000 字符" },
    { "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": 8,
  "aigc_watermark": false
}

请求体（参考素材场景示例）：

json

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "prompt，必填，≤7000 字符" },
    { "type": "image_url", "image_url": { "url": "https://example.com/ref1.jpg" }, "role": "reference_image" },
    { "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" }, "role": "reference_video" }
  ],
  "resolution": "768P",
  "duration": 8
}

首尾帧与参考类输入（参考图 / 视频 / 音频）互斥，不要在同一个 content 里混用。两类场景都可以缺省 ratio（按 adaptive 处理）；纯文生视频则必须给具体比例。

响应体：

json

{
  "task_id": "1860e25a08ed7aebd0a1430d4b611b9g"
}

2.2 v2 查询任务

GET https://confluia.com/v2/query/video_generation/{task_id}
Authorization: Bearer sk-你的密钥

完成时：

json

{
  "task": {
    "id": "1860e25a08ed7aebd0a1430d4b611b9g",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": { "url": "https://...(限时有效)", "prompt": "..." },
    "resolution": "2K",
    "duration": 8,
    "ratio": "16:9",
    "created_at": 1690000000,
    "updated_at": 1690000120,
    "usage": {
      "total_seconds": 12,
      "input_seconds": 7,
      "output_seconds": 5,
      "input_image_count": 6
    }
  }
}

status 取值：queued / running / succeeded / failed / cancelled。失败时 task.error 含 code 与 message。

v2 入口的错误响应为 MiniMax v2 风格包络： { "type": "error", "error": { "type": "...", "message": "...", "http_code": "..." }, "request_id": "..." }

2.3 v1 兼容入口

老型号（Hailuo-2.3 / Hailuo-02 / T2V / I2V / S2V 等）走 v1 协议，按请求中的 model 自动路由：

POST https://confluia.com/v1/video_generation
GET  https://confluia.com/v1/query/video_generation?task_id={task_id}

提交响应（v1 形态）：

json

{ "task_id": "task_xxx", "base_resp": { "status_code": 0 } }

查询响应（v1 形态）：status 为大写枚举 Processing / Success / Fail，成片地址在 video_url：

json

{
  "task_id": "task_xxx",
  "status": "Success",
  "video_url": "https://...(限时有效)",
  "base_resp": { "status_code": 0 }
}

v1 形态下"排队中"与"生成中"都返回 Processing，不进一步区分；失败时 base_resp.status_code 非 0 且 status_msg 给出原因。注意 v1 查询用 ?task_id= 查询参数，v2 是路径参数 /{task_id}。

三、Seedance 模型

Seedance（方舟）系列视频模型通过 OpenAI 兼容入口接入，查询与下载路径与 MiniMax H3 完全一致，差异只在提交参数与计费方式。

3.1 接入方式

操作	路径
提交	`POST /v1/videos`（等价 `POST /v1/video/generations`）
查询	`GET /v1/videos/{task_id}`
下载	`GET /v1/videos/{task_id}/content`

3.2 模型与能力

模型	输出分辨率	参考视频输入	音频输出
`doubao-seedance-1-0-pro-250528`	480p / 720p / 1080p	✗	—
`doubao-seedance-1-0-lite-t2v`	480p / 720p / 1080p	✗	—
`doubao-seedance-1-0-lite-i2v`	480p / 720p / 1080p	✗	—
`doubao-seedance-1-5-pro-251215`	480p / 720p / 1080p	✗	✓（`metadata.generate_audio`，缺省为开）
`doubao-seedance-2-0-260128`	480p / 720p / 1080p / 4k	✓	—
`doubao-seedance-2-0-fast-260128`	480p / 720p	✓	—
`doubao-seedance-2-0-mini-260615`	480p / 720p	✓	—

mini 与 fast 只支持 480p / 720p。 提交超出模型能力的档位不会在提交时报错，但会在上游生成阶段失败，请按上表选择；计费预扣按你声明的分辨率估算（未声明时按该模型最高档预扣，最高 1080p），结算按上游实际用量多退少补。

3.3 提交任务

最简文生视频：

json

{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "一只橘猫坐在窗台上看雨，窗外霓虹灯光闪烁，电影感镜头",
  "seconds": "5"
}

bash

curl -s https://confluia.com/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-mini-260615",
    "prompt": "一只橘猫坐在窗台上看雨",
    "seconds": "5"
  }'

指定分辨率与画幅（通过 metadata）：

json

{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "一只橘猫坐在窗台上看雨，窗外霓虹灯光闪烁，电影感镜头",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9"
  }
}

图生视频（首帧）—— 使用 images 数组或 image 单图：

json

{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "镜头缓慢推进，光影流动",
  "images": ["https://example.com/first.jpg"],
  "seconds": "5"
}

Seedance 的 image 单图字段与 images 数组均有效（image 等价于单元素 images）。

带参考视频（仅 2.x）—— 通过 metadata.content 传入：

json

{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "让视频中的人物转头看向镜头",
  "seconds": "8",
  "metadata": {
    "resolution": "720p",
    "content": [
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/ref.mp4" },
        "role": "reference_video"
      }
    ]
  }
}

提示词只写在顶层 prompt。metadata.content 里的媒体条目会被透传给上游，但其中的 text 条目会被丢弃（不会与 prompt 合并）。带视频输入的素材单价更低（见 3.6）。

提交响应（与其他视频模型一致）：

json

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "queued",
  "progress": 0,
  "created_at": 1690000000
}

3.4 请求参数

顶层字段：

字段	类型	必填	说明
`model`	string	✓	见 3.2 模型表
`prompt`	string	✓	非空文本
`seconds`	string	—	时长（秒），推荐写法
`duration`	int	—	时长（秒）；两者都给时 `seconds` 优先。均缺省时按 5 秒估算并交由上游默认
`images`	string[]	—	参考图数组，传 1 张即为图生视频
`image`	string	—	单张参考图，等价于单元素 `images`
`metadata`	object	—	扩展字段，见下表
`size`	string	—	不生效，请用 `metadata.resolution` + `metadata.ratio`

最少只要 model + prompt 即可提交：缺省时按 5 秒、模型最高分辨率档（≤1080p）做预扣估算，实际输出规格由上游决定。需要精确控制输出规格时再加 metadata。

metadata 扩展字段（全部可选，原样透传上游）：

字段	类型	说明
`resolution`	string	`480p` / `720p` / `1080p` / `4k`，按模型能力，见 3.2
`ratio`	string	画幅比例，如 `16:9` / `9:16` / `1:1`
`duration`	int	时长（秒），等价顶层 `duration`
`frames`	int	帧数（与 `duration` 二选一）
`seed`	int	随机种子
`watermark`	boolean	是否带水印
`camera_fixed`	boolean	固定镜头
`generate_audio`	boolean	是否生成音频（仅 1.5 pro，缺省为开）
`draft`	boolean	草稿模式
`content`	array	多模态内容数组，用于参考视频等高级输入，见 3.3
`callback_url`	string	生成完成后的回调地址
`return_last_frame`	boolean	是否返回尾帧
`execution_expires_after`	int	任务执行超时（秒）
`tools`	array	工具声明，形如 `[{"type": "..."}]`
`service_tier` / `priority` / `safety_identifier`	—	原样透传

顶层 seconds / duration 与 metadata 中的时长取值范围为 0 ~ 3600 秒（0 视为未设置），超出范围提交即返回 400 invalid_seconds。

3.5 查询与下载

与其他视频模型完全一致：

bash

# 查询（status: queued / in_progress / completed / failed）
curl -s https://confluia.com/v1/videos/task_xxxxxxxxxxxx \
  -H "Authorization: Bearer sk-你的密钥"

# 代理下载（不受结果链接时效影响）
curl -sL https://confluia.com/v1/videos/task_xxxxxxxxxxxx/content \
  -H "Authorization: Bearer sk-你的密钥" -o out.mp4

完成后成片地址在 metadata.url。

3.6 计费说明

Seedance 按 token 计价（与 MiniMax H3 的按秒计价不同）。计费 token 按官方公式估算：

tokens = 时长(秒) × 宽 × 高 × 24 / 1024

其中宽 × 高按输出分辨率的 16:9 标准档取值（如 720p 为 1280×720）。单价按输出分辨率与是否含视频输入分档（单位：元 / 百万 token）：

模型	480p / 720p	1080p	4k
`doubao-seedance-2-0-260128`	46（不含视频）/ 28（含视频）	51 / 31	26 / 16
`doubao-seedance-2-0-fast-260128`	37 / 22	—	—
`doubao-seedance-2-0-mini-260615`	23 / 14	—	—

提交时按时长与分辨率预扣，任务完成后按上游返回的实际 token 数多退少补；
带视频输入时单价更低（上表各行的「含视频」档）；
未在上表列出的型号（1.0 / 1.5 系列）以控制台「价格 / 模型列表」页面为准。

四、主要参数

4.1 OpenAI 兼容入口（MiniMax H3，扁平字段）

参数	类型	必填	说明
`model`	string	✓	`MiniMax-H3` 或其展示别名（如 `minimax-h3-768p` / `minimax-h3-2k`）
`prompt`	string	✓	视频描述，≤7000 字符
`image`	string	—	单张首帧图（URL / Base64 data URI）
`input_reference`	file / string	—	multipart 上传首帧文件，或直接给 URL / Base64
`first_frame_image`	string	—	首帧图（URL / Base64）
`last_frame_image`	string	—	尾帧图（URL / Base64）
`images`	string[]	—	角色参考图数组（≤9 张）；提供首 / 尾帧时会被忽略
`subject_reference`	array	—	角色参考图，形如 `[{"type":"character","image":["url1"]}]`；同 `images`
`duration` / `seconds`	int / string	—	时长（秒），`4` ~ `15`，缺省 `4`；两者都给时 `seconds` 优先
`size`	string	—	像素尺寸或画幅比例串，见下方取值表
`ratio`	string	—	画幅比例：`adaptive` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
`resolution`	string	—	`768P` / `2K`，优先级高于 `size` 推导
`aigc_watermark`	boolean	—	是否携带 AIGC 水印
`callback_url`	string	—	不支持，传入返回 `400 unsupported_callback_url`

size 取值与映射：

`size`	分辨率	画幅
`768p`	768P	16:9
`2k`	2K	16:9
`768x768`	768P	1:1
`1024x1024`	2K	1:1
`1280x720`	768P	16:9
`720x1280`	768P	9:16
`1792x1024` / `1920x1080`	2K	16:9
`1024x1792` / `1080x1920`	2K	9:16
`21:9` `16:9` `4:3` `1:1` `3:4` `9:16`（比例串）	默认 768P	该比例

参数取值规则：

image / input_reference / first_frame_image 均表示首帧（multipart 文件 > first_frame_image > input_reference > image），last_frame_image 表示尾帧。
提供首 / 尾帧时 ratio 固定为 adaptive（跟随输入画面比例）。
提供 images 或 subject_reference 表示角色参考生成，不要与首尾帧混用（会被忽略）。
纯文生视频缺省 size 时默认 16:9 + 768P；显式传入的 resolution / ratio 优先于 size 推导。
未识别的字段会被忽略，不影响请求。

4.2 MiniMax v2 原生入口（content 数组）

字段	类型	必填	说明
`model`	string	✓	`MiniMax-H3`
`content`	array	✓	多模态内容组合，见下表
`resolution`	string	✓	`768P` / `2K`
`duration`	int	✓	时长（秒），`4` ~ `15`
`ratio`	string	视场景	纯文本必填且不能为 `adaptive`；含首帧 / 参考输入时可缺省
`aigc_watermark`	boolean	—	AIGC 水印
`callback_url`	string	—	不支持，返回 `400`

content 元素与数量上限：

`type`	载荷字段	`role`	数量上限
`text`	`text`	无	非空必填，≤7000 字符
`image_url`	`image_url.url`	`first_frame` / `last_frame` / `reference_image`	首帧 ≤1、尾帧 ≤1、参考图 ≤9
`video_url`	`video_url.url`	`reference_video`	≤3
`audio_url`	`audio_url.url`	`reference_audio`	≤3

content 组合规则（提交前在网关侧校验，不合法返回 400）：

text 非空必填；
首尾帧与参考类输入（参考图 / 视频 / 音频）互斥（invalid_content）；
仅有 reference_audio 时必须同时提供参考图或参考视频；
纯文本生成必须给具体 ratio（不能为 adaptive 或缺省）；含首帧或参考输入且未给 ratio 时按 adaptive 处理；
媒体可用 URL、mm_file://{file_id} 或 Base64 data URI；请求体 ≤64MB。

五、计费说明

本章描述 MiniMax H3 的按秒计价。Seedance 按 token 计价，见 3.6。

MiniMax H3 按生成秒数计价，采用「提交时预扣、完成后按上游实际用量结算」：

预扣：每秒单价 × 请求时长；若含参考视频输入，另按上限预留 15 秒输入折算（参考图不参与预留）。
结算：任务完成后按上游返回的实测用量（输出秒数 + 参考视频折算秒数）重算，多退少补；输出与输入素材是否采用不同单价以价格页的计费表达式为准。
失败：上游失败且未返回用量时，预扣额度保留（不自动退款）。
超时：提交后长时间（默认 24 小时）未出结果的任务判定为失败，退还预扣额度（以日志明细为准）。

每秒单价以控制台「价格 / 模型列表」页面为准（官方价：768P 0.5/秒、2K 0.8/秒）。使用 minimax-h3-768p / minimax-h3-2k 这类展示别名时，按别名对应的单价计费。

展示别名的准确含义

分辨率由请求中的 resolution / size 决定，别名本身不携带分辨率。用 minimax-h3-2k 提交但未指定分辨率时，仍按默认 768P 生成（只是按 minimax-h3-2k 的单价计费）。

参考图 / 参考视频是否单独计价：默认可按输入素材折算；实际是否启用以控制台价格页的计费表达式为准。

六、错误处理与限制

6.1 错误响应形态

不同入口的错误结构不同，请按 code / message 处理，不要只依赖 HTTP 状态码：

入口	非 2xx 响应体（示例）
OpenAI 兼容（`/v1/videos`、`/v1/video/generations`）	`{"code":"invalid_size","message":"...","data":null}`
v2 原生（`/v2/video_generation`）	`{"type":"error","error":{"type":"bad_request_error","message":"...","http_code":"400"}}`
v1 原生（`/v1/video_generation`）	`{"base_resp":{"status_code":400,"status_msg":"..."}}`

6.2 常见错误与处理

`code`	HTTP	原因	处理
`invalid_size`	400	`size` 不在支持列表	用像素尺寸或比例串，取值见 4.1
`invalid_ratio`	400	`ratio` 不在支持列表，或 v2 原生纯文本给了 `adaptive` / 缺省	纯文生视频给具体比例（`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`）
`invalid_duration`	400	MiniMax H3 时长不在 `4`~`15` 秒	修正 `duration` / `seconds`
`invalid_seconds`	400	Seedance 等任务时长超出 `0`~`3600` 秒	修正时长
`invalid_resolution`	400	`resolution` 不是 `768P` / `2K`	修正 `resolution`
`invalid_content`	400	缺 `prompt`、首尾帧与参考类输入混用（v2 原生）、媒体数量超限、请求体超 64MB	按 `message` 修正请求体
`unsupported_callback_url`	400	MiniMax H3 传入了 `callback_url`	该参数不支持，改用轮询
`insufficient_user_quota`	403	余额不足支付预扣	充值后重试
`async_task_concurrency_limit`	429	单账号"排队中 + 生成中"的异步任务达到并发上限	等已有任务完成后再提交，或联系客服调整上限
上游负载饱和	429 / 5xx	分组上游临时繁忙	指数退避重试（重试前确认上一次没有拿到 `task_id`）

6.3 使用限制（MiniMax H3）

Seedance 的能力与参数差异较大，见 3.2 与 3.4。

时长：4 ~ 15 秒；一次提交只生成 1 个视频（n / count 对 MiniMax H3 无效）。
媒体数量：首帧 ≤1、尾帧 ≤1、参考图 ≤9、参考视频 ≤3、参考音频 ≤3；请求体 ≤64MB。
文本：prompt 必填，≤7000 字符。
任务归属：任务与提交它的账号绑定，查询与下载只能访问自己的任务（管理员除外）。
未知状态：上游罕见地返回未登记状态时，任务保持「生成中」并继续轮询，不会误判失败。

6.4 推荐的重试姿势

提交接口：仅当返回 429 / 5xx 时重试；重试前先确认上一次请求没有拿到 task_id，避免重复生成与重复计费。
查询接口：幂等，可自由重试；建议 5~15 秒间隔，对 429 / 5xx 做指数退避。
下载接口：可重试；代理下载要求任务已 completed，否则返回 400。

七、常见问题

两套模型的差异速查：

维度	MiniMax H3	Seedance（方舟）
提交入口	OpenAI 兼容 + MiniMax v2 / v1 原生	仅 OpenAI 兼容
分辨率字段	`size`（像素尺寸或比例串）或 `resolution`	`metadata.resolution` + `metadata.ratio`（顶层 `size` 不生效）
首帧字段	`image` / `input_reference` / `first_frame_image` / multipart 等价	`images` 数组或 `image` 单图
时长字段	`duration`（int）或 `seconds`（string），`4`~`15` 秒，缺省 `4`	同左；缺省按 5 秒估算
参考视频输入	v2 原生 `content`（≤3 条），影响计费	仅 2.x，`metadata.content`，单价更低
计费方式	按秒单价（每秒单价 × 实测秒数）	按 token（时长 × 宽 × 高 × 24 / 1024）
计费表达式维度	`seconds` / `resolution` / `input_images` / `input_video_seconds`	`tokens` / `resolution` / `video_input` / `generate_audio`
查询 / 下载	`GET /v1/videos/{task_id}`、`/content`	同左（完全一致）

提交后马上返回、没有视频？ 视频为异步任务，需轮询 /v1/videos/{task_id} 直至 completed，再用 metadata.url 下载。
下载链接 404 / 403？ 结果链接限时有效，重新查询任务拿新链接，或使用 /v1/videos/{task_id}/content 代理下载。
返回 invalid_duration？ MiniMax H3 的 duration 需在 4~15 秒之间。
返回 invalid_ratio？ MiniMax v2 原生入口的纯文本生成必须给具体比例（不能为 adaptive 或缺省）。
任务 failed（内容审核等）？ 多为安全审核未通过，请调整提示词或参考图后再试。
callback_url 报 400？ MiniMax H3 不支持回调，请使用任务轮询。
Seedance 时长不生效？ 优先使用字符串形式 "seconds": "5"；seconds 优先于整数 duration。
Seedance 设置了 size 没效果？ Seedance 不读顶层 size，分辨率 / 画幅请用 metadata.resolution / metadata.ratio。

视频生成 ​

一、OpenAI 兼容接口 ​

1.1 提交视频任务 ​

1.2 查询任务状态 ​

1.3 下载视频 ​

1.4 状态流转与进度 ​

1.5 完整调用示例（提交 → 轮询 → 下载） ​

二、MiniMax v2 / v1 原生接口 ​

2.1 v2 提交任务 ​

2.2 v2 查询任务 ​

2.3 v1 兼容入口 ​

三、Seedance 模型 ​

3.1 接入方式 ​

3.2 模型与能力 ​

3.3 提交任务 ​

3.4 请求参数 ​

3.5 查询与下载 ​

3.6 计费说明 ​

四、主要参数 ​

4.1 OpenAI 兼容入口（MiniMax H3，扁平字段） ​

4.2 MiniMax v2 原生入口（content 数组） ​

五、计费说明 ​

六、错误处理与限制 ​

6.1 错误响应形态 ​

6.2 常见错误与处理 ​

6.3 使用限制（MiniMax H3） ​

6.4 推荐的重试姿势 ​

七、常见问题 ​

视频生成

一、OpenAI 兼容接口

1.1 提交视频任务

1.2 查询任务状态

1.3 下载视频

1.4 状态流转与进度

1.5 完整调用示例（提交 → 轮询 → 下载）

二、MiniMax v2 / v1 原生接口

2.1 v2 提交任务

2.2 v2 查询任务

2.3 v1 兼容入口

三、Seedance 模型

3.1 接入方式

3.2 模型与能力

3.3 提交任务

3.4 请求参数

3.5 查询与下载

3.6 计费说明

四、主要参数

4.1 OpenAI 兼容入口（MiniMax H3，扁平字段）

4.2 MiniMax v2 原生入口（content 数组）

五、计费说明

六、错误处理与限制

6.1 错误响应形态

6.2 常见错误与处理

6.3 使用限制（MiniMax H3）

6.4 推荐的重试姿势

七、常见问题