视频生成 API 接入说明

060 秒判断

三条会改变你代码写法的硬事实

1. 终态有四个，不是一个。 completed / failed / qc_failed / cancelled。 漏掉 qc_failed 会让轮询循环永远跑下去（它不交付、不计费）。见 §7。
2. 建单 200 ≠ 参数合法。 大量参数问题会在建单时 400（2026-11-03 起提前判定）， 但素材层面的问题仍要拿到素材才能判，表现为「建单 200 → 数秒后 failed」。判据是终态，不是建单 HTTP 码。见 §10.4。
3. duration 是「至少」不是「正好」。 传 duration: 4 出的片子是 124 帧 / 5.1667 秒 （实测，见 §1）；响应里的 duration_secs 仍回你请求的 4.0。要精确控时长用 num_frames。

一分钟自检你手上的 Key

curl -s "https://api.123all.cn/api/v1/reseller/tokens/verify?key=sk-omni-xxxxxxxx"
# 期望：{"active":true, ... } —— active=false 就别往下试了

真实响应与字段解释见 §2；两种 401 的原文也在那里。

1快速开始（2026-11-05 真实跑通）

下面三段不是示意，是 2026-11-05 14:47（+08:00）在公网域名 api.123all.cn 上真跑的一条请求： 提交 → 轮询 → 取片，附完整响应、耗时、字节数与 ffprobe 结果。

第 1 步 · 提交作业（181 毫秒返回）

curl -s -X POST https://api.123all.cn/v1/videos \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-hyper",
       "prompt":"海边日落，海浪拍岸，电影感，镜头缓慢推进",
       "duration":4,"resolution":"480p","ratio":"16:9"}'

HTTP/1.1 200 OK   （实测 181 ms）
{"id":"video_3f9371a03b7747ecb63f73f9e4a33a2d","object":"video",
 "status":"queued","model":"minimax-h3-hyper","created_at":1793861261}

第 2 步 · 轮询（5–10 秒一次，只在终态结束）

curl -s https://api.123all.cn/v1/videos/$ID -H "Authorization: Bearer $KEY"

{"id":"video_3f9371a03b7747ecb63f73f9e4a33a2d","object":"video","status":"completed",
 "model":"minimax-h3-hyper","created_at":1793861261,
 "qc":{"verdict":"Pass","sobel_mean":13.2217,"blank_frac":0.0,"freeze_diff":16.3814,
       "lap_var":917.1292,"soft":false,"frames_sampled":8,"clipped_samples":0,
       "clipped_ratio":0.0,"notes":[]},
 "url":"/v1/videos/video_3f9371a03b7747ecb63f73f9e4a33a2d/content"}

这条作业的完整时间线（轮询间隔 5 秒，共 18 次）：

第 3 步 · 取片（这一步最容易踩）

curl -fL -o out.mp4 "https://api.123all.cn/v1/videos/$ID/content" \
  -H "Authorization: Bearer $KEY"
file out.mp4        # 期望：ISO Media, MP4 v2
ls -l out.mp4       # 期望：4035364

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Length: 4035364

同一批次的另外两单（2026-11-05 实测）

三单同一秒提交、同一条通道池排队。竖屏那单走的是 vdn，交付 480×864 —— 与 §3.2 那张尺寸表逐像素一致（承诺值）。带画风那单比另外两单多等了一倍， 因为画风要单独准备资源（§6.5），且当时排在前两单后面。

如果你只想先跑通一次

export KEY=sk-omni-xxxxxxxx          # 换成发给你的 Key
export BASE=https://api.123all.cn

JOB=$(curl -s -X POST $BASE/v1/videos \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"model":"minimax-h3-hyper","prompt":"海边日落，海浪拍岸","duration":4,"resolution":"480p"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')
echo "job=$JOB"

while :; do
  S=$(curl -s "$BASE/v1/videos/$JOB" -H "Authorization: Bearer $KEY")
  ST=$(printf '%s' "$S" | python3 -c 'import sys,json;print(json.load(sys.stdin)["status"])')
  echo "status=$ST"
  case "$ST" in completed|failed|qc_failed|cancelled) break;; esac
  sleep 6
done

case "$ST" in
  completed) curl -fL -o out.mp4 "$BASE/v1/videos/$JOB/content" -H "Authorization: Bearer $KEY"
             file out.mp4 ;;
  *)         printf '%s\n' "$S" ;;     # 把 error / qc 原样打出来
esac

2认证与自检

2.1 请求头

Authorization: Bearer sk-omni-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key 的格式是 sk-omni- + 32 位十六进制。它是密文：不要贴进前端代码、公开仓库或工单。 服务端不会再有第二处能读到明文；列表接口只回掩码。

• 一把 Key 绑一个账户：用量、配额、账目互不串。要分账就分 Key。
• Key 的模型白名单是逐把配的（默认 minimax-h3-*,doubao-seedance-*）。
• 配额用尽 / 停用 / 过期都会让 active 变 false，调用随即 401。

2.2 先自检这把 Key（不需要任何其它凭据）

curl "https://api.123all.cn/api/v1/reseller/tokens/verify?key=sk-omni-xxxxxxxx"

真实响应 实测 2026-11-05 · 46 ms（账户字段已脱敏）：

{
  "active": true,
  "scopes": ["video:generate", "chat:completion", "mcp:tool"],
  "quota": 0.0,
  "consumed": 35.0,
  "bound_account_id": "agency:<你的代理商>"
}

consumed 是最终一致的：作业交付时累加，同步有延迟。 它适合看「Key 还能不能用」，不适合当精确用量 —— 精确用量请找我们对账。

2.3 两种 401，原文不一样

