星算云 开发者文档

主题

z/seedance 视频生成(按秒计费) ​

星算云 z/seedance 视频网关挂载于 /api/v3,对外提供 z/seedance 系列模型(按秒计费)。请求体与响应体沿用上游原生格式(扁平对象)原样透传,平台仅做鉴权、模型校验与按秒计费;鉴权用 Authorization: Bearer xsk_...。

与 Seedance(火山兼容)、k/seedance(按秒计费)、c/seedance(按秒计费)、s/seedance(按秒计费) 区别:本网关只接 以 z/seedance 开头且按秒计费 的模型;火山系(token 计费)模型请走 POST /api/v3/contents/generations/tasks,k/seedance 模型请走 POST /api/v3/videos/generations/tasks,c/seedance 模型请走 POST /api/v3/c/videos/generations/tasks,s/seedance 模型请走 POST /api/v3/s/videos/generations/tasks。

基础信息 ​

项目内容
Base URLhttps://xingsuan.cloud(平台地址)
创建任务POST /api/v3/z/videos/generations/tasks(成功回 202)
查询任务GET /api/v3/z/videos/generations/tasks/{task_id}
Content-Typeapplication/json
鉴权 HeaderAuthorization: Bearer xsk_...(平台 API Key)

API Key 安全

只在服务端保存 API Key,不要放入浏览器、公开仓库或客户端安装包。

官方格式入口(可选)

z/seedance 按秒模型也可经 POST /api/v3/contents/generations/tasks(Seedance 官方格式)调用:创建回 202、usage 恒 null、duration 必填(整数 [4,30],不支持 -1)、content 必填。计费秒数 = 查询响应回报的 billedSeconds(与本端点口径一致,均为输出时长);duration 仅在响应未回报秒数时兜底。详见 Seedance(火山兼容) 的「按秒模型官方格式入口」。

模型 ​

全部 Z Seedance 模型支持文生视频、首帧驱动、首尾帧生成、图/视频/音频全能参考、同步音频开关 generate_audio,画幅 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / adaptive。

模型代码分辨率输出时长图片上限视频上限音频上限
z/seedance-2.5480p、720p4–30 秒301010
z/seedance-2.0480p、720p、1080p、4k4–15 秒933
z/seedance-2.0-fast480p、720p4–15 秒933
z/seedance-2.0-mini480p、720p4–15 秒933

z/ 前缀用于固定选择 Z 渠道。平台以请求体 model 为准。

计费 ​

按「计费秒数 × 分辨率 × 是否含视频参考单价」计费,单位元/输出秒,以平台模型配置价格与 API Key 折扣为准,从账户钱包实时扣减。

  • 计费秒数 = 输出视频时长(即请求的 duration),不叠加参考视频或参考音频时长。
  • 请求只含图片或音频参考时,仍用「无视频参考」单价;含至少一个视频参考时用「含视频参考」单价。
  • 任务失败不收取费用,预扣金额释放。

标准价目(元/输出秒;账户有折扣时以控制台显示的实际价格为准):

模型分辨率无视频参考含视频参考
z/seedance-2.0-mini480p0.2300000.265000
z/seedance-2.0-mini720p0.5000000.565000
z/seedance-2.0-fast480p0.3700000.410000
z/seedance-2.0-fast720p0.8000000.890000
z/seedance-2.0480p0.4600000.525000
z/seedance-2.0720p0.9900001.125000
z/seedance-2.01080p2.4700002.820000
z/seedance-2.04k5.0500005.830000
z/seedance-2.5480p0.6730000.605000
z/seedance-2.5720p1.5120001.361000

示例(无折扣):z/seedance-2.5、720p、10 秒、含视频参考 → 10 × 1.361 = 13.61 元。

创建任务 ​

POST /api/v3/z/videos/generations/tasks

bash
API_BASE=https://xingsuan.cloud
curl "$API_BASE/api/v3/z/videos/generations/tasks" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "z/seedance-2.5",
    "prompt": "雨后的未来城市,霓虹倒映在路面,镜头平稳向前推进,电影级真实摄影",
    "input_type": "reference",
    "duration": 8,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'
python
import requests

API_BASE = "https://xingsuan.cloud"
resp = requests.post(
    f"{API_BASE}/api/v3/z/videos/generations/tasks",
    headers={"Authorization": f"Bearer {XSK_KEY}"},
    json={
        "model": "z/seedance-2.5",
        "prompt": "雨后的未来城市,霓虹倒映在路面,镜头平稳向前推进,电影级真实摄影",
        "input_type": "reference",
        "duration": 8,
        "resolution": "720p",
        "ratio": "16:9",
        "generate_audio": True,
        "watermark": False,
    },
)
data = resp.json()
print(data["task_id"])  # 任务 ID,用于查询

请求参数

参数位置必填说明
AuthorizationHeader是Bearer xsk_...
modelBody是Z Seedance 完整模型代码
promptBody条件必填文本提示词;prompt 与 references 至少提供一个
referencesBody否参考素材数组,上限见模型表,见参考素材
input_typeBody否reference(默认,普通生成/全能参考);首帧/首尾帧用 first_last_frame
durationBody否输出时长秒;2.5 为 [4,30],2.0 系列为 [4,15];建议显式传入
resolutionBody否输出分辨率,须为所选模型支持的值;建议显式传入
ratioBody否输出画幅;建议显式传入
generate_audioBody否是否生成同步音频;建议根据需要显式传入
watermarkBody否是否添加水印,默认 false

