星算云 开发者文档

主题

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

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

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

基础信息 ​

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

API Key 安全

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

官方格式入口(可选)

r/seedance 按秒模型也可经 POST /api/v3/contents/generations/tasks(Seedance 官方格式)调用:创建回 202、usage 恒 null、duration 必填(整数 [4,30],不支持 -1)、content 必填。计费秒数 = 查询响应回报的 billedSeconds(与本端点同口径,含视频参考时为「参考视频总时长 + 输出时长」);duration 仅在响应未回报秒数时兜底,该兜底场景下含视频参考会低于上游结算口径。详见 Seedance(火山兼容) 的「按秒模型官方格式入口」。

模型 ​

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

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

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

duration 必须为整数,不支持 -1 智能时长。参考素材须为公网可直接访问的 HTTP(S) URL;R 渠道 无素材库,asset:// 引用不被识别;参考素材在任务创建后由上游异步拉取,不可访问或内容不合规 以 status=failed 返回(不会在创建时 400)。

多参考编号

提示词按素材在 references 中出现的顺序引用:第一张参考图为 @Image1,第一段参考视频为 @Video1(图片与视频分别从 1 计数,音频同理 @Audio1);首帧、尾帧不参与编号。顺序写错不会 报错,但会生成与描述不符的视频并正常计费。

计费 ​

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

  • 无参考视频(纯文本、仅图片或音频参考):计费秒数 = 请求的 duration,用「无参考视频」 单价;图片、音频的数量与时长不额外计费。
  • 含参考视频:计费秒数 = 所有参考视频时长之和(每段向上取整到整秒)+ 请求的 duration (最低按 4 秒),用「含参考视频」单价。
  • 平台信上游回报的 billedSeconds 结算,与上述口径一致;任务失败不收取费用。

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

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

示例(无折扣):r/seedance-2.0-mini、720p、参考视频 6.2 秒、生成 5 秒 → 计费秒数 = 7(6.2 向上取整)+ 5 = 12,费用 = 12 × 0.565 = 6.78 元。

含参考视频价档方向

R 渠道 2.0 系列与 K 渠道同价(含视频参考更贵);r/seedance-2.5 方向相反(含视频参考 更便宜)。上表已按官方价目列出,录入价目时以本表为准。

创建任务 ​

POST /api/v3/r/videos/generations/tasks

bash
API_BASE=https://xingsuan.cloud
curl "$API_BASE/api/v3/r/videos/generations/tasks" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "r/seedance-2.0-fast",
    "prompt": "一只橘猫在清晨的草地上奔跑,阳光透过树叶形成光斑,电影感真实摄影",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
python
import requests

API_BASE = "https://xingsuan.cloud"
resp = requests.post(
    f"{API_BASE}/api/v3/r/videos/generations/tasks",
    headers={"Authorization": f"Bearer {XSK_KEY}"},
    json={
        "model": "r/seedance-2.0-fast",
        "prompt": "一只橘猫在清晨的草地上奔跑,阳光透过树叶形成光斑,电影感真实摄影",
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
)
data = resp.json()
print(data["task_id"])  # 任务 ID,用于查询

请求参数

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

创建响应 ​

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

json
{
  "task_id": "task_c4060d94f1bef4eed796bc99",
  "status": "running",
  "model": "r/seedance-2.0-mini",
  "createdAt": "2026-09-07T07:37:57.482Z"
}

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

查询任务 ​

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

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

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

status 取值

status含义是否终态
running处理中否
succeeded成功,videoUrl 为视频地址(请求 return_last_frame: true 时可能附 lastFrameUrl)是
failed失败,error.message 含原因是

成功

json
{
  "task_id": "task_c4060d94f1bef4eed796bc99",
  "status": "succeeded",
  "model": "r/seedance-2.0-mini",
  "videoUrl": "https://example.com/generated-video.mp4",
  "lastFrameUrl": null,
  "billedSeconds": 4,
  "usage": null,
  "error": null,
  "createdAt": "2026-09-07T07:37:57.482Z",
  "completedAt": "2026-09-07T07:39:35.512Z"
}

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

失败

json
{
  "task_id": "task_c4060d94f1bef4eed796bc99",
  "status": "failed",
  "model": "r/seedance-2.0-mini",
  "videoUrl": null,
  "lastFrameUrl": null,
  "usage": null,
  "error": {
    "code": null,
    "message": "Reference material @Image2 could not be prepared: url is not reachable"
  },
  "createdAt": "2026-09-07T07:37:57.482Z",
  "completedAt": "2026-09-07T07:38:10.000Z"
}

失败原因常见为参考素材 URL 无法访问、格式不支持或内容审核未通过(error.message 会用请求中的 编号指出是哪个素材,如 @Image2);以及提示词或生成结果审核未通过、上游暂无可用容量。失败 不扣费,稍后重新创建任务即可。

视频 URL 有效期

videoUrl 为临时地址,有效期 24 小时,请及时下载或转存。

参考素材 ​

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

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

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

文生视频(无需 references)

json
{
  "model": "r/seedance-2.0-fast",
  "prompt": "一只橘猫在清晨的草地上奔跑,阳光透过树叶形成光斑,电影感真实摄影",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

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

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

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

json
{
  "model": "r/seedance-2.5",
  "prompt": "镜头从首帧自然过渡到尾帧,动作连贯,真实摄影质感",
  "input_type": "first_last_frame",
  "duration": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "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": "r/seedance-2.0",
  "prompt": "明亮鲜艳的广告片风格,主体是水果夹心饼干。草莓味参考 @Image1,开场构图参考 @Video1,运镜参考 @Video2,背景音乐参考 @Audio1。",
  "input_type": "reference",
  "duration": 15,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true,
  "return_last_frame": true,
  "references": [
    { "type": "image", "url": "https://example.com/strawberry.png", "role": "reference_image" },
    { "type": "video", "url": "https://example.com/open.mp4", "role": "reference_video" },
    { "type": "video", "url": "https://example.com/camera.mp4", "role": "reference_video" },
    { "type": "audio", "url": "https://example.com/bgm.mp3", "role": "reference_audio" }
  ]
}

该请求含视频参考,按「含视频参考」价格计费,计费秒数为两段参考视频时长(各段向上取整)之和 加 duration。

错误 ​

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

路由约束

本网关只接受 以 r/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,z/seedance 模型请改用 POST /api/v3/z/videos/generations/tasks,火山系(token 计费)模型请改用 POST /api/v3/contents/generations/tasks。

Copyright © 2026 星算云