01快速开始
异步任务：提交拿 id，轮询到 completed 后取成片。
端点别用错。本系列走 POST /v1/videos，不能用 /v1/chat/completions —— 用对话接口调会直接 404。
- Base URL
https://www.salpx.com/v1- 鉴权
Authorization: Bearer <SalpX Token>- 提交任务
POST /v1/videos- 查询状态
GET /v1/videos/{id}- 代理取片
GET /v1/videos/{id}/content- 模型名
- 不带参考视频
seedance-2.5-720p-ml；带参考视频seedance-2.5-ref-720p-ml - 必填参数
model、prompt、duration（整数秒）- 客户端超时
- 建议轮询总超时 ≥ 600 秒
分辨率固定 720p，不用传。请求体里的 resolution 会被改成 720p。
02模型与价格
按出片秒数计费，单价 × 出片秒数 = 总价。价格单位为人民币元 / 秒。
| 模型名 | 任务类型 | 单价 | 4 秒 | 10 秒 | 30 秒 |
|---|---|---|---|---|---|
seedance-2.5-720p-ml | 不带参考视频（文生 / 首帧 / 首尾帧 / 参考图 / 参考音频） | ¥1.08 / 秒 | ¥4.32 | ¥10.80 | ¥32.40 |
seedance-2.5-ref-720p-ml | 带参考视频（可同时带参考图 / 参考音频） | ¥1.45 / 秒 | ¥5.80 | ¥14.50 | ¥43.50 |
按是否带参考视频选模型名。请求里有 reference_video 必须用 seedance-2.5-ref-720p-ml，没有则必须用 seedance-2.5-720p-ml；用错会直接返回 400，不扣费。
参考视频时长不另收费，只按出片秒数计。参考图、参考音频、生成有声视频也都不加价。
03计费方式
提交成功即按「单价 × 出片秒数」扣费；任务失败或超时自动全额退回。
| 情形 | 计费公式 |
|---|---|
seedance-2.5-720p-ml（不带参考视频） | ¥1.08 × 出片秒数 |
seedance-2.5-ref-720p-ml（带参考视频） | ¥1.45 × 出片秒数 |
出片秒数就是请求里的 duration（4 – 30 的整数）。
04参考素材规则
| 素材 | 上限 |
|---|---|
| 参考图 | 最多 30 张 |
| 参考视频 | 最多 10 个（仅 seedance-2.5-ref-720p-ml） |
| 参考音频 | 最多 10 段 |
| 只传参考音频 | 支持 |
| 首尾帧 | 支持 |
| 出片时长 | 4 – 30 秒 |
媒体地址必须是公网可直接下载的 URL（上游服务器要能取到文件）。私有云链接、需要登录或带防盗链的地址会取片失败。audio_url 必须是真音频文件（wav / mp3 等）。
05提交任务
5.1 请求格式
文本放顶层 prompt，媒体放 metadata.content，每项带 role：
| role | 用途 |
|---|---|
first_frame / last_frame | 首帧 / 尾帧（只传首帧即首帧图生视频） |
reference_image | 参考图（主体 / 风格 / 构图） |
reference_video | 参考视频（运镜 / 动作），须用 seedance-2.5-ref-720p-ml |
reference_audio | 参考音频（节奏 / 环境声） |
顶层参数：duration（必填，整数秒）、ratio（可选：16:9、4:3、1:1、3:4、9:16、21:9、adaptive）。要生成带声音的视频，在 metadata 里传 "generate_audio": true，不加价。
首帧 / 首尾帧任务不要传 ratio。这种模式下画幅固定跟随首帧图，传了 ratio 会被上游拒绝（任务失败、自动退款）。
其它模式下，不传 ratio 时本网关不代填默认值；带参考素材时画幅可能跟随素材。要锁定 16:9 等画幅，请显式传 ratio。
5.2 纯文生视频
curl -X POST https://www.salpx.com/v1/videos \ -H "Authorization: Bearer $SALPX_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.5-720p-ml", "prompt": "霓虹都市夜景，镜头缓缓推进，雨后街道倒映灯光", "duration": 5, "ratio": "16:9" }'
5.3 首帧 / 首尾帧
curl -X POST https://www.salpx.com/v1/videos \ -H "Authorization: Bearer $SALPX_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.5-720p-ml", "prompt": "从第一张图自然过渡到第二张图", "duration": 5, "metadata": { "content": [ {"type":"image_url","image_url":{"url":"https://your-cdn.com/first.png"},"role":"first_frame"}, {"type":"image_url","image_url":{"url":"https://your-cdn.com/last.png"},"role":"last_frame"} ] } }'
5.4 参考图 + 参考音频 + 有声
curl -X POST https://www.salpx.com/v1/videos \ -H "Authorization: Bearer $SALPX_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.5-720p-ml", "prompt": "角色与图片1一致，动作节奏贴合音频1", "duration": 8, "ratio": "16:9", "metadata": { "content": [ {"type":"image_url","image_url":{"url":"https://your-cdn.com/char.png"},"role":"reference_image"}, {"type":"audio_url","audio_url":{"url":"https://your-cdn.com/bgm.mp3"},"role":"reference_audio"} ], "generate_audio": true } }'
5.5 参考视频（用 seedance-2.5-ref-720p-ml）
curl -X POST https://www.salpx.com/v1/videos \ -H "Authorization: Bearer $SALPX_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.5-ref-720p-ml", "prompt": "角色跟图片1一致，运镜跟视频1", "duration": 10, "ratio": "16:9", "metadata": { "content": [ {"type":"image_url","image_url":{"url":"https://your-cdn.com/char.png"},"role":"reference_image"}, {"type":"video_url","video_url":{"url":"https://your-cdn.com/motion.mp4"},"role":"reference_video"} ] } }'
5.6 提交成功的响应
返回的是 SalpX 的任务 ID（task_ 开头），后续查询和取片都用这个 ID。
{
"id": "task_wD4efMzF414I6eMTQ7j2A3bW1Wluh44L",
"task_id": "task_wD4efMzF414I6eMTQ7j2A3bW1Wluh44L",
"object": "video",
"model": "seedance-2.5-720p-ml",
"status": "queued",
"progress": 0,
"created_at": 1791600000
}
id 和 task_id 恒为同一个值，新接入用 id 即可。
06轮询与取片
用 GET /v1/videos/{id} 轮询，建议间隔 15 秒。
curl https://www.salpx.com/v1/videos/task_wD4efMzF414I6eMTQ7j2A3bW1Wluh44L \ -H "Authorization: Bearer $SALPX_KEY"
status | 含义 |
|---|---|
queued | 排队中 |
in_progress | 生成中 |
completed | 已完成，成片地址在 metadata.url |
failed | 失败，原因在顶层 error；已自动退款 |
成片地址在 metadata.url，不在顶层。取值写法：resp["metadata"]["url"]。任务未完成时为空字符串。progress 只是状态的粗略映射，请以 status 判断是否结束。
{
"id": "task_wD4efMzF414I6eMTQ7j2A3bW1Wluh44L",
"task_id": "task_wD4efMzF414I6eMTQ7j2A3bW1Wluh44L",
"object": "video",
"model": "seedance-2.5-720p-ml",
"status": "completed",
"progress": 100,
"created_at": 1791600000,
"completed_at": 1791600160,
"metadata": {
"url": "https://video.example.com/xxxx.mp4"
}
}
| 取片方式 | 说明 |
|---|---|
| 直链下载 | metadata.url 是公网地址，直接 GET 即可 |
| 代理取片 | GET /v1/videos/{id}/content，需带 Authorization，由 SalpX 中转返回同一个文件 |
成片链接请及时转存。直链是临时地址，会过期，不要当长期存储用。
07错误处理
| HTTP | 典型信息 | 处理 |
|---|---|---|
| 404 | bad response status code 404 | 用了 /v1/chat/completions，改用 POST /v1/videos |
| 400 | duration 不在允许范围 | 4 – 30 秒，整数 |
| 400 | reference_video_not_allowed / reference_video_required | 模型名和参考视频不匹配：带参考视频用 seedance-2.5-ref-720p-ml，不带用 seedance-2.5-720p-ml |
| 400 | too_many_reference_images / videos / audios | 减少素材数量，上限见第 04 节 |
| — | 任务 failed：ratio is not valid … follows the first-frame image | 首帧 / 首尾帧任务去掉 ratio |
| — | 任务 failed：素材下载失败 | 媒体 URL 需公网可直接下载 |
| 403 | token quota is not enough | 余额不足，充值或换令牌 |
| 503 | No available channel | 模型名拼错或令牌分组未开通 |
失败自动退款。提交被拒、上游失败、超时或任务进入 failed，已扣额度全额退回，不产生扣费。