创建响应 ​

创建成功返回 HTTP 202(任务已受理,异步处理),响应为扁平对象:

json
{
  "task_id": "task_09e650d163219bfd056acdf0",
  "status": "running",
  "model": "z/seedance-2.5",
  "createdAt": "2026-08-12T10:00:00.000Z"
}

保存 task_id,后续用它查询任务。202 只表示任务已受理,不代表生成成功,请持续轮询到终态,不要重复创建。

查询任务 ​

GET /api/v3/z/videos/generations/tasks/{task_id}

bash
curl "$API_BASE/api/v3/z/videos/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $XSK_KEY"

建议每隔至少 5 秒查询一次。succeeded 与 failed 为终态。

status 取值

status含义是否终态
running处理中否
succeeded成功,videoUrl 为视频地址(首尾帧模式可能附 lastFrameUrl)是
failed失败,error.message 含原因是

成功

json
{
  "task_id": "task_09e650d163219bfd056acdf0",
  "status": "succeeded",
  "model": "z/seedance-2.5",
  "videoUrl": "https://example.com/generated-video.mp4",
  "lastFrameUrl": null,
  "billedSeconds": 10,
  "usage": null,
  "error": null,
  "createdAt": "2026-08-12T10:00:00.000Z",
  "completedAt": "2026-08-12T10:04:30.000Z"
}

billedSeconds 为该任务实际计费秒数(= 输出视频时长),仅在成功并完成结算后返回。

失败

json
{
  "task_id": "task_09e650d163219bfd056acdf0",
  "status": "failed",
  "model": "z/seedance-2.5",
  "videoUrl": null,
  "lastFrameUrl": null,
  "usage": null,
  "error": { "code": null, "message": "task failed" },
  "createdAt": "2026-08-12T10:00:00.000Z",
  "completedAt": "2026-08-12T10:01:00.000Z"
}

视频 URL 有效期

videoUrl 可能具有有效期,请在任务成功后及时保存或下载。

参考素材 ​

references 是对象数组,每一项字段如下:

字段类型必填说明
typestring是image、video 或 audio
urlstring是服务端可直接访问的公网 HTTP(S) URL
rolestring普通参考否;首帧/尾帧是普通参考:reference_image / reference_video / reference_audio(省略时按 type 自动识别);首帧/尾帧:first_frame / last_frame(必须显式填写)

参考素材须为公网可直接访问的 HTTP(S) 地址;预签名 URL 有效期应覆盖任务处理全程;不支持本地路径、内网地址或需登录态的地址。

文生视频(无需 references)

json
{
  "model": "z/seedance-2.5",
  "prompt": "雨后的未来城市,镜头平稳向前推进,电影级真实摄影",
  "input_type": "reference",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

首帧驱动(input_type: "first_last_frame",必须且只能含一张 first_frame,不得混入其他参考)

json
{
  "model": "z/seedance-2.5",
  "prompt": "人物缓慢转身看向镜头,衣摆随风摆动,镜头轻微推进",
  "input_type": "first_last_frame",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9",
  "references": [
    { "type": "image", "url": "https://example.com/first.jpg", "role": "first_frame" }
  ]
}

首尾帧生成(必须含一张 first_frame,可选一张 last_frame;不能混入其他参考素材)

json
{
  "model": "z/seedance-2.0",
  "prompt": "从清晨自然过渡到夜晚,保持主体、构图和镜头运动连续",
  "input_type": "first_last_frame",
  "duration": 8,
  "resolution": "720p",
  "ratio": "adaptive",
  "references": [
    { "type": "image", "url": "https://example.com/first.jpg", "role": "first_frame" },
    { "type": "image", "url": "https://example.com/last.jpg", "role": "last_frame" }
  ]
}

全能参考(input_type: "reference",图/视频/音频混合;是否含「视频参考」决定计费单价档)

json
{
  "model": "z/seedance-2.5",
  "prompt": "保持人物外观、动作节奏和环境声一致,使用电影级运镜",
  "input_type": "reference",
  "duration": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "references": [
    { "type": "image", "url": "https://example.com/character.jpg", "role": "reference_image" },
    { "type": "video", "url": "https://example.com/motion.mp4", "role": "reference_video" },
    { "type": "audio", "url": "https://example.com/music.mp3", "role": "reference_audio" }
  ]
}

错误 ​

  • 上游响应:原样透传上游扁平对象与 OpenAI 风格错误体(400 参数/余额、401 鉴权、404 模型/任务、429 限流、503 不可用,按 error.param / error.code / error.message 排查)。
  • 平台侧错误(鉴权失败 / 模型不存在 / 非 z/seedance 按秒模型 / 钱包余额不足等):统一为火山风格信封 {"error":{"code":"<字符串>","message":...}}。上游超时 → 504;连接错误 → 502。详见 错误码。

路由约束

本网关只接受 以 z/seedance 开头且按秒计费 的模型;若传入其他模型会返回 400 invalid_request——k/seedance 模型请改用 POST /api/v3/videos/generations/tasks,c/seedance 模型请改用 POST /api/v3/c/videos/generations/tasks,s/seedance 模型请改用 POST /api/v3/s/videos/generations/tasks,火山系(token 计费)模型请改用 POST /api/v3/contents/generations/tasks。

Copyright © 2026 星算云