401
{"code":"modality.key.denied",
 "params":{"detail":"出片接口需要有效凭据：license JWT / 登录态 JWT / 未过期且未超额的 sk-omni API key"},
 "message":"出片接口需要有效凭据：…"}

401
{"code":"modality.key.invalid",
 "params":{},
 "message":"API key 无效、已停用、已过期或已超额"}

两条都是 实测 2026-11-05（141 ms / 143 ms）。 写客户端时按 code 分支，别匹配 message —— 那是给人读的中文，会改。

3模型 / 档位 / 画幅

3.1 三条通道，能力不一样

3.2 档位由「节点画布」决定，不是模型本身

自有引擎（minimax-h3-*）的五档分两组，一台节点只提供其中一组 —— 档位名相同但生成几何不同。这是很多人第一次接会踩的地方：

所以 768p 与 768p_native 的耗时差（73 s vs 143 s）来自生成分辨率不同， 不是超分。传了不在列表里的档，建单时同步 400 并列出可用清单（真实原文见 §10.3）。

3.3 resolution × ratio 的成片尺寸（承诺值）

六档画幅全部开放（2026-11-03 起）。不传 ratio 就是 16:9。 下面这张表是逐像素核对过的承诺值：按它排版、裁切不会差像素。

2026-11-05 复验：vdn + 480p + 9:16 实得 480×864， 与表中一致（ffprobe 读的是成片，不是响应）。

3.4 耗时：分「准备好了」和「要准备」两档

① 全档复测 实测 2026-10-22（同一把 Key、公网域名、duration=4、ratio=16:9、 seed=4242、轮询 5 秒）。「墙钟」= 建单到成片落盘，含排队；建单本身 0.3–1.6 秒返回 queued。

② 会明显更慢的四类请求 实测 2026-10-31（4 秒片 / 480p）：

画幅对耗时的影响 实测 2026-11-03 · 节点直测（不含排队）

换画幅不改生成面积，所以耗时同量级（±20%）。竖屏长边更长，超分多处理些行，略慢。 hyper 同口径：480p 竖屏 90 s / 方屏 85 s；768p 方屏 95 s / 竖屏 115 s。

3.5 复现：seed 是抓手，不是缓存键

• 不传 seed 时服务端用固定默认值 ⇒ 同一 prompt 反复投会得到同一条片（看起来像缓存，其实是确定性生成）。
• 要每次不同：每次传不同的 seed。要复现某条：把当时的 seed 记下来再传。
• 同 seed 重投，画面内容一致，但像素级可能有约 1% 差异（不同服务实例的计算细节不同）。 需要逐字节相同（素材比对、算 diff）请事先联系我们，默认做不到。

4请求参数

POST /v1/videos
Content-Type: application/json
Authorization: Bearer sk-omni-…

4.1 通用参数

4.2 content[]：四种元素

三种媒体的地址也支持 asset://<素材ID>（先上传到素材库，见 §5.5）。

值的两种形态

{"type":"image_url","image_url":{"url":"https://…/a.png"},"role":"reference_image"}   // 对象形态（官方写法）
{"type":"image_url","image_url":"https://…/a.png","role":"reference_image"}             // 字符串形态（同样收）

4.3 图片的另一种写法：扁平字段（与 content[] 二选一）

400
{"code":"modality.content.mixed_forms","params":{},
 "message":"content[] 里已经有图片，同时又给了 first_frame_image 这类扁平字段 —— 只用一种写法（挑一个会让另一半静默失效）"}

4.4 任务是从素材形状「推」出来的（不是参数）

没有 task 字段 —— 照抄方舟：任务类型由 content[] 的形状决定。

参考配额（逐通道不同，别照搬）

「音频不能单独给」是上游契约：音频决定音色 / 语速，画面仍需要一张图或一段视频当主体。 它不在建单时拒（实测 2026-11-05：200 queued，4.3 秒后 failed，原文见 §10.4）。

4.5 时长：duration 是「至少」

5素材与素材库

5.1 素材规格：逐通道对照（含官方口径）

两家的数不一样，别互相代入。这不是我们分两套，而是上游各自的官方限制本来就不同 —— 最典型的是「参考视频多大」：方舟 200 MB，MiniMax H3 50 MB，差 4 倍。

官方手册还写明：输出 4–15 秒、24 fps、全部带声音（原生双声道）；768p 档短边 768， 16:9~9:16 之外按“约 1M 像素”重算（例如 21:9 = 1536×672）—— 与我们的 768p_native 行一致。

5.2 素材怎么给：优先公网 URL

61.9 KB → 过        64.5 KB → 不过      ← 正对上游那个 65,535 字节的字段上限
0.25 MB → 也不过    4.74 MB → 也不过

