ULTIVOX · OPEN API · SEEDANCE 2.0 EDITION
Seedance 2.0 系列专用接口文档（v1.4）
本文档从平台总文档中抽出 Seedance 2.0 / 2.0 Fast / 2.0 Mini 三款基础模型 与 Seedance 2.0 Pro / fast 两款进阶模型 在自主创作模式（free-video）下的全部接口行为与参数，与网页端行为完全一致。基础三款全模式可用；Pro / fast 仅自主创作。适用读者：您本人与您的 AI 助手（附「如何对 AI 说」对话模板）。
Base URL：https://ultivox.cn/api/open/v1
5 个模型：seedance2 / _fast / _mini / _pro / _fast_multimodal
版本 v1.4 · 2026-10-14
自主创作 free-video
RULES Seedance 2.0 系列核心红线（先读这个）⏱️ 时长：仅支持 4 ~ 15 的整数秒。 超限直接 400（与网页端一致）。需要 15 秒以上的视频请改用 Wan3.0（支持 2–30 秒，见 Wan3.0 专用文档）。
🖼️ 分辨率：固定 720P 竖屏（9:16）。 本系列不提供清晰度选择，resolution 参数传了会被忽略——请不要依赖它。
维度 Seedance 2.0 系列的行为 时长 duration 4–15 整数秒 （默认 5）。小数向下取整分辨率 resolution 固定 720P 竖屏 9:16 ，参数传值忽略参考图 images ≤ 9 张 （注意：Wan3.0 上限为 10 张，两者不同）。超限 400参考视频 benchmark_video ✅ 可选，4~15 秒 （这是本系列独有优势 ）。平台自动人脸打码 + 消音条数 quantity 1–5，默认 1 排队说明 seedance2 白天提交会进入 scheduled 状态、22:00–06:00（北京时间）夜间窗口放行 ；Fast 与 Mini 不受夜间队列限制 ，全天可跑不支持 基础三款：音频素材（audios 传了 400，仅 Wan3.0 / Pro / fast 支持）/ 画幅选择（aspect_ratio 传了 400，本组固定 9:16）/ 首帧 / 尾帧 / 多参考视频 / 分辨率选择（当前均不支持）
PICK 五款模型差异速查
API 模型值 网页端展示名 每秒单价 分辨率 排队 适合 seedance2Seedance 2.0 20 星点/秒 720P 竖屏（固定） 夜间队列（22:00–06:00 放行） 对画面与运镜要求最高的主力出片 seedance2_fastSeedance 2.0 Fast 15 星点/秒 720P 竖屏（固定） 全天可跑 速度与质量均衡的日常选择 seedance2_miniSeedance 2.0 Mini 10 星点/秒 720P 竖屏（固定） 全天可跑 出片最快，批量出草稿 seedance2_proSeedance 2.0 Pro 480P=30 · 720P=60 · 1080P=73 480P / 720P / 1080P 可选 全天可跑 多素材精准复刻、强参考控制 seedance2_fast_multimodalSeedance 2.0 fast 480P=25 · 720P=49 · 1080P=63 480P / 720P / 1080P 可选 全天可跑 能力档同 Pro、更快出片
📌 基础三款 （2.0 / Fast / Mini）支持的模式、参数、参考图上限（9 张）完全相同 ，差异只在排队策略与单价。拿不准就用 seedance2_fast。Pro / fast 两款仅自主创作（free-video）可用 ，其余模式传了直接 400；支持参考视频数组与音频素材（见下节）。
AUTH 认证与端点清单所有请求携带请求头：Authorization: Bearer sk-rh-xxxxxxxx...（密钥在网页端「个人中心 → API 密钥」）。限频 60 次/分钟 ，超限返回 429 + Retry-After。
方法 端点 用途 GET /me当前账户信息 GET /pricing实时价目表 POST /videos提交视频任务（自主创作 free-video，见下） GET /videos任务列表（?status=&limit=，limit 默认 10 最大 50） GET /videos/{job_id}查询单任务进度与结果 POST /assets导入外部素材（图片/视频 URL → asset_id） POST /images提交生图任务（见生图专用文档） GET /images/{job_id}查询单个生图任务 POST /chat/completionsAI 对话（OpenAI 兼容，按 token 计费）
📌 素材建议：直接传公网 https 直链即可；大文件或需复用的素材先走 POST /assets 换成 {"asset_id": "..."} 引用（图片格式 JPG/JPEG/PNG/WebP，单张建议 ≤10MB；参考视频 MP4 优先、H.264、建议 ≤200MB、≤15 秒）。素材 URL 必须公网 https 可匿名 GET。
MODE 自主创作 free-video（纯文 / 图生视频）POST /videos mode=free-video
参数 必填 说明 mode否 free-video（自主创作）model否 seedance2 / seedance2_fast / seedance2_mini（缺省时为 Wan3.0，请显式传本系列模型值 ）prompt必填 视频创作要求描述（建议 ≤2000 字符，中英文可换行；硬上限 100000 字符，超限提交失败） duration否 4–15 整数秒 （默认 5）。超限 400images否 参考图数组，最多 9 张 （URL 字符串或 {"asset_id"} 对象均可），超限 400 benchmark_video否 ✅ 可选（本系列独有） ：参考视频 4~15 秒，平台自动人脸打码 + 消音，AI 参考其节奏与镜头语言进行创作。URL 或 {"asset_id"} 均可quantity否 1–5，默认 1 resolution / ratio— 忽略 ：分辨率固定 720P 竖屏、画幅固定 9:16，传值无效aspect_ratio / audios— ❌ 不支持 ：本系列成片固定 9:16 竖屏、不支持音频素材，传了返回 400（仅 Wan3.0 支持这两个参数）
POST /api/open/v1/videos
{
"mode" : "free-video" ,
"model" : "seedance2_fast" ,
"prompt" : "黄色亚麻衬衫套装平铺展示，柔光，电商白底风格" ,
"duration" : 10,
"images" : ["https://my-cdn.com/product.jpg" ]
}
# 201 返回：{ "job_id": "...", "status": "queued" }
「用 ULTIVOX 开放 API 的自主创作模式（mode=free-video）生成一条视频：Seedance 2.0 Fast、10 秒，prompt=「把图中的产品放在大理石台面上，环绕运镜展示细节，电商质感」，参考图 https://my-cdn.com/product.jpg。提交后每 10 秒轮询一次，出片后下载保存。密钥从环境变量 ULTIVOX_API_KEY 读取。」
PRO Seedance 2.0 Pro / fast（进阶款，仅自主创作）POST /videos mode=free-video model=seedance2_pro | seedance2_fast_multimodal
两款进阶模型在基础三款能力之上额外支持：480P / 720P / 1080P 三档分辨率 、画幅 9:16 / 16:9 、音频素材 与多参考视频数组 。除下列差异外，其余参数与基础三款一致。
参数 说明 resolution480P（默认）/ 720P / 1080P，按档计费（Pro：30/60/73；fast：25/49/63 星点/秒）aspect_ratio9:16（默认）/ 16:9——基础三款传该参数 400，Pro / fast 支持audios音频素材数组，最多 3 段、总时长 ≤30 秒 （https URL 或 {"asset_id"}） benchmark_videos参考视频数组：最多 3 个、单个 ≥2 秒且 ≤45 秒、总时长 ≤45 秒 ，超限 400。按参考视频时长额外计费（向上取整秒）：Pro（480P=18、720P=35、1080P=35）、fast（480P=12、720P=24、1080P=24）星点/秒 images参考图最多 9 张 （与基础三款一致） 模式限制 仅 free-video ：talking-sales / story-remix / viral-remix 传这两款模型直接 400
POST /api/open/v1/videos
{
"mode" : "free-video" ,
"model" : "seedance2_pro" ,
"prompt" : "参考这条爆款视频的节奏，把产品换成图中的保温杯" ,
"duration" : 10,
"resolution" : "720P" ,
"benchmark_videos" : ["https://my-cdn.com/hot-video.mp4" ],
"images" : ["https://my-cdn.com/product.jpg" ]
}
# 计费：10s × 60（720P）= 600 星点 + 参考视频 10s × 35 = 350 星点
「用 ULTIVOX 开放 API 生成视频：Seedance 2.0 Pro、720P、10 秒、自主创作模式，参考视频 https://my-cdn.com/hot-video.mp4（不超过 45 秒），参考产品图 https://my-cdn.com/product.jpg。写完整 Python：提交 → 轮询 → 下载成片。」
POLL 轮询与任务状态机GET /api/open/v1/videos/{job_id}
{
"job_id" : "..." ,
"status" : "queued | uploading | generating | scheduled | succeeded | failed" ,
"progress" : 0-100 ,
"video_url" : "https://...（succeeded 时返回，签名链接 6 小时内有效）"
}
状态 含义 调用方动作 queued排队中 继续等待 uploading素材上传中（参考图等上传并提交任务） 继续轮询 scheduled已进入夜间窗口等待（仅 seedance2 白天提交） 等到 22:00 后自动放行；赶时间请改用 Fast / Mini generating生成中 继续轮询 succeeded成功 取 video_url 下载（签名链接 6 小时内有效 ，请及时转存） failed失败 读 last_error 改参数重提
📌 轮询建议：每 10 秒一次即可，不要加密到 1 秒级（限频 60 次/分钟）。瞬时故障平台会自动重新排队重试（最多 2 次、30 秒退避），调用方无需处理。
# Python 轮询骨架
import time, requests
H = {"Authorization" : f"Bearer {os.environ['ULTIVOX_API_KEY']}" }
while True:
r = requests.get(f"https://ultivox.cn/api/open/v1/videos/{job_id}" , headers=H, timeout=30).json()
if r["status" ] in ("succeeded" , "failed" ): break
time.sleep(10)
if r["status" ] == "succeeded" :
mp4 = requests.get(r["video_url" ]).content
open("out.mp4" , "wb" ).write(mp4)
ERRORS 错误速查
HTTP code 典型原因与处理 400 validation_errorduration 不在 4–15、缺 prompt、参考图 >9、传了 aspect_ratio / audios（本系列不支持）等——改参数重提 401 unauthorized密钥缺失 / 无效 / 已禁用 402 insufficient_credits账户余额不足，请充值后再试（响应含 balance 与 required） 404 not_found任务 ID 不存在或端点写错 429 rate_limited超 60 次/分钟，按 Retry-After 等待后重试 500 internal_error平台内部错误，请稍后重试
ULTIVOX 开放 API · Seedance 2.0 系列专用文档 v1.4 · 2026-10-14 · 自主创作专用 · 单文件可离线查看