星算云 开发者文档

主题

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

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

与 Seedance(火山兼容)、k/seedance(按秒计费)、c/seedance(按秒计费)、z/seedance(按秒计费) 区别:本网关只接 以 s/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,z/seedance 模型请走 POST /api/v3/z/videos/generations/tasks。

基础信息 ​

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

API Key 安全

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

官方格式入口(可选)

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

模型 ​

模型代码分辨率时长特性
s/seedance-2.5仅 720p4–30 秒(整数)文生视频、首帧驱动、首尾帧、全能参考(图/视频/音频混合),同步音频默认启用

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

计费 ​

按「计费秒数 × 单价」计费,所有生成模式同一单价(文生视频、首帧、首尾帧、全能参考均相同):

分辨率单价(元/输出秒)
720p0.600000

计费规则:

  • 计费秒数 = 请求的输出时长(duration),不叠加参考视频或参考音频时长。
  • 携带参考素材(图片/视频/音频)不改变单价与计费秒数。
  • 最终费用 = 计费秒数 × 单价 × 账户折扣,从账户钱包实时扣减。任务失败不收取费用。

示例(无折扣):生成 10 秒、含参考视频 → 10 × 0.60 = 6.00 元。

创建任务 ​

POST /api/v3/s/videos/generations/tasks

bash
API_BASE=https://xingsuan.cloud
curl "$API_BASE/api/v3/s/videos/generations/tasks" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "s/seedance-2.5",
    "prompt": "清晨的海边公路,一辆黑色跑车穿过薄雾,镜头从低机位平稳追随,真实电影摄影风格",
    "duration": 8,
    "resolution": "720p",
    "ratio": "16:9"
  }'
python
import requests

API_BASE = "https://xingsuan.cloud"
resp = requests.post(
    f"{API_BASE}/api/v3/s/videos/generations/tasks",
    headers={"Authorization": f"Bearer {XSK_KEY}"},
    json={
        "model": "s/seedance-2.5",
        "prompt": "清晨的海边公路,一辆黑色跑车穿过薄雾,镜头从低机位平稳追随,真实电影摄影风格",
        "duration": 8,
        "resolution": "720p",
        "ratio": "16:9",
    },
)
data = resp.json()
print(data["task_id"])  # 任务 ID,用于查询

请求参数

参数位置必填默认值说明
AuthorizationHeader是Bearer xsk_...
modelBody是s/seedance-2.5
promptBody是视频生成提示词,不能为空(所有模式均必填)
durationBody否4输出时长秒 [4,30] 的整数;不支持 -1
resolutionBody否720p当前固定 720p
ratioBody否adaptiveadaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
input_typeBody否reference普通生成/全能参考用 reference;首帧/首尾帧用 first_last_frame
referencesBody否[]参考素材数组,图片≤30 / 视频≤10 / 音频≤10,见参考素材
seedBody否随机随机种子;字符串时应为十进制整数字符串

创建响应 ​

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

json
{
  "task_id": "task_09e650d163219bfd056acdf0",
  "status": "running",
  "model": "s/seedance-2.5",
  "createdAt": "2026-08-15T03:45:20.000Z"
}

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

查询任务 ​

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

bash
curl "$API_BASE/api/v3/s/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": "s/seedance-2.5",
  "videoUrl": "https://example.com/generated-video.mp4",
  "lastFrameUrl": null,
  "billedSeconds": 10,
  "usage": null,
  "error": null,
  "createdAt": "2026-08-15T03:45:20.000Z",
  "completedAt": "2026-08-15T03:49:38.000Z"
}

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

失败

json
{
  "task_id": "task_09e650d163219bfd056acdf0",
  "status": "failed",
  "model": "s/seedance-2.5",
  "videoUrl": null,
  "lastFrameUrl": null,
  "usage": null,
  "error": { "code": null, "message": "task failed" },
  "createdAt": "2026-08-15T03:45:20.000Z",
  "completedAt": "2026-08-15T03:46:12.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 中混合,数量上限分别为 30 / 10 / 10。

文生视频(无需 references)

json
{
  "model": "s/seedance-2.5",
  "prompt": "雨后的未来城市,霓虹倒映在路面,镜头平稳向前推进,电影级真实摄影",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

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

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

首尾帧生成(必须含一张 first_frame,可选一张 last_frame;last_frame 不能单独使用)

json
{
  "model": "s/seedance-2.5",
  "prompt": "从清晨的海边自然过渡到夜幕下的灯塔,保持主体、构图和镜头运动连续",
  "input_type": "first_last_frame",
  "duration": 10,
  "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": "s/seedance-2.5",
  "prompt": "保持人物外观、动作节奏和环境声一致,使用电影级运镜",
  "input_type": "reference",
  "duration": 10,
  "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 排查)。
  • 平台侧错误(鉴权失败 / 模型不存在 / 非 s/seedance 按秒模型 / 钱包余额不足等):统一为火山风格信封 {"error":{"code":"<字符串>","message":...}}。上游超时 → 504;连接错误 → 502。详见 错误码。

路由约束

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

Copyright © 2026 星算云