TUTUJING APITUTUJING API
开发者接口

视频 API 设置

一套 OpenAI 兼容的视频接口,接入 H3、Wan 3.0、Seedance 和 Grok。本文只讲接口本身:怎么连、怎么垫图、每个模型支持哪些画幅和分辨率,方便你把模型接进自己的画布、工作流或后端服务。

本页面仅用于 TUTUJING API 的合法授权调用、内部管理和私有化部署。请妥善保护账号、密钥和请求数据。

一、接入准备

所有视频模型共用同一组地址。视频任务是异步的:先提交拿到任务 ID,再轮询状态,完成后再下载成片。聊天类接口是同步返回,视频接口不是。

项目填写内容
Base URLhttps://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 全小写带短横线。改写后缀、大小写或空格都会被判成未知模型。

二、三步调用流程

1

提交任务

文生视频最少只要 model + prompt。下面这条是 H3 Video 的 768P、5 秒、16:9:

curl · 提交
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:

JSON · 提交响应
{
  "id": "task_2rKKh2zymBZjxvad1QfMsEk33rduoNUF",
  "object": "video",
  "model": "H3 Video",
  "status": "queued",
  "progress": 0,
  "created_at": 1792774242
}
2

轮询状态

建议 5–10 秒查一次。视频一般 1–10 分钟出片,H3 长时长、Wan 3.0 高分辨率会更久。

curl · 查询
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 是原因展示原因,允许用户改参数重试;失败不扣费
3

下载成片

curl · 下载(-L 跟随重定向)
curl -L https://api.tutujing.com/v1/videos/task_2rKKh2zymBZjxvad1QfMsEk33rduoNUF/content \
  -H "Authorization: Bearer sk-你的令牌" \
  -o result.mp4
H3 系列不要指望查询结果里直接给直链

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 Video480P / 720P / 768P(默认)/ 960P / 1080Padaptive、21:9、16:9、4:3、1:1、3:4、9:16;720P 仅 16:9 / 9:16
H3 Frames同上同上
wan30-720p720P16:9、9:16、1:1、4:3、3:4、21:9
seedance-2.0-mini720P16:9、9:16
grok-imagine-video-1.5-preview480p / 720p16:9、9:16、1:1(以接口返回的画幅枚举为准)

H3 Video:多参垫图主力

适合「人物一致性 + 场景参考 + 动作参考」的组合创作。参考图、参考视频、参考音频要放进 metadata.content 数组里,并给每项标明角色;ratio 写在 metadata.ratio。

curl · H3 Video 多参垫图
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 不接受 input_reference / first_frame

它在接口层校验「H3 Video images must use reference_image」:所有图片必须是 reference_image 角色。要首尾帧请换 H3 Frames,两个模型不能混用同一种图片字段。

H3 Frames:首帧 / 尾帧

用首帧锁开场、尾帧锁收尾,中间动作交给提示词。给 1 张就是单首帧,给 2 张就是首尾帧,顺序固定「先首帧、后尾帧」。

curl · H3 Frames 首尾帧
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 · wan30 图生视频
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:91280x720默认横屏
9:16720x1280竖屏
1:1960x960方形
4:31112x834标准横屏
3:4834x1112标准竖屏
21:91680x720宽银幕

多图、参考视频、参考音频按上游 OpenAI 视频 JSON 透传,具体字段名以上游实测为准;建议先用首帧 input_reference 跑通再补参考素材。

seedance-2.0-mini:轻量、按次计费

适合批量试镜、快速出草稿。基础参数与 Wan 一致(seconds 用字符串、size 用预设值),按次计费,出片时长不影响价格。

curl · seedance 文生视频
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 · Grok 单图垫图
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 · Grok 多图参考
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"]
  }'
Grok 不支持首尾帧,也不接受视频/音频参考

需要首帧锁开场、尾帧锁收尾请换 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
素材必须是公网可访问的 HTTPS 地址

本接口不会替你托管图片。本机图片请先传到对象存储 / 图床 / 自己的 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 KeyAuthorizationBearer sk-...
模型modelH3 Video / H3 Frames / wan30-720p / seedance-2.0-mini / grok-imagine-video-1.5-preview
画面比例H3:metadata.ratio
Wan、Grok:aspect_ratio
16:9、9:16、1:1、4:3、3:4、21:9(H3 另有 adaptive)。H3 不读顶层 aspect_ratio,写错位置会退回默认画幅。
分辨率resolutionH3:480P/720P/768P/960P/1080P;Wan / Seedance:720p;Grok:480p / 720p
时长secondsH3 传数字;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):

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 去重。

六、常见错误与排查

状态码返回文案(节选)原因与处理
401Invalid token令牌缺失、写错或被禁用;确认 Bearer sk- 前缀完整。
503分组 X 下模型 Y 无可用渠道令牌分组与模型不匹配,按「接入准备」的分组表重建令牌。
400MiniMax-H3 resolution must be one of 480P, 720P, 768P, 960P, 1080P分辨率值不在枚举内,H3 用大写 P。
400MiniMax-H3 duration must be an integer between 4 and 30 seconds时长必须是整数秒;H3 Frames 上限 15 秒。
400H3 Frames requires at least one first_frame or last_frame image and cannot use reference media首尾帧模型没给帧图,或混了参考视频/音频。
400H3 Video images must use reference_image给 H3 Video 传了首尾帧字段,改用 metadata.content + reference_image。
400MiniMax-H3 ratio must be one of adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16比例写错位置或用了不支持的值;H3 的 ratio 放在 metadata 里。
400MiniMax-H3 720P only supports ratio 16:9 or 9:16720P 只支持横竖屏,其他画幅请换 768P 或更高。
400seconds must be between 1 and 3600秒数为 0、负数或非数字。
400json: cannot unmarshal number into Go struct field .Alias.seconds of type stringWan / Seedance 的 seconds 要传字符串。
400服务繁忙,请稍后重试通常是 size 给了上游不认的尺寸;改用 aspect_ratio + resolution。
503服务繁忙,请稍后重试上游该模型暂无可用渠道(新开通模型常见)。不创建任务、不扣费;稍后重试,持续出现请附 request id 联系客服。
200 后 failedvideo_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 秒同价
先把最小请求跑通再上量

建议先用 480P / 768P、4–5 秒做连通性验证,确认模型名、分组、比例、垫图字段都对,再接进批量队列。这样单次试错成本最低。