视频 API 设置
一套 OpenAI 兼容的视频接口,接入 H3、Wan 3.0、Seedance 和 Grok。本文只讲接口本身:怎么连、怎么垫图、每个模型支持哪些画幅和分辨率,方便你把模型接进自己的画布、工作流或后端服务。
一、接入准备
所有视频模型共用同一组地址。视频任务是异步的:先提交拿到任务 ID,再轮询状态,完成后再下载成片。聊天类接口是同步返回,视频接口不是。
| 项目 | 填写内容 |
|---|---|
| Base URL | https://api.tutujing.com(客户端若自动拼接 /v1/videos,填到域名即可) |
| 提交任务 | POST /v1/videos,JSON(参考图也可以用 multipart/form-data 上传) |
| 查询任务 | GET /v1/videos/{task_id} |
| 下载成片 | GET /v1/videos/{task_id}/content,返回 302 跳到 CDN,客户端需允许跟随重定向 |
| 鉴权 | 请求头 Authorization: Bearer sk-你的令牌 |
| 内容类型 | Content-Type: application/json;上传本地首帧时用 multipart/form-data |
令牌分组决定你能调用哪些视频模型
视频模型按分组开放。令牌建错分组时接口会直接返回 503 model_not_found,报错里会写明「分组 X 下模型 Y 无可用渠道」。先在控制台确认令牌分组,再取密钥。
| 令牌分组 | 可用视频模型 |
|---|---|
| H3 视频生成 | H3 Video(文生 / 多参垫图)、H3 Frames(首尾帧) |
| 视频A组 | wan30-720p、seedance-2.0-mini、grok-imagine-video-1.5-preview |
| Seedance 分组 | seedance-2.0-mini |
H3 Video 中间是空格、大小写固定;wan30-720p 全小写带短横线。改写后缀、大小写或空格都会被判成未知模型。
二、三步调用流程
提交任务
文生视频最少只要 model + prompt。下面这条是 H3 Video 的 768P、5 秒、16:9:
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "H3 Video",
"prompt": "雨夜的便利店门口,穿黄色雨衣的女孩收伞走进画面,镜头缓慢前推",
"seconds": 5,
"resolution": "768P",
"metadata": { "ratio": "16:9" }
}'提交成功返回任务对象,记下 id:
{
"id": "task_2rKKh2zymBZjxvad1QfMsEk33rduoNUF",
"object": "video",
"model": "H3 Video",
"status": "queued",
"progress": 0,
"created_at": 1792774242
}轮询状态
建议 5–10 秒查一次。视频一般 1–10 分钟出片,H3 长时长、Wan 3.0 高分辨率会更久。
curl https://api.tutujing.com/v1/videos/task_2rKKh2zymBZjxvad1QfMsEk33rduoNUF \ -H "Authorization: Bearer sk-你的令牌"
| status | 含义 | 客户端处理 |
|---|---|---|
queued | 已排队,等待上游开工 | 继续轮询 |
in_progress | 生成中,progress 0–100 | 继续轮询 |
completed | 已完成,可下载 | 进入第 3 步下载并落盘 |
failed | 失败,error.message 是原因 | 展示原因,允许用户改参数重试;失败不扣费 |
下载成片
curl -L https://api.tutujing.com/v1/videos/task_2rKKh2zymBZjxvad1QfMsEk33rduoNUF/content \ -H "Authorization: Bearer sk-你的令牌" \ -o result.mp4
H3 Video / H3 Frames 完成后,查询响应只有状态字段,成片必须走 /content 下载。Wan 3.0 和 Seedance 走中转时查询响应可能同时带 url,但统一用 /content 最稳,也便于你把文件存到自己的存储。
三、模型能力总表
目前对外开放五个视频模型。第一张表决定你能怎么喂素材、能生成多长;第二张表决定输出画幅和清晰度。分辨率、时长、画幅都是接口侧会校验的硬限制,超出直接返回 400,不会生成任务也不会扣费。
| 模型 | 输入模式 | 参考素材上限 | 时长 |
|---|---|---|---|
H3 Video |
文生视频 多参垫图 |
9 张参考图 + 1 段参考视频(≤15 秒)+ 3 段参考音频 | 4–30 秒整数;960P/1080P ≤15 秒;768P + 21:9 ≤20 秒 |
H3 Frames |
首尾帧 | 1 张首帧 + 1 张尾帧;不能混参考视频、参考音频 | 4–15 秒整数 |
wan30-720p |
文生视频 图生视频(首帧) 参考图 / 音视频 |
最多 10 张参考图 + 5 段参考音频 + 5 段参考视频(不建议,速度慢) | 1–30 秒 |
seedance-2.0-mini |
文生视频 图生视频(首帧) |
首帧 1 张;多图与参考音视频以上游能力为准 | 建议 5 / 10 秒 |
grok-imagine-video-1.5-preview |
文生视频 参考图垫图 |
多张参考图;不接受参考视频、参考音频。参考图只作外观/画风参考,不是首尾帧 | 单图 6 / 10 / 15 秒;多图 6 / 10 秒 |
| 模型 | 分辨率 | 画幅 |
|---|---|---|
H3 Video | 480P / 720P / 768P(默认)/ 960P / 1080P | adaptive、21:9、16:9、4:3、1:1、3:4、9:16;720P 仅 16:9 / 9:16 |
H3 Frames | 同上 | 同上 |
wan30-720p | 720P | 16:9、9:16、1:1、4:3、3:4、21:9 |
seedance-2.0-mini | 720P | 16:9、9:16 |
grok-imagine-video-1.5-preview | 480p / 720p | 16:9、9:16、1:1(以接口返回的画幅枚举为准) |
H3 Video:多参垫图主力
适合「人物一致性 + 场景参考 + 动作参考」的组合创作。参考图、参考视频、参考音频要放进 metadata.content 数组里,并给每项标明角色;ratio 写在 metadata.ratio。
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "H3 Video",
"prompt": "@图片1 的女孩走进 @图片2 的咖啡馆,镜头跟着她缓慢前推,@音频1 作为环境声",
"seconds": 5,
"resolution": "768P",
"metadata": {
"ratio": "16:9",
"content": [
{ "type": "image_url", "role": "reference_image", "image_url": { "url": "https://cdn.example.com/girl.png" } },
{ "type": "image_url", "role": "reference_image", "image_url": { "url": "https://cdn.example.com/cafe.png" } },
{ "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://cdn.example.com/room.mp3" } }
]
}
}'它在接口层校验「H3 Video images must use reference_image」:所有图片必须是 reference_image 角色。要首尾帧请换 H3 Frames,两个模型不能混用同一种图片字段。
H3 Frames:首帧 / 尾帧
用首帧锁开场、尾帧锁收尾,中间动作交给提示词。给 1 张就是单首帧,给 2 张就是首尾帧,顺序固定「先首帧、后尾帧」。
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "H3 Frames",
"prompt": "一个连续镜头:从开场画面缓慢推近,人物转头看向窗外,最后停在收尾画面",
"seconds": 8,
"resolution": "768P",
"metadata": { "ratio": "16:9" },
"images": [
"https://cdn.example.com/first.png",
"https://cdn.example.com/last.png"
]
}'首帧也可以直接用 input_reference(URL),或 multipart/form-data 上传本地图片(字段名 input_reference,单文件 ≤20 MB,是否被上游接受以实测为准)。
wan30-720p:Wan 3.0 720P,按秒计费
画幅用 aspect_ratio 指定,分辨率固定 720p;seconds 必须是字符串。首帧图用 input_reference。
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "wan30-720p",
"prompt": "画面中的红球缓慢向前滚动,固定机位,浅灰地面,光线均匀",
"seconds": "5",
"aspect_ratio": "1:1",
"resolution": "720p",
"input_reference": "https://cdn.example.com/ball.png"
}'1)seconds 写成数字会被上游拒绝,必须写字符串 "5"。
2)自定义 size 只认少数预设(如 1680x720),随便写 720x720 这类尺寸会报「服务繁忙,请稍后重试」。优先用 aspect_ratio + resolution: "720p"。
已验证的画幅与输出尺寸(720P):
| aspect_ratio | 输出尺寸 | 说明 |
|---|---|---|
16:9 | 1280x720 | 默认横屏 |
9:16 | 720x1280 | 竖屏 |
1:1 | 960x960 | 方形 |
4:3 | 1112x834 | 标准横屏 |
3:4 | 834x1112 | 标准竖屏 |
21:9 | 1680x720 | 宽银幕 |
多图、参考视频、参考音频按上游 OpenAI 视频 JSON 透传,具体字段名以上游实测为准;建议先用首帧 input_reference 跑通再补参考素材。
seedance-2.0-mini:轻量、按次计费
适合批量试镜、快速出草稿。基础参数与 Wan 一致(seconds 用字符串、size 用预设值),按次计费,出片时长不影响价格。
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-mini",
"prompt": "清晨的港口,薄雾里一艘小船缓缓驶出,镜头横移跟随",
"seconds": "5",
"size": "720x1280"
}'上游返回 video_generation_failed:视频生成未成功,可能是系统临时波动 时属于可重试错误,建议客户端自动重试 1–2 次并记录 request id;这类失败不扣费,不要在 UI 上直接判定「模型不可用」。
grok-imagine-video-1.5-preview:Grok 视频,按次计费
参考图是「垫图」语义,不是首尾帧:第一张放 image_url,其余追加到 reference_image_urls。单图可 6 / 10 / 15 秒,多图只能 6 / 10 秒;分辨率 480p / 720p;画幅用 aspect_ratio。按次计费,6 秒和 15 秒同价。
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5-preview",
"prompt": "女孩在雨夜的霓虹街头回头,镜头缓慢环绕,电影质感",
"seconds": 6,
"aspect_ratio": "16:9",
"resolution": "720p",
"image_url": "https://cdn.example.com/girl.png"
}'多图参考时,其余图片放进 reference_image_urls,时长只能取 6 或 10 秒:
curl -X POST https://api.tutujing.com/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5-preview",
"prompt": "@图片1 的女孩走进 @图片2 的咖啡馆,镜头跟随推进",
"seconds": 10,
"aspect_ratio": "9:16",
"resolution": "480p",
"image_url": "https://cdn.example.com/girl.png",
"reference_image_urls": ["https://cdn.example.com/cafe.png"]
}'需要首帧锁开场、尾帧锁收尾请换 H3 Frames;Grok 的参考图只影响人物外观和画风,不控制结尾画面。单帧、多帧的数量上限与画幅枚举会随上游版本变化,遇 400 请附 request id 反馈。
四、垫图与参考素材
「垫图」在本接口里分三种语义,先想清楚你要的是哪一种,再选字段:
| 传法 | 字段 | 语义 | 适用 |
|---|---|---|---|
| 首帧 / 尾帧 | input_reference、images[]、metadata.first_frame_image / last_frame_image | 作为视频的起始画面(可加结束画面),不参与「参考」编号 | H3 Frames、wan30-720p、seedance-2.0-mini |
| 多参考图 | metadata.content[],每项 role: "reference_image" | 只参考外观、场景、风格,不是首帧 | H3 Video |
| 垫图(Grok) | 首张 image_url,其余 reference_image_urls[] | 只参考人物外观与画风,不是首帧,也不控制结尾画面 | grok-imagine-video-1.5-preview |
| 动作 / 声音参考 | metadata.content[] 的 video_url / audio_url,角色 reference_video / reference_audio | 参考动作、镜头运动、音色与环境声 | H3 Video |
本接口不会替你托管图片。本机图片请先传到对象存储 / 图床 / 自己的 CDN,再把 URL 传给接口;内网地址、file://、blob: 都会被上游拒绝。H3 首帧支持 multipart 直传(≤20 MB),但多参考素材仍然只能给 URL。
参考图编号与提示词写法
参考素材按同类输入的顺序从 1 编号,在提示词里用 @图片1、@图片2、@音频1 指代,例如「@图片1 的女孩走进 @图片2 的咖啡馆」。提示词里没提到的参考素材仍会作为通用画面参考,但写明用途命中率更高。
H3 Frames 只能首尾帧,不能同时塞参考视频或音频;H3 Video 只能参考图/视频/音频,不能用首尾帧字段。混用会在提交阶段被 400 拦下,不会创建任务。
五、画布客户端设置清单
如果你在做画布、工作流或分镜类工具,把下面这张表照进设置面板就能跑通。字段差异集中在「比例」和「秒数类型」两处。
| 画布里的设置项 | 提交字段 | 取值与注意 |
|---|---|---|
| Base URL | — | https://api.tutujing.com |
| API Key | Authorization | Bearer sk-... |
| 模型 | model | H3 Video / H3 Frames / wan30-720p / seedance-2.0-mini / grok-imagine-video-1.5-preview |
| 画面比例 | H3:metadata.ratioWan、Grok: aspect_ratio | 16:9、9:16、1:1、4:3、3:4、21:9(H3 另有 adaptive)。H3 不读顶层 aspect_ratio,写错位置会退回默认画幅。 |
| 分辨率 | resolution | H3:480P/720P/768P/960P/1080P;Wan / Seedance:720p;Grok:480p / 720p |
| 时长 | seconds | H3 传数字;Wan / Seedance 传字符串;Grok 单图 6/10/15 秒、多图 6/10 秒 |
| 首帧 / 垫图 | input_reference、metadata.content[],或 Grok 的 image_url + reference_image_urls | 公网 HTTPS URL;H3 Video 必须用 reference_image;Grok 的参考图不是首帧 |
| 轮询 | GET /v1/videos/{id} | 5–10 秒一次,单任务最多等 20 分钟 |
| 下载 | GET /v1/videos/{id}/content | 跟随 302,把文件存到自己的目录 |
最小可用的前端实现(TypeScript):
const BASE = "https://api.tutujing.com";
const auth = { Authorization: `Bearer ${localStorage.getItem("apiKey")}` };
async function createVideo(body: Record<string, unknown>) {
const res = await fetch(`${BASE}/v1/videos`, {
method: "POST",
headers: { ...auth, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error?.message || "提交失败");
return data.id as string;
}
async function waitVideo(taskId: string, onProgress?: (s: string) => void) {
const deadline = Date.now() + 20 * 60 * 1000;
while (Date.now() < deadline) {
const res = await fetch(`${BASE}/v1/videos/${taskId}`, { headers: auth });
const task = await res.json();
onProgress?.(task.status);
if (task.status === "completed") return task;
if (task.status === "failed") throw new Error(task.error?.message || "生成失败");
await new Promise((r) => setTimeout(r, 7000));
}
throw new Error("等待超时,可稍后用任务 ID 继续查询");
}
async function downloadVideo(taskId: string) {
const res = await fetch(`${BASE}/v1/videos/${taskId}/content`, { headers: auth });
if (!res.ok) throw new Error("下载失败");
return res.blob();
}提交接口每调用一次就可能产生一个计费任务。网络抖断时用已拿到的任务 ID 继续查询,不要重新 POST;需要幂等的场景请自己在上层按业务 ID 去重。
六、常见错误与排查
| 状态码 | 返回文案(节选) | 原因与处理 |
|---|---|---|
| 401 | Invalid token | 令牌缺失、写错或被禁用;确认 Bearer sk- 前缀完整。 |
| 503 | 分组 X 下模型 Y 无可用渠道 | 令牌分组与模型不匹配,按「接入准备」的分组表重建令牌。 |
| 400 | MiniMax-H3 resolution must be one of 480P, 720P, 768P, 960P, 1080P | 分辨率值不在枚举内,H3 用大写 P。 |
| 400 | MiniMax-H3 duration must be an integer between 4 and 30 seconds | 时长必须是整数秒;H3 Frames 上限 15 秒。 |
| 400 | H3 Frames requires at least one first_frame or last_frame image and cannot use reference media | 首尾帧模型没给帧图,或混了参考视频/音频。 |
| 400 | H3 Video images must use reference_image | 给 H3 Video 传了首尾帧字段,改用 metadata.content + reference_image。 |
| 400 | MiniMax-H3 ratio must be one of adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | 比例写错位置或用了不支持的值;H3 的 ratio 放在 metadata 里。 |
| 400 | MiniMax-H3 720P only supports ratio 16:9 or 9:16 | 720P 只支持横竖屏,其他画幅请换 768P 或更高。 |
| 400 | seconds must be between 1 and 3600 | 秒数为 0、负数或非数字。 |
| 400 | json: cannot unmarshal number into Go struct field .Alias.seconds of type string | Wan / Seedance 的 seconds 要传字符串。 |
| 400 | 服务繁忙,请稍后重试 | 通常是 size 给了上游不认的尺寸;改用 aspect_ratio + resolution。 |
| 503 | 服务繁忙,请稍后重试 | 上游该模型暂无可用渠道(新开通模型常见)。不创建任务、不扣费;稍后重试,持续出现请附 request id 联系客服。 |
| 200 后 failed | video_generation_failed: 视频生成未成功 | 上游临时波动,重试即可;失败任务不扣费。 |
反馈问题时请附上返回里的 request id(形如 20261026013058227321886d5602172mFBfyTlD)和任务 ID,能直接定位到上游那一次调用。
七、计费与配额
| 模型 | 计费口径 | 参考单价(人民币,分组倍率 1) |
|---|---|---|
H3 Video | 按输出秒数 × 分辨率档 | 480P ¥0.03/秒 · 720P ¥0.05/秒 · 768P ¥0.08/秒 · 960P ¥0.24/秒 · 1080P ¥0.32/秒;768P 5 秒 = ¥0.40 |
H3 Frames | 按输出秒数 × 分辨率档 | 与 H3 Video 同价,不额外收首尾帧费用;480P 4 秒 = ¥0.12 |
wan30-720p | 按秒计费 | ¥0.42/秒;5 秒 = ¥2.10,10 秒 = ¥4.20 |
seedance-2.0-mini | 按次计费 | ¥2.80/次,与时长无关 |
grok-imagine-video-1.5-preview | 按次计费 | ¥2.00/次,6 / 10 / 15 秒同价 |
- 提交时按请求参数预扣,完成后按上游返回的真实秒数结算,多退少补。
- 生成失败不扣费(失败任务计费为 0),余额原路返还;内容被拒、主动取消同理。
- 表中单价按分组倍率 1 折算,实际单价、分组倍率和余额以模型广场和控制台为准。
建议先用 480P / 768P、4–5 秒做连通性验证,确认模型名、分组、比例、垫图字段都对,再接进批量队列。这样单次试错成本最低。