{"status":"failed","error":"[502 Bad Gateway] Upstream error [500]:
  AI Gate CreateTask 返回 500 Internal Server Error: {…\"message\":\"Data too long for column 'form' at row 1\"}"}

5.3 三层请求体上限（谁拦你，含义不同）

30 MB 管「这一张合不合法」，64 MB 管「这一次一共要了多少」—— 少了后者，30 张满档图每张单独都合法、合起来却能压垮请求。两层都要有，各报各的错。

5.4 引用协议：asset:// 与 mm_file://

我们收两个名字。判据落在 ID 前缀上，不在协议名上 —— 从官方文档抄来的 mm_file:// 代码，我们照样收。

5.5 素材库：传一次，用多次

同一张参考图/视频要用在很多个作业上时，不要每次重传 base64（会把请求体撑大、也拖慢建单）。 先传上来拿一个 ID，之后每个作业里写 asset://<ID>。

上传 · 实测 2026-11-05 · 200

POST /v1/assets
{"name":"样例-1x1.png","data":"data:image/png;base64,iVBORw0KGgo…"}

{"id":"asset-omni-f5251062c1f64373a87903e8b59b8a9d",
 "uri":"asset://asset-omni-f5251062c1f64373a87903e8b59b8a9d",
 "kind":"image","name":"样例-1x1.png","content_type":"image/png","bytes":75,
 "sha256":"ebda4d4ace3059d20d30b04f8fb1a9390f9e8bd8cd2117fca38db09ba2efa1a0",
 "created_at":1793861514,
 "public_url":"http://<素材主机>/v1/artifacts/assets/20261105/asset-omni-f525….png"}

管理自己的素材

按「归属账户」隔离：别人的素材 ID 在你这儿一律 404，答复与「不存在」刻意不区分 （否则就能靠错误文案枚举别人有哪些素材）。删掉之后再用那个 asset:// 建单，建单 200、3.1 秒后 failed：

{"id":"video_3a8d4fb6e58b4d729bed44c61b30196b","object":"video","status":"failed", …,
 "error":"[400 Bad Request] {\"code\":\"modality.asset.parse_failed\",
   \"params\":{\"code\":\"modality.invalid_request\",\"detail\":\"asset not found: asset-omni-f525…\"},
   \"message\":\"素材引用解析失败：asset not found: …\"}"}

素材库的限制（它是「内联」，不是「大文件托管」）

注意 72 MB ≠ 官方那个 64 MB：官方的 64 MB 管的是「生成请求里内联素材总量」； 本接口的请求体里只有一件素材，所以它的上限由「最大单件」推出来。混用一个数会让 50 MB 的视频永远传不上来（它的 base64 是 66.7 MB）。

5.6 三条已知边界（挑素材前先知道）

• 真人像会被上游拒：InputImageSensitiveContentDetected.PrivacyInformation（“may contain real person”）。 真人素材必须用上游授权的素材库，URL 绕不过这道闸。
• 要位图格式：SVG 返 InvalidParameter.UnsupportedImageFormat。
• URL 必须上游抓得到：抓不到的表现是 resource download failed。先在你自己的机器上 curl 一遍确认可达，再提交。

# 请求：content 里给了一个不存在的音频 URL
POST /v1/videos → 200 queued   （187 ms，拿到了 job id）
# 4.3 秒后 GET
{"id":"video_7d5538fa64014f3cbfb32ad3d7986c89","object":"video","status":"failed",
 "model":"minimax-h3-hyper","created_at":1793861235,
 "error":"[400 Bad Request] Upstream error [400]: 远端 H3 拒绝提交 HTTP 400 Bad Request:
   {\"error\": {\"message\": \"取素材失败 https://example.com/a.mp3：HTTP Error 404: Not Found\"}}"}

6风格画风（loras）

一次请求可以让成片带上某种画风 —— 赛璐璐、水墨、90 年代港片、霓虹赛博、像素、子弹时间…… 而不用改提示词。做法是在建单请求里加一个 loras 数组。目前 45 种（清单见 附录 A）。

6.1 形状

{
  "model": "minimax-h3-vdn",
  "prompt": "一只橘猫在阳光下的花园里奔跑，电影感",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "loras": [{"id": "style_sumi_ink", "scale": 0.9}]
}

6.2 目录：GET /v1/loras（公开，不需要 Key）

curl -s https://api.123all.cn/v1/loras        # 可加 ?model=minimax-h3-vdn 只看某条通道能用的

{
  "object": "list",
  "max_loras": 3,
  "data": [
    {"id": "anime2d", "name": "2D Anime Cel-shading", "trigger": "2danime",
     "prepend_trigger": true, "strength": 0.9, "base": "minimax-h3-fl2va", "available_on": 3},
    {"id": "style_sumi_ink", "name": "Sumi-e Ink Wash", "category": "illustration",
     "trigger": "A sumiink painting style animation", "prepend_trigger": true,
     "strength": 0.9, "strength_range": [0.5, 1.3], "base": "minimax-h3-fl2va", "available_on": 3}
    …
  ]
}

实测 2026-11-05 · 395 ms · 45 条 该接口实测 < 1 秒，可放心在选风格时实时调用。 available_on 是有几台服务器装了这个画风 —— 不是每台都有，下单前用它判断更稳。

6.3 会慢多少（这决定你的超时）

不要按无画风那条数设 60 秒超时，否则会超时重投、把队列排得更长（§3.4）。

6.4 不会因为「画风鲜艳」被判成坏片

出库质检只拦「画面真的坏了」（结构破损、音频静音/爆音、片头未收敛等），不会因为画风饱和度高就拒付。 已实测：水墨、赛璐璐、以及 2 件叠加都正常交付。

「画面偏蓝/偏暗」这类内容本身也不会被判失败（2026-11-03 起）：判据比的是这条片自己的底色 —— 只有「某几帧明显比全片更蓝」（解码分块写坏）或「整段色彩崩塌」才拦。水下、夜空正常交付（实测 blue_excess 33.9 也放行）， 只在 qc 里留一条告警。

6.5 支持范围与限制

7作业与状态机

7.1 状态机（status 只有这几种）

7.2 一个真实的 completed 作业对象

{"id":"video_3f9371a03b7747ecb63f73f9e4a33a2d","object":"video","status":"completed",
 "model":"minimax-h3-hyper","created_at":1793861261,
 "qc":{"verdict":"Pass","sobel_mean":13.221747935070395,"blank_frac":0.0,
       "freeze_diff":16.381418099647266,"lap_var":917.1291633923171,
       "soft":false,"frames_sampled":8,"clipped_samples":0,"clipped_ratio":0.0,"notes":[]},
 "url":"/v1/videos/video_3f9371a03b7747ecb63f73f9e4a33a2d/content"}

这就是 2026-11-05 那条 hyper/480p/16:9 的作业，原样拷贝（只折了行）。

7.3 qc 字段的含义（别拿错指标做判据）

不要拿 sobel_mean 做自己的判据（它不决定 Pass/Fail），也别把 soft=true 当成「片子不合格」—— 它只是提示「细节偏软，建议目检」。

7.4 failed 的 error 怎么读

• 以 [数字] 开头，那个数字是上游 HTTP 码：[400] 上游拒收、[502] 服务端临时故障、[504] 上游超时。分支判这个前缀，别匹配后面的中文。
• H3 出片链失败时，末尾会带 （stage=…），值可能是 generating / upscaling / quality / ref2va_prep / delivered。 它只是诊断用，别按它分支——我们会加新值。
• 同一句里的中文阈值（如 0.6014 < 0.8）是当次判据的现场值，不是契约。

{"id":"video_1916d5c5278047c99d3ce76e9be11d54","object":"video","status":"qc_failed",
 "model":"minimax-h3-hyper","created_at":1793861658,
 "error":"[502 Bad Gateway] Upstream error [503]: 远端 H3 出片失败（stage=quality）:
   出库质检未过：edge_luma_ratio=0.011 < 0.4（片头亮度只有片尾的 1%：从近黑爬出/整片未收敛）"}

[502 Bad Gateway] Upstream error [503]: 远端 H3 出片失败（stage=quality）:
出库质检未过：tail_over_mid_norm=0.1782 < 0.8（对比度归一化后的尾/中清晰度；原始 tail/mid=0.11）

7.5 轮询建议

不要在客户端做忙等。queued 阶段可能持续数十秒，但慢的是生成段，不是排队。 参考类作业建议同时只留 1 个在途（与其它形态交替会更慢，§3.4）。

8取片

GET /v1/videos/{id}/content
Authorization: Bearer sk-omni-…

真实响应头 实测 2026-11-05：

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Length: 4035364

8.1 url 字段的两种形态（别当长期地址）

三条纪律：

1. 优先用 /content：形态统一、长期有效、带你自己的鉴权。
2. 若图省事直接用 url，请当天转存到自己的存储，别把链接存进数据库长期用。
3. 无论如何，拿到片子就转存，不要长期依赖我们这侧的链接。

8.2 同步模式（background:false）的响应是另一种形状

{"model":"minimax-h3-hyper",
 "data":[{"url":"http://<成片主机>/v1/artifacts/video/2026-09-23/video_76278e….mp4",
          "duration_secs":4.0,
          "thumbnail_url":null}]}

• 没有作业 id —— 同步模式一次性把结果给你，之后无法用 /v1/videos/{id} 查或 /content 取。
• url 是直链，主机是 IP:端口（在对客域名之外），境内客户不一定连得上。 把路径接到对客域名上即可：https://api.123all.cn/v1/artifacts/video/…/xxx.mp4（实测 200 / video/mp4）。
• 一次请求是一条挂住的长连接（实测 84 秒 / hyper+480p；慢档 3 分钟以上）。除脚本化场景外请用默认异步。

8.3 ⛔ 最常见的坑：把错误体当成片子写进文件

curl -o out.mp4 "…/content"
# 401 时：文件写成功、退出码 0
# out.mp4 内容是：
# {"code":"modality.key.denied",…}

curl -fL -o out.mp4 "…/content" -H "Authorization: Bearer $KEY"
# 出错时 curl 退出 22，一个字节都不落盘
file out.mp4   # ISO Media / MP4

根因：curl -o（不加 -f）会把任何 4xx/5xx 的响应体原样写进目标文件并返回 0。 2026-10-14 实测复现：$KEY 未设置时 header 退化成 Bearer （等同空）⇒ 服务端回 401 + JSON （{"code":"modality.key.denied",…}），-o 把它整段写进文件。

8.4 成果物直链是「知道就能下」的

实测把 url 的路径直接拼到对客域名上（https://api.123all.cn/v1/artifacts/…）， 不带任何鉴权头也是 200。链接里是一段随机 ID，别人猜不到，但你把它外发出去就等于把片子外发出去。 需要「只有我能取」的效果，请用 /content（它要你的 Key）。

8.5 附：列出自己的作业（实测可用）

GET /v1/videos?limit=3      # limit 1–100，默认 20；只返回这把 Key 归属的作业，最新在前
→ {"object":"list","data":[{…作业对象…}],"count":3}

2026-11-05 实测 200。用途：客户端崩了/重启后，按它核对「我到底建了哪些作业」， 不用逐 id 盲查。作业记录会落盘保留（没有官方的 7 天窗口），但也别当长期存储 —— 片子请及时取走。

9取消作业

DELETE /v1/videos/{id}

DELETE /v1/videos/video_3f9371a03b7747ecb63f73f9e4a33a2d  →  200
{"id":"video_3f9371a03b7747ecb63f73f9e4a33a2d","object":"video","status":"completed",
 "model":"minimax-h3-hyper","created_at":1793861261,
 "qc":{…},"url":"/v1/videos/video_3f9371a03b7747ecb63f73f9e4a33a2d/content"}

9.1 撤单是真的会停 实测 2026-11-03

三条使用建议：

1. 撤单成功后请以 GET 的 status 为准，不要假定就是 cancelled（可能已经 completed）。
2. 撤单幂等：同一个 id 反复撤都是 200，重试不会报错。
3. 撤单不回滚已交付的片子：如果 GET 已经是 completed，/content 照样能取 —— 那是你付过的那一单。

10错误码

错误分两类，形状不同。先说这条，因为它比下面任何一张表都更常踩： 只判「建单 200」会把全部异步失败漏掉。

10.1 2026-11-05 实测总表（公网域名，逐条投出来的）

10.2 建单即拒（A 类）· 原文逐条

下面每一条都是 实测 2026-11-05 的原样正文（只做了换行）。拿不到 job id 的都是这一类。

# 没带 Authorization
{"code":"modality.key.denied","params":{"detail":"出片接口需要有效凭据：license JWT / 登录态 JWT / 未过期且未超额的 sk-omni API key"},"message":"出片接口需要有效凭据：…"}

# Key 错
{"code":"modality.key.invalid","params":{},"message":"API key 无效、已停用、已过期或已超额"}

# 写了官方模型名
{"code":"modality.key.model_not_allowed","params":{"model":"MiniMax-H3","allow":"minimax-h3-*,doubao-seedance-*"},"message":"该 API key 不允许使用模型 MiniMax-H3（白名单：minimax-h3-*,doubao-seedance-*）"}

# 少 model
{"code":"request.missing_field","params":{"field":"model"},"message":"Failed to deserialize the JSON body into the target type: missing field `model` at line 1 column 38"}

# prompt 空且 content[] 也空（content: [] 等于没给）
{"code":"modality.content.prompt_empty","params":{},"message":"prompt 为空且没有 content[] —— 用 prompt 给文本，或走 ark 风格的 content[]（文本放在 text 项里）。空提示词只会生成噪声"}

# 图两种写法混用
{"code":"modality.content.mixed_forms","params":{},"message":"content[] 里已经有图片，同时又给了 first_frame_image 这类扁平字段 —— 只用一种写法（挑一个会让另一半静默失效）"}

# 档位不在枚举里
{"code":"modality.resolution.unknown","params":{"raw":"999p","available":"480p, 768p, 768p_native, 1080p, 2k","suggestion":"768p"},"message":"未知出片档 resolution=999p。可用：480p, 768p, 768p_native, 1080p, 2k（建议 768p；如需 999p 请等上游开闸后重试）"}

# 画幅协议外
{"code":"modality.video.param_invalid","params":{"model":"minimax-h3-hyper"},"message":"未知画幅 ratio=2:1。可用：16:9, 21:9, 4:3, 1:1, 3:4, 9:16（adaptive 按 16:9 处理）"}

{"code":"modality.video.param_invalid","params":{"model":"minimax-h3-hyper"},"message":"最多 3 个 LoRA（收到 4 个）"}
{"code":"modality.video.param_invalid","params":{"model":"minimax-h3-hyper"},"message":"loras 只接受 `id`（节点已安装的风格）；任意 URL/路径一律拒绝"}
{"code":"modality.video.param_invalid","params":{"model":"minimax-h3-hyper"},"message":"style_sumi_ink: scale=3 越界（0.0–2）"}
{"code":"modality.video.param_invalid","params":{"model":"minimax-h3-hyper"},"message":"content[0] 的 role=reference_video 不认。可用：first_frame, last_frame, reference_image"}
{"code":"modality.duration.out_of_range","params":{"model":"minimax-h3-hyper","lo":4.0,"hi":15.0,"secs":16.0},"message":"minimax-h3-hyper 的成片时长必须在 4–15 秒之间，收到 16"}

{"code":"modality.field.unimplemented",
 "params":{"fields":"`gen`（`steps` / `video_shift` / `audio_shift` / `sigma_grid` / `lora_schedule` / `f32_compute`）：这些是**节点侧调参**，对外通道不转发 —— 收下只会让它静默不生效。画质档位请用 `resolution` + `loras`；确有需要请找我们开专用通道"},
 "message":"请求里有官方支持、但本平台不实现的字段，所以不能收下当没看见：\n  - `gen`（…）：…\n（这些字段原先会被静默丢弃 —— 你那边看到 200、结果却不对。删掉它们重投即可。）"}

10.3 三个容易误判的细节

• 白名单先判：写官方模型名 MiniMax-H3 会先撞白名单（403），不会走到「400 并列出本机名字」。
• 档位／时长越界是建单同步 400，不会「200 之后 failed」——拿不到 job id，所以重试逻辑别写成「建单成功后轮询到 failed」。
• 404 有两种原因，刻意不区分：① id 写错；② 作业在途时赶上我们升级重启（在途作业表在内存里，重启即丢）。 后者不计费、不吃配额，重新提交即可。拿不准就把 id 给我们查。

10.4 建单 200 → 数秒 failed（B 类）：剩下这两族

2026-11-03 起，网关在排队之前先跑一遍 provider 的参数解析（content[] 形状 → 提示词/帧数 → 档位 → 画幅 → 画风）。 所以参数层面的错误全都提前成同步 400 了。仍然会走到「200 → failed」的，是必须拿到素材才能判的那两族：

10.5 gen 与「官方有、我们不做」的字段

这条值得单独说，因为它从「静默忽略」改成了「当场 400」，而且理由与客户直接相关：

其余完全没声明的键（客户自带的元数据）仍按「不报错也不生效」处理 —— 这一类我们不做判断。

10.6 402：代理商余额预检（本页新增）

HTTP/1.1 402 Payment Required
{"code":"agency.precheck.payment_required",
 "params":{"reason":"代理商 <你的代理商> 余额 … CP，未结欠账 … CP，结清后不足以出一片（下限约 200 CP），请上级充值"},
 "message":"…（与 reason 同文）"}

它发生在参数校验之前（实测：同一把 Key 下 resolution:"999p" 得到的是 402 而不是 400； 而 content[] 与扁平字段混用这种基础形状校验仍会先报 400）。所以排障顺序是： 先看余额/欠账，再看参数。

• 处置：联系上级充值 / 结清欠账；或改用平台预付费配额（quota > 0 的 Key）。
• 不要重试 —— 重试不会改变余额。

10.7 code 的命名族（按前缀分支，不要逐个硬编码）

code 是稳定的，message 会改 —— 按前缀族写，我们加新码时你的逻辑不会漏。

10.8 重试原则

别拿高频重试当兜底 —— 它会把队列顶长，让包括你在内的所有单都更慢。

11配额与计费

11.1 配额：每把 Key 200 次（按终态计）

• 在途不计数 ⇒ 并发提交会短暂超发：在途的不占额度，等它们各自进终态才一起记上。需要硬性瞬时限流请告诉我们（当前实现做不到）。
• 既然失败不吃次数，别拿配额当防护网去挡垃圾请求 —— 挡不住，那是限流该干的事。
• 配额用尽后，调用返回 401 API key 无效、已停用、已过期或已超额。
• quota: 0 在 verify 里的含义是不限次、按量后付（走代理商钱包），不是「不能用」。

11.2 计费：两个最容易踩的点

落在 bound_account_id 那个账户上，只对真正出片的作业计费。费率按秒、逐通道逐档不同，以费率卡为准。

本文件 2026-09-24 版在这里写过一个「4 秒 / 480p = 2 CP（≈¥0.02）」的示例，那是错的（差了 100 倍）。 2026-10-10 已按费率卡更正为上式，并把「480p 落 768p 档」写明。

verify 的 consumed 可以看大概进度：它最终一致（同步有延迟），别拿它当精确对账依据。 要精确用量请找我们对账。

12与官方 MiniMax H3 API 对照

我们的两条 minimax-h3-* 通道逐字段对齐官方《创建视频生成任务》/《查询任务》， 但有四处刻意不同（下面每处都写了为什么）。照着官方样例代码改，通常只改 model 名与 base_url 就能跑。

官方参考： MiniMax 开放平台 · 视频生成 · 火山方舟 · 视频生成（seedance 那条通道的上游）。

12.1 官方口径速查（摘自官方《MiniMax H3 模型使用手册》）

12.2 逐字段对照（请求体 / 查询体 / 错误体）

12.3 把官方样例迁过来的三步

1. base_url → https://api.123all.cn；Authorization 用发给你的 sk-omni-…。
2. model → minimax-h3-hyper（快）或 minimax-h3-vdn（画质/参考素材）。
3. 删掉 callback_url / aigc_watermark / extra，把「等回调」改成「轮询 GET /v1/videos/{id}」。

12.4 我们刻意与官方不同的四处（以及为什么）

13代码示例

13.1 Python（requests，可直接跑）

import time, requests

BASE = "https://api.123all.cn"
KEY  = "sk-omni-xxxxxxxx"          # 换成你的 Key
H    = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
TERMINAL = {"completed", "failed", "cancelled", "qc_failed"}   # qc_failed 也是终态

# ① 提交
r = requests.post(f"{BASE}/v1/videos", headers=H, timeout=60, json={
    "model": "minimax-h3-hyper",
    "prompt": "一只橘猫在阳光下的花园里奔跑，电影感，浅景深",
    "duration": 4,
    "resolution": "480p",
    "ratio": "16:9",                       # 竖屏写 "9:16"；尺寸见 §3.3
    # "loras": [{"id": "style_sumi_ink", "scale": 0.9}],
})
if r.status_code == 402:                    # 代理商余额预检（§10.6）
    raise SystemExit(f"余额不足：{r.text}")
r.raise_for_status()
job = r.json()["id"]
print("job:", job)

# ② 轮询
deadline = time.time() + 420                # ≥6 分钟，别按 60 秒
while True:
    body = requests.get(f"{BASE}/v1/videos/{job}", headers=H, timeout=30).json()
    st = body["status"]
    print("status:", st, round(time.time() - (deadline - 420)), "s")
    if st in TERMINAL:
        break
    if time.time() > deadline:
        raise SystemExit(f"客户端超时（作业可能仍在跑）：{job}")
    time.sleep(6)

if st == "failed":
    raise SystemExit(f"作业失败：{body.get('error')}")
if st == "qc_failed":
    raise SystemExit(f"未过出库质检（不计费）：{body.get('qc')}")

# ③ 取片：用 /content，requests 自动跟随 307
with requests.get(f"{BASE}/v1/videos/{job}/content", headers=H,
                  timeout=300, stream=True) as resp:
    resp.raise_for_status()
    ctype = resp.headers.get("Content-Type", "")
    if not ctype.startswith("video/"):       # 防「2xx 但回的是错误页/JSON」
        raise SystemExit(f"取片失败：Content-Type={ctype!r}，body 头={resp.text[:200]!r}")
    with open("out.mp4", "wb") as f:
        for chunk in resp.iter_content(65536):
            f.write(chunk)
print("saved out.mp4")

13.2 Node 18+（内置 fetch）

const BASE = "https://api.123all.cn";
const KEY  = process.env.OMNI_KEY;            // 别把 Key 写进源码
const H    = { "Authorization": `Bearer ${KEY}`, "Content-Type": "application/json" };
const TERMINAL = new Set(["completed", "failed", "cancelled", "qc_failed"]);

const created = await fetch(`${BASE}/v1/videos`, {
  method: "POST", headers: H,
  body: JSON.stringify({
    model: "minimax-h3-vdn",
    prompt: "夜市摊位，暖色灯光，镜头缓慢横移",
    duration: 4, resolution: "480p", ratio: "9:16",
  }),
});
if (!created.ok) throw new Error(`建单 ${created.status}: ${await created.text()}`);
const { id } = await created.json();

let job;
const t0 = Date.now();
while (true) {
  job = await (await fetch(`${BASE}/v1/videos/${id}`, { headers: H })).json();
  if (TERMINAL.has(job.status)) break;
  if (Date.now() - t0 > 6 * 60 * 1000) throw new Error(`超时，作业 ${id} 可能仍在跑`);
  await new Promise(r => setTimeout(r, 6000));
}
if (job.status !== "completed") throw new Error(`终态 ${job.status}: ${job.error ?? JSON.stringify(job.qc)}`);

const res = await fetch(`${BASE}/v1/videos/${id}/content`, { headers: H });  // 自动跟随 307
if (!res.ok) throw new Error(`取片 ${res.status}: ${await res.text()}`);
if (!res.headers.get("content-type")?.startsWith("video/")) throw new Error("回的不是视频");
const buf = Buffer.from(await res.arrayBuffer());
await require("node:fs/promises").writeFile("out.mp4", buf);
console.log("saved out.mp4", buf.length, "bytes");

13.3 客户端要自己限并发

• 普通 t2va 之类：2–3 个在途；ref2va（参考素材）：1 个在途。
• 轮询 5–10 秒一次，进终态立刻停。
• 队列是共享且串行的：并发不会更快，只会把队列排长、把每一单都拖慢（§3.4）。

14上线检查清单

• Key 只放在服务端环境变量里；前端/仓库/日志里没有明文（verify 只看 active 与 scopes）
• 轮询终止条件包含 4 个终态，特别是 qc_failed
• HTTP 超时 ≥6 分钟；轮询间隔 5–10 秒；超时后先按 id 查状态再决定是否重投
• 取片用 /content + 跟随重定向；写盘前核 状态码 与 Content-Type；curl 带 -f
• 错误分支按 code 前缀写；400/402/403/404/422 不重试，502/504 退避重试
• 素材优先公网 URL；doubao-seedance-* 上绝不用内联 base64 传大于几十 KB 的图
• 参考类作业同时只留 1 个在途；与普通作业交替提交会变慢，已排进超时预算
• 成片落自己存储（/content 或当天转存）；没有把 url / /v1/artifacts/… 存进数据库当长期地址
• 画风只用 GET /v1/loras 里的 id；叠加 2–3 件时 scale 取 0.6–0.8
• 合规：成片若要对客发布，记得自行叠加「AI 生成」标识（我们不加 aigc_watermark）

15常见问题

Q：响应里 url 是 volces.com 的链接，能直接用吗？

能。那是带签名的临时链接，实测 200 / video/mp4，约 24 小时后失效。 图省事可以用，但请当天转存。稳妥做法是一律用 /content。

Q：url 是 /v1/videos/… 这种半截路径？

那是另一种形态（minimax-h3-* 给这种），需要带鉴权头请求。同样建议直接用 /content。

Q：我下到的 out.mp4 打开是 JSON，内容是 {"code":"modality.key.denied",…}？

那不是片子，是你把 HTTP 错误体整段写进了文件。取片端点带鉴权，凭据缺失/为空时回 401 + JSON； 而 curl -o（不加 -f）会把任何 4xx/5xx 的响应体原样写进文件并返回 0。 修复两条：① 取片加 -f（出错时 curl 退 22 且不落盘）；② 客户端写盘前核状态码 + Content-Type。 最常见的触发是 $KEY 没设置（header 退化成 Bearer ）。

Q：我选了竖屏（ratio:"9:16"），出来的真是竖的吗？多大？

是，ratio 换的是画布本身。逐档尺寸见 §3.3（承诺值）。2026-11-05 实测：vdn+480p+9:16 交付 480×864。 三点：① 不接受的画幅现在建单就 400；② adaptive 按 16:9 处理；③ 图生视频时官方会忽略 ratio，我们不忽略。

Q：status 一直是 queued 很久？

排队。生成资源是共享的，高峰期排队可能比出片本身更久。轮询间隔 5–10 秒即可。

Q：status 变 failed 了，但建单时是 200？

这仍然可能发生（§10.4）：素材解析失败、或在节点上才能判的模态组合。 请看 error 字段，它是原因原文；改完重新提交即可。失败不计费、也不占配额 —— 但仍建议先小样试参数：省的是你能拿到的片子，不是次数。

Q：为什么我的建单回了 402？

代理商余额/欠账预检没过（§10.6）。verify 仍是 active:true 不代表能出片 —— 请上级充值或结清欠账。不要重试。

Q：duration: 4，为什么成片是 5.17 秒？

合法帧数下限是 124 帧（24 fps ⇒ 5.17 s）。4 秒 = 96 帧低于下限，服务端抬到 124 帧。 响应里的 duration_secs 仍回 4.0。要精确控时长用 num_frames: 124（§4.5）。

Q：同一个 prompt 每次出的片不一样？

分情况：minimax-h3-* 不传 seed 时用固定默认种子，所以同一 prompt 反复提交会得到同一条片 （看起来像缓存，其实是确定性生成）。要每次不同请传变化的 seed；要复现就把当时的 seed 记下来。 但「像素级完全一致」不保证：同一 model 背后可能有多台服务器接单，画面内容一致、像素级约 1% 差异。 doubao-seedance-* 的 seed 同样支持，不传由上游决定。

Q：能不能并发提很多作业？

可以，但不建议敞开提：出片资源共享且串行，并发收益不在「更快」，而在「把队列排长」。 而且配额只在交付时计，在途不占额度 ⇒ 并发会短暂超发配额。 建议客户端限并发（普通 2–3、参考素材 1），轮询 5–10 秒。

Q：轮询着突然 404，可我确信刚提交过？

两种可能，我们刻意不区分：id 写错，或者这个作业在途时赶上了我们的升级重启（在途作业表在内存里，重启即丢）。 后者不计费、不吃配额，重投即可。2026-10-13 有一条就是这样丢的：服务端 23:02:07 重启，客户 23:02:08 拿到 502、23:02:14 拿到 404 —— 遇 502 立刻重试前，先等十几秒。

Q：api.123all.cn 和 gateway.123all.cn 有什么区别？

没有区别。 两个域名提供逐字相同的接口与数据：视频、素材、成果物、Key 自检四条路径都在。用哪个都一样。 （旧品牌 qiliqiji.com 在过渡期同样可用，路径与请求体不变。）

Q：素材库传上去的图/视频能复用多少次？限量吗？

不限次。素材是一份字节加一条登记，作业只是引用它。删掉素材之后：已引用它的作业不受影响（片子已经出了）， 但新的作业再用那个 asset:// 会 404。

Q：参考视频/音频到底哪些模型收？

三条通道都收三类参考模态（逐条对照见 §4.4）。两条 minimax-h3-* 都收首帧/尾帧/首尾帧； vdn 上参考素材走 ref2va。唯一不收的是「纯音频」：音频是陪衬（决定音色/语速），主体必须有一张图或一段视频。

Q：我想让片子带某种画风，要怎么写提示词？

不用写提示词 —— 建单时给 loras（最多 3 件），画风由 id 决定， 绑定它的触发词服务端会自动加到 prompt 前面。45 种 id 见 附录 A，用法见 §6。

Q：asset:// 怎么用？

先 POST /v1/assets 传一次（§5.5），拿到 asset://asset-omni-…，之后每个作业的三类素材字段里都能写它。 只用一次的大素材不必走素材库 —— 直接给公网 URL 更快。

Q：Key 泄了怎么办？

立刻联系我们停用并补发。active 会立刻变 false。

Q：从国内访问偶尔打不开？

这是接入侧按 IP/域名的登记状态问题（备案是按「域名 × 接入商」登记的，换接入商后要在新接入商做接入备案）， 不是服务端故障。判断方法：我们这边与境外访问都正常，只有境内部分出口失败。遇到请把你的出口 IP 与时间发给我们。

A附录 A · 画风（loras）清单

id 就是 loras[].id。「推荐强度」是不传 scale 时的默认值，范围 0.0–2.0。 触发词由服务端自动前置，请求里不用写；这一列列出来只为让你知道画风是从哪来的。 数据来自 GET /v1/loras 的实时响应 2026-11-05 · 45 条。

B附录 B · 实测档案

本页所有「实测」条目都能查到原始记录。日期、条件、判据都写在每一段里 —— 没有写条件数字请不要拿来当容量规划。

B.1 三条成片（2026-11-05 14:47–14:52 +08:00）

三单同一秒提交、同一条通道池排队。第 3 单明显更久，主要来自排队与画风资源准备 —— 这正是「并发不加速」的现场证据，不代表带画风的单发耗时（2026-10-31 单发实测约 80 秒）。

B.2 错误面（2026-11-05 14:40–14:52 逐条投出）

完整清单见 §10.1（20 条，另有 4 条画风/空文本类记在 B.4）。采集方式：同一入口、同一公网域名、逐条独立请求，记录状态码 / code / 耗时 / 原文。 建单即拒的那些没有产生 job id，也没有计费；两条「200 → failed」的作业同样不交付、不计费。

B.3 历史实测（引用，未重跑）

2026-09-24 那组数字别与 10-22 的混用：服务端之后更新过快的一版，排队与出片都更快了。

B.4 怎么复现（判据都在命令里）

# 0) 自检
curl -s "$BASE/api/v1/reseller/tokens/verify?key=$KEY"

# 1) 提交 → 2) 轮询到终态（脚本见 §1 / §13）
#    判据：GET 的 status ∈ {completed, failed, qc_failed, cancelled}

# 3) 取片并**核内容**
curl -fL -o out.mp4 "$BASE/v1/videos/$JOB/content" -H "Authorization: Bearer $KEY"
ffprobe -v error -show_entries stream=width,height,nb_frames,r_frame_rate:format=duration -of json out.mp4

# 4) 参数面（应全部同步 400，且拿不到 job id）
for body in \
  '{"model":"minimax-h3-hyper","prompt":"x","resolution":"999p"}' \
  '{"model":"minimax-h3-hyper","prompt":"x","ratio":"2:1"}' \
  '{"model":"minimax-h3-hyper","prompt":"x","loras":[{"id":"style_sumi_ink"}],"style":"style_sumi_ink"}' \
  ; do
  curl -s -o /dev/null -w '%{http_code} ' -X POST "$BASE/v1/videos" \
    -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d "$body"
done; echo

最后一条（style 与 loras 同时给）2026-11-05 实测返回 200 —— 我们尚未把它列进 A 类。 那条作业跑了 372.3 秒，最后 qc_failed（edge_luma_ratio=0.011 < 0.4，片头未收敛）。 结论不变：只给一种；两个一起给不会报错，但组合语义没有背书。

同批还实测到：loras 里写不存在的 id ⇒ 建单 200、6.2 秒后 failed （LORA_UNKNOWN，消息里列出本节点已安装的全部画风）；只给一个空 text、无 prompt ⇒ 建单 200、6.6 秒后 failed（「没有文本提示词…」）。

B.5 本页对 md（2026-11-03 版）的五处勘误

另：GET /v1/videos?limit=（列出自己的作业）实测可用，本文首次登记（§8.5）。 其余条目与 2026-11-03 版一致，未改动；尺寸表、档位表、官方口径对照逐条复核过。