星算云 开发者文档

主题

Seedance(火山兼容) ​

星算云 视频网关挂载于 /api/v3,与火山引擎方舟 API 1:1 兼容。鉴权用 Authorization: Bearer xsk_...。

真人素材管理 ​

Seedance 真人视频生成需要前置的「真人人像素材」。通过 H5 活体认证创建真人素材组（GroupId），再上传照片/视频作为素材，最后在创建任务时引用。

①创建认证会话 → 用户在 H5 完成活体 → ②换取 GroupId → 创建视频任务

创建认证会话 ​

POST /api/v3/liveness/sessions

bash
curl "$API_BASE/api/v3/liveness/sessions" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{"CallbackURL": "https://your-app.com/callback"}'
json
{
  "ResponseMetadata": {"RequestId": "...", "Action": "CreateVisualValidateSession"},
  "Result": {
    "BytedToken": "20260716...",
    "H5Link": "https://ark.volcengine.com/...",
    "CallbackURL": "https://your-app.com/callback"
  }
}

引导用户在浏览器打开 H5Link 完成活体认证。BytedToken 用于下一步换取 GroupId（30 分钟有效）。

换取 GroupId ​

GET /api/v3/liveness/sessions/{byted_token}

bash
curl "$API_BASE/api/v3/liveness/sessions/$BYTED_TOKEN" \
  -H "Authorization: Bearer $XSK_KEY"
json
{
  "ResponseMetadata": {"RequestId": "..."},
  "Result": {
    "GroupId": "group-20260716-livenessface-xxx"
  }
}

GroupId 是真人素材组 ID，用于上传素材和创建视频任务。

素材组 ​

创建素材组 ​

POST /api/v3/asset-groups

可选

真人素材组由活体认证自动产生（②），一般不需要手动创建。此接口用于创建 AIGC 虚拟人像素材组。

bash
curl "$API_BASE/api/v3/asset-groups" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{"Name": "my-group", "Description": "虚拟人像素材"}'

查询素材组 ​

GET /api/v3/asset-groups/{group_id}

bash
curl "$API_BASE/api/v3/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $XSK_KEY"

素材 ​

上传素材 ​

POST /api/v3/assets

将真人照片/视频上传到 GroupId。

bash
curl "$API_BASE/api/v3/assets" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "GroupId": "group-20260716-livenessface-xxx",
    "URL": "https://example.com/photo.jpg",
    "AssetType": "Image",
    "Name": "我的照片"
  }'
json
{
  "ResponseMetadata": {"RequestId": "..."},
  "Result": {
    "Id": "asset-20260716-xxx",
    "Status": "Active",
    "URL": "https://ark-media-asset...",
    "GroupId": "group-...",
    "AssetType": "Image"
  }
}

Status 为 Active 表示素材可用；Failed 表示处理失败；Processing 表示仍在处理（超时未完成）。

查询素材 ​

GET /api/v3/assets/{asset_id}

bash
curl "$API_BASE/api/v3/assets/$ASSET_ID" \
  -H "Authorization: Bearer $XSK_KEY"

素材 URL 有效期

素材的 URL 为火山签发的临时链接，有效期 12 小时。过期后重新查询获取新 URL。

创建任务 ​

POST /api/v3/contents/generations/tasks

bash
API_BASE=https://xingsuan.cloud
curl "$API_BASE/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "全程使用视频1的第一视角构图,全程使用音频1作为背景音乐。第一人称视角果茶宣传广告,seedance牌「苹苹安安」苹果果茶限定款;首帧为图片1,你的手摘下一颗带晨露的阿克苏红苹果;尾帧定格为图片2。背景声音统一为女生音色。"},
      {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"}, "role": "reference_audio"}
    ]
  }'
python
import requests

API_BASE = "https://xingsuan.cloud"
resp = requests.post(
    f"{API_BASE}/api/v3/contents/generations/tasks",
    headers={"Authorization": f"Bearer {XSK_KEY}"},
    json={
        "model": "doubao-seedance-2-0-260128",
        "content": [
            {"type": "text", "text": "全程使用视频1的第一视角构图,全程使用音频1作为背景音乐。第一人称视角果茶宣传广告,seedance牌「苹苹安安」苹果果茶限定款;首帧为图片1,你的手摘下一颗带晨露的阿克苏红苹果;尾帧定格为图片2。背景声音统一为女生音色。"},
            {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "reference_image"},
            {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"}, "role": "reference_image"},
            {"type": "video_url", "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"}, "role": "reference_video"},
            {"type": "audio_url", "audio_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"}, "role": "reference_audio"},
        ],
    },
)
task = resp.json()
print(task["id"])  # 任务 ID,用于查询

火山系模型创建成功(HTTP 200)返回星算云任务 id,用于后续查询。

