星算云 开发者文档

主题

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

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

与 Seedance(火山兼容)、c/seedance(按秒计费)、s/seedance(按秒计费)、z/seedance(按秒计费) 区别:本网关只接 以 k/seedance 开头且按秒计费 的模型;火山系(token 计费)模型请走 POST /api/v3/contents/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/videos/generations/tasks
查询任务GET /api/v3/videos/generations/tasks/{task_id}
Content-Typeapplication/json
鉴权 HeaderAuthorization: Bearer xsk_...(平台 API Key)

API Key 安全

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

官方格式入口(可选)

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

模型 ​

模型代码档位分辨率适用场景
k/seedance-2.0-miniMini480p、720p低成本生成
k/seedance-2.0-fastFast480p、720p快速生成
k/seedance-2.0Pro480p、720p、1080p、4k高质量和 4K

k/ 前缀用于固定选择 K 渠道。请求体中的 mode 不用于切换档位,平台以 model 为准。

计费 ​

按「实际生成视频时长(秒)× 分辨率·输入类型单价」计费,单位元/秒,以平台模型配置价格与 API Key 折扣为准,从账户钱包实时扣减。任务失败不收取费用。

档位分辨率无参考视频含参考视频
Mini480p0.2300000.265000
Mini720p0.5000000.565000
Fast480p0.3700000.410000
Fast720p0.8000000.890000
Pro480p0.4600000.525000
Pro720p0.9900001.125000
Pro1080p2.4700002.820000
Pro4k5.0500005.830000

只有 videos 非空时使用「含参考视频」价格;仅使用图片或音频参考时不切换。使用参考视频时计费秒数可能大于生成时长;请求体 duration 仅作审计、可不传。

创建任务 ​

POST /api/v3/videos/generations/tasks

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

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

请求参数

参数位置必填说明
AuthorizationHeader是Bearer xsk_...
modelBody是k/seedance-2.0-mini / k/seedance-2.0-fast / k/seedance-2.0
promptBody条件文本提示词;未提供图片/视频参考时必填
imagesBody否图片参考数组,最多 9 张
videosBody否视频参考数组,最多 3 个(每个原始时长 ≥ 2 秒)
audiosBody否音频参考数组,最多 3 段
resolutionBody否480p / 720p;Pro 额外 1080p / 4k,默认 720p
ratioBody否16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive,默认 adaptive
durationBody否生成时长秒 [4,15](可不传)
generate_audioBody否是否生成同步音频,默认 true
watermarkBody否是否加水印,默认 false
seedBody否随机种子
return_last_frameBody否是否返回尾帧,默认 false
toolsBody否当前支持 [{"type":"web_search"}]
execution_expires_afterBody否任务过期秒 [3600,259200],默认 172800
bitrate_modeBody否standard / high,默认 standard
input_typeBody否reference / first_last_frame,默认 reference
generation_typeBody否当前传 video

prompt、images、videos 至少提供一项。images / videos / audios 元素为 {url, role} 对象,URL 须为公网可直接访问的 HTTP(S) 地址。

创建响应 ​

创建成功(HTTP 200)返回上游原生信封,code == 0:

json
{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "task_09e650d163219bfd056acdf0"
  },
  "trace_id": "trace_xxx"
}

保存 data.task_id,后续用它查询任务。

查询任务 ​

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

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

响应为上游原生信封,data.status 表示任务状态。建议每 5~10 秒轮询一次,succeeded 与 failed 为终态。

status 取值

status含义是否终态
running处理中否
succeeded成功,data.video_url 为视频地址是
failed失败,data.error 含原因是

运行中

json
{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "task_09e650d163219bfd056acdf0",
    "status": "running",
    "video_url": null,
    "last_frame_url": null,
    "error": null
  },
  "trace_id": "trace_xxx"
}

成功

json
{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "task_09e650d163219bfd056acdf0",
    "status": "succeeded",
    "video_url": "https://example.com/generated-video.mp4",
    "duration": 5,
    "usage": { "completion_tokens": 40594, "total_tokens": 40594 },
    "framespersecond": "24",
    "last_frame_url": null,
    "error": null
  },
  "trace_id": "trace_xxx"
}

失败

json
{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "task_09e650d163219bfd056acdf0",
    "status": "failed",
    "video_url": null,
    "last_frame_url": null,
    "error": { "code": null, "message": "task failed" }
  },
  "trace_id": "trace_xxx"
}

视频 URL 有效期

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

参考素材示例 ​

图片参考

json
{
  "model": "k/seedance-2.0",
  "prompt": "保持人物外观,让人物在海边自然回头并微笑,真实电影镜头",
  "images": [{"url": "https://example.com/person.png", "role": "reference_image"}],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 6
}

首尾帧(input_type: first_last_frame,需一张 first_frame + 一张 last_frame)

json
{
  "model": "k/seedance-2.0-fast",
  "prompt": "镜头从首帧自然过渡到尾帧,动作连贯,真实摄影质感",
  "input_type": "first_last_frame",
  "images": [
    {"url": "https://example.com/first.jpg", "role": "first_frame"},
    {"url": "https://example.com/last.jpg", "role": "last_frame"}
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

视频与音频参考(仅 videos 非空时用「含参考视频」价)

json
{
  "model": "k/seedance-2.0",
  "prompt": "参考视频中的动作节奏和镜头运动,生成城市夜景跑酷镜头",
  "videos": [{"url": "https://example.com/motion.mp4", "role": "reference_video"}],
  "audios": [{"url": "https://example.com/music.wav", "role": "reference_audio"}],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 6
}

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

错误 ​

  • 上游成功/失败响应:原样透传上游信封 {code, message, data, trace_id}(code == 0 即业务成功;非 0 为上游逻辑错误,HTTP 仍为 200)。
  • 平台侧错误(鉴权失败 / 模型不存在 / 非 k/seedance 按秒模型 / 钱包余额不足等):统一为火山风格信封 {"error":{"code":"<string>","message":...}}。上游超时 → 504;连接错误 → 502。详见 错误码。

路由约束

本网关只接受 以 k/seedance 开头且按秒计费 的模型;若传入非 k/seedance 模型会返回 400 invalid_request,请改用 POST /api/v3/contents/generations/tasks。

Copyright © 2026 星算云