视频生成 API
对接速查(主站 / 客户端用)
| 接口地址 | https://independent.172-247-37-6.sslip.io |
| 鉴权 | Authorization: Bearer sk-…(在网关「令牌」页创建) |
| 查模型 | GET /v1/models → 返回 seedance-2.5-wr-ref / seedance-2.0-wr-ref |
| 提交 | POST /v1/videos → 返回 {"id":"task_…","status":"queued"} |
| 轮询 | GET /v1/videos/{id} → status 为 queued / in_progress / completed / failed;completed 取 video_url |
| 取文件 | GET /v1/videos/{id}/content → video/mp4 字节流 |
参数固定为
model / prompt / seconds / resolution / ratio + 可选 reference_images / reference_videos / reference_audios;不走流式,异步任务。统一的视频生成请求格式:一段提示词,加上可选的参考图片、视频、音频。本文档只定义怎么请求,不对任何单一模型做限制——当前可用的模型与各自参数见第 3 节。供应商切换、密钥轮询、失败重试由网关处理。
1. 快速开始
三步跑通,大约 5 分钟。
- 向管理员申请令牌,格式为
sk-开头 - 调用
POST /v1/videos提交任务,拿到task id - 轮询
GET /v1/videos/{id},状态为completed时用video_url下载
curl -X POST https://independent.172-247-37-6.sslip.io/v1/videos \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-wr-ref",
"prompt": "一只橘猫在月夜屋顶上转身拔剑",
"seconds": 4,
"resolution": "480p",
"ratio": "9:16"
}'
生成是异步的:4 秒片段约 3–4 分钟,30 秒片段约 5 分钟。请不要同步等待,用轮询。
2. 认证
| 项 | 值 |
|---|---|
| Base URL | https://independent.172-247-37-6.sslip.io |
| 认证方式 | Authorization: Bearer sk-xxxxxxxx |
| 内容类型 | application/json |
3. 可用模型与各自限制
下面这些模型共用同一套请求格式,只是时长、素材上限和线路不同。同名模型有两条独立线路,后缀 -at 的走 Atlas,不带后缀的走 RunAPI,你可以按质量和成本自行选择;两条线路的请求写法完全一样。上限由网关在提交前校验,超限直接返回 400,不扣费。
| model | 时长 | 参考图 | 参考视频 | 参考音频 | 线路 |
|---|---|---|---|---|---|
seedance-2.5-wr-ref | 4–30 秒 | ≤ 30 | ≤ 10 | ≤ 10 | RunAPI 线路 |
seedance-2.0-wr-ref | 4–15 秒 | ≤ 9 | ≤ 3 | ≤ 3 | RunAPI 线路 |
seedance-2.5-wr-ref | 4–30 秒 | ≤ 30 | ≤ 10 | ≤ 10 | Atlas 线路 |
seedance-2.0-wr-ref | 4–15 秒 | ≤ 9 | ≤ 3 | ≤ 3 | Atlas 线路 |
支持画幅:16:9 9:16 1:1 4:3 3:4 21:9(另有 adaptive 跟随参考素材比例)。实际像素由「分辨率档位 + 画幅」决定,短边等于档位像素。
注意:
seconds 的上限跟着模型走。seedance-2.0-wr-ref 传 16 秒会被拒绝,
seedance-2.5-wr-ref 可以到 30 秒。素材数量同理。
4. 创建任务
POST /v1/videos
4.1 字段总表
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model | string | 是 | — | 模型 id,取第 3 节列出的值(如 seedance-2.5-wr-ref)。网关按你传的 id 路由,不做白名单限制 |
prompt | string | 是 | — | 画面描述,最多 20480 字符 |
resolution | string | 是 | — | 480p / 720p(1080p 暂未开放) |
seconds | number | 否 | 5 | 4–30 整数,或 -1 由模型决定 |
ratio | string | 否 | 9:16 | 16:9 9:16 1:1 4:3 3:4 21:9 adaptive |
reference_images | array | 否 | — | 参考图 URL,最多 30 张 |
reference_videos | array | 否 | — | 参考视频 URL,最多 10 个 |
reference_audios | array | 否 | — | 参考音频 URL,最多 10 个 |
别名(等价):
duration 等同于 seconds;image / images / input_reference 等同于单张参考图;
video 等同于单个参考视频;audio 等同于单个参考音频。
音频始终生成:模型原生同步生成音频,不支持关闭;也不要再传
generate_audio 或 return_last_frame,这两个字段已从接口移除。
4.2 完整请求
{
"model": "seedance-2.5-wr-ref",
"prompt": "@Image1 中的猫咪穿上盔甲,动作参考 @Video1,声音参考 @Audio1",
"seconds": 4,
"resolution": "480p",
"ratio": "9:16",
"reference_images": ["https://你的图/cat.png"],
"reference_videos": ["https://你的视频/move.mp4"],
"reference_audios": ["https://你的音频/voice.mp3"]
}
4.3 响应
{
"id": "task_xxxxxxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.5-wr-ref",
"status": "queued",
"progress": 0,
"created_at": 1793420998
}
5. 素材要求
所有参考素材都必须是公网可访问的 URL,不支持上传文件。数量上限随模型不同,先看第 3 节。
图片 reference_images
| 项 | 限制 |
|---|---|
| 张数 | 2.5 系(含 -at)≤ 30 / 2.0 系 ≤ 9 |
| 格式 | jpeg / png / webp / bmp / tiff / gif / heic / heif |
| 边长 | 300 – 6000 px |
| 宽高比 | 0.4 – 2.5 |
| 单张大小 | < 30 MB |
视频 reference_videos
| 项 | 限制 |
|---|---|
| 数量 | 2.5 系 ≤ 10 / 2.0 系 ≤ 3 |
| 格式 | mp4 / mov(H.264 / H.265 + AAC / MP3) |
| 时长 | 单段 2 – 30 秒;全部合计 ≤ 30 秒 |
| 分辨率 | 480p – 4K |
| 帧率 | 24 – 60 fps |
| 单个大小 | ≤ 200 MB |
音频 reference_audios
| 项 | 限制 |
|---|---|
| 数量 | 2.5 系 ≤ 10 / 2.0 系 ≤ 3 |
| 格式 | wav / mp3 |
| 时长 | 单段 2 – 30 秒;全部合计 ≤ 30 秒 |
| 单个大小 | ≤ 15 MB |
素材时长、格式、大小由上游校验。不合规会在提交阶段返回 400,不扣费。
6. @ 引用规则
| 写法 | 指向 |
|---|---|
@Image1 / @Image2 | reference_images 数组第 1 / 2 张 |
@Video1 | reference_videos 数组第 1 个 |
@Audio1 | reference_audios 数组第 1 个 |
编号 = 数组顺序,不要打乱。
实测注意:一旦挂了主体参考图,文字描述会被图片强烈压制。例如提示词写「蜘蛛侠大战黑寡妇」、参考图是一只猫,
实际生成的是「两只猫打架」。想精确控制画面,请把主体放图里、把动作放文字里。
7. 查询任务
GET /v1/videos/{task_id}
| status | progress | 含义 |
|---|---|---|
queued | 0 | 排队中 |
in_progress | 50 | 生成中 |
completed | 100 | 成功,取 video_url |
failed | 100 | 失败,读 error.message |
成功
{
"id": "task_xxxxxxxxxxxxxxxx",
"status": "completed",
"progress": 100,
"video_url": "https://media.example.com/.../xxx.mp4?X-Tos-Signature=...",
"url": "https://media.example.com/.../xxx.mp4?X-Tos-Signature=..."
}
失败
{
"id": "task_xxxxxxxxxxxxxxxx",
"status": "failed",
"progress": 100,
"error": {
"code": "upstream_failed",
"message": "The generated audio may be related to copyright restrictions and was blocked by the provider policy."
}
}
error.message 是上游原始原因,可直接展示给终端用户,不是笼统的「生成失败」。8. 取视频
方式 A:直接下载链接(推荐)
用 video_url 直接下载。
curl -L -o out.mp4 "https://media.example.com/.../xxx.mp4?X-Tos-Signature=..."
方式 B:走网关代理
GET /v1/videos/{task_id}/content
Authorization: Bearer sk-xxxxxxxx
返回 video/mp4 字节流,由网关实时转发上游,服务器不存储文件。
链接 24 小时后过期,且不可续期。拿到链接必须立刻转存到自己的存储,否则过期只能重新生成(再次计费)。
9. 错误码
| HTTP | 场景 | 处理 |
|---|---|---|
| 400 | 缺 resolution、时长越界、模型名错、素材不合规 | 按 error.message 改参数,不扣费 |
| 401 | 令牌无效或已禁用 | 检查 sk- 令牌 |
| 402 | 额度不足 | 充值 |
| 429 | 限流 | 退避重试 |
200 + status=failed | 上游生成失败 | 读 error.message,不要盲目重发 |
错误响应体:
{ "error": { "code": "", "message": "Invalid request: ...", "type": "new_api_error" } }
10. 计费
费用 = 实际输出秒数 × 分辨率单价
| 分辨率 | 单价 | 示例 |
|---|---|---|
| 480p | $0.10 / 秒 | 4 秒 = $0.40 |
| 720p | $0.20 / 秒 | 30 秒 = $6.00 |
- 按令牌额度扣减,每次调用的金额可在「使用日志」查看
- 提交阶段被拒(400)不扣费
- 生成阶段失败:网关退款给令牌额度
seconds: -1时先按 30 秒预留,完成后按实际秒数结算
11. 完整示例
Python
import time, requests
BASE, TOKEN = "https://independent.172-247-37-6.sslip.io", "sk-xxxxxxxx"
H = {"Authorization": f"Bearer {TOKEN}"}
# 1) 创建
r = requests.post(f"{BASE}/v1/videos", headers=H, json={
"model": "seedance-2.5-wr-ref",
"prompt": "@Image1 中的猫咪在屋顶飞檐走壁",
"seconds": 4,
"resolution": "480p",
"ratio": "9:16",
"reference_images": ["https://你的图/cat.png"],
}, timeout=120)
r.raise_for_status()
task_id = r.json()["id"]
# 2) 轮询
while True:
s = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H, timeout=30).json()
if s["status"] == "completed":
url = s["video_url"]
break
if s["status"] == "failed":
raise RuntimeError(s["error"]["message"])
time.sleep(10)
# 3) 立刻下载(24 小时内)
with requests.get(url, stream=True, timeout=300) as v:
v.raise_for_status()
with open(f"{task_id}.mp4", "wb") as f:
for chunk in v.iter_content(1 << 20):
f.write(chunk)
print("saved", f"{task_id}.mp4")
Node.js
const BASE = "https://independent.172-247-37-6.sslip.io";
const TOKEN = "sk-xxxxxxxx";
const H = { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" };
const created = await fetch(`${BASE}/v1/videos`, {
method: "POST", headers: H,
body: JSON.stringify({
model: "seedance-2.5-wr-ref",
prompt: "一只橘猫在月夜屋顶上转身拔剑",
seconds: 4, resolution: "480p", ratio: "9:16"
})
}).then(r => r.json());
let url = null;
while (true) {
const s = await fetch(`${BASE}/v1/videos/${created.id}`, { headers: H }).then(r => r.json());
if (s.status === "completed") { url = s.video_url; break; }
if (s.status === "failed") throw new Error(s.error.message);
await new Promise(res => setTimeout(res, 10000));
}
console.log("done:", url);
cURL 轮询脚本
TASK=$(curl -s -X POST "$BASE/v1/videos" \
-H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
-d '{"model":"seedance-2.5-wr-ref","prompt":"...","seconds":4,"resolution":"480p"}' \
| sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
while :; do
BODY=$(curl -s "$BASE/v1/videos/$TASK" -H "Authorization: Bearer $SK")
echo "$BODY" | grep -q '"status":"completed"' && { echo "$BODY"; break; }
echo "$BODY" | grep -q '"status":"failed"' && { echo "$BODY"; exit 1; }
sleep 10
done
12. 常见坑
| 坑 | 现象 | 解法 |
|---|---|---|
忘写 resolution | 400 | 必填,三档之一 |
| 时长写 3 或 31 | 400 | 只能 4–30 或 -1 |
| 参考图用本地路径 | 400 | 必须公网 URL |
| 同一单重复提交 | 重复扣费 | 超时先查状态,确认失败再重发 |
| 第二天才下载 | 链接 404 | 24 小时内转存 |
幂等建议
- 提交失败(4xx / 5xx):可以重试
- 已拿到 task id:绝不重发,改为查询状态
- 轮询失败:可以重试,不产生费用
- 下载失败:可以重试(24 小时内有效)
13. 更新日志
| 版本 | 变更 |
|---|---|
| v1.3 | 新增 seedance-2.0-wr-ref(4–15 秒,参考图 9 / 视频 3 / 音频 3) |
| v1.2 | 新增参考视频 / 参考音频;补充 @ 引用实测注意;明确 20480 字符上限 |
| v1.1 | resolution 改为必填;1080p 暂不开放 |
| v1.0 | 首发:文生视频 + 参考图生视频 |
有疑问请联系管理员。文档版本 v1.3。