json
{
  "id": "task_WVTVN5hzFLSOoEtpDXt2TrYQ48g3sTiH"
}

请求参数

参数位置必填说明
AuthorizationHeader是Bearer xsk_...
modelBody是模型标识,如 doubao-seedance-1-0-pro-250528 / doubao-seedance-2-0-260128
contentBody是生成输入数组,元素 type 支持 text / image_url / video_url / audio_url
content[].roleBody条件图片 first_frame / last_frame / reference_image;视频 reference_video;音频 reference_audio
watermarkBody否是否加水印,默认 false
resolutionBody否480p / 720p / 1080p / 4k,默认 720p
ratioBody否16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive,默认 adaptive
durationBody否时长秒 [4,15] 或 -1(模型自选),默认 5
generate_audioBody否是否生成同步音频,默认 true
return_last_frameBody否是否返回尾帧图,默认 false
execution_expires_afterBody否任务超时秒 [3600,259200],默认 172800

生成参数写法

resolution / ratio / duration / watermark 可以作为顶层字段直传(强校验),也可以写在 content[].text 末尾以 --resolution 1080p --ratio 16:9 形式(弱校验)。两种方式均为官方支持。

简写模式

文生视频可只传 prompt + images(首帧),平台自动构造 content 数组。

查询任务 ​

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

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

响应包含任务状态与生成结果(视频 URL),格式与火山官方一致。建议用轮询方式查询直到任务完成。

status 取值

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

响应示例

json
{
  "id": "task_xxxxxx",
  "model": "seedance-2.0-mini",
  "status": "succeeded",
  "created_at": 1784216398,
  "updated_at": 1784216551,
  "content": {
    "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxxxxx.mp4?..."
  },
  "usage": {
    "completion_tokens": 100858,
    "total_tokens": 100858
  }
}

视频 URL 有效期

content.video_url 为临时链接,有效期 24 小时,请及时下载或转存。

按秒模型官方格式入口(k/c/s/z) ​

k/seedance、c/seedance、s/seedance、z/seedance 系按秒计费模型也可以直接走本端点(Seedance 官方格式兼容入口),无需改用各自的统一格式端点。平台按 model 前缀自动分流,查询接口同样按任务自动路由。

项火山系模型k/c/s/z 按秒模型(官方格式)
创建响应HTTP 200,{id}HTTP 202,{id, model, status, created_at, updated_at}
计费方式token(usage.completion_tokens)按秒,计费秒数 = 查询响应回报的 billedSeconds(缺失时按请求 duration 兜底)
usage 字段成功后含 completion_tokens恒 null(不作为计费依据)
bash
curl "$API_BASE/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "c/seedance-2.0",
    "content": [{"type": "text", "text": "清晨山路上一辆黑色电动车驶过,真实电影摄影风格"}],
    "duration": 8,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'
# → HTTP 202  {"id": "task_xxx", "model": "c/seedance-2.0", "status": "queued", ...}

官方格式分支的约束

  • duration 必填:整数 [4,30],不支持 -1(智能时长)——查询响应未回报 billedSeconds 时按它兜底结算。部分模型实际上限更低(如 2.0 系 [4,15]),越界由上游 400 透传。
  • content 必填为数组;不支持本页的 prompt + images 简写。
  • 仅透传 model / content / duration / resolution / ratio / generate_audio / watermark;return_last_frame、execution_expires_after、seed 等火山字段会被忽略。
  • 单价与各模型统一格式端点一致,按「分辨率 × 是否含视频参考(content 含 video_url 项)」取档,价目见 k、c、s、z 计费表;任务失败不计费。
  • 上游错误为 OpenAI 风格 {"error": {"message", "type", "param", "code"}} 原样透传(与火山风格信封不同)。

含视频参考的计费口径

官方格式查询响应会回报 billedSeconds(上游实际结算秒数):c/k 含视频参考时为「参考视频总时长 + 输出时长」,z/s 为输出时长——与各模型统一格式端点口径一致(均信上游回报)。仅当响应未回报该字段时,平台才按请求 duration(输出时长)兜底,该场景下 c/k 含视频参考会低于上游结算口径。

错误 ​

错误信封为火山风格({"error":{"code":"<string>","message":...}}),code 是字符串。上游超时 → 504;连接错误 → 502;若上游已返回火山错误体则原样透传。详见 错误码。

路由约束

本网关按模型自动分流:火山系(token 计费)模型与 k/seedance / c/seedance / s/seedance / z/seedance 按秒模型(官方格式,见上节)直接调用即可。k/c/s/z 按秒模型也可改走各自统一格式端点:POST /api/v3/videos/generations/tasks(k)、POST /api/v3/c/videos/generations/tasks(c)、POST /api/v3/s/videos/generations/tasks(s)、POST /api/v3/z/videos/generations/tasks(z)。

Copyright © 2026 星算云