火山方舟（线路4） Seedance 模型接入指南

火山方舟（线路4）由渠道特殊优化，接入与官方Seedance不同，需要单独兼容接入

概览

OneLinkAI 提供火山方舟（线路4）的 Seedance 视频生成与素材库能力。为降低接入成本，火山方舟（线路4）完全复用火山方舟兼容协议：客户端始终以火山方舟的接口路径、请求体、鉴权方式调用，由 OneLinkAI 网关在内部把请求翻译成腾讯云 VOD 云 API，响应再翻译回火山格式。

也就是说，如果你已经接入过火山方舟兼容接口，切换到火山方舟（线路4）通常无需改动客户端代码，只需在 API Key 上把「只用供应商」设为火山方舟（线路4）即可。

本文仅说明火山方舟（线路4）与火山官方协议行为不一致的地方。协议本身、路径规则、鉴权方式与火山方舟接入指南一致，不再重复，请先阅读《火山方舟模型接入指南》。

适用线路：供应商名称可能按运营命名规则显示（例如「火山方舟（线路N）」），实际底层为腾讯云 VOD。以 API Key「只用供应商」中绑定的线路为准。

鉴权与路径（与火山一致）

鉴权：Authorization: Bearer <ApiKey>

视频生成：POST /volc/api/v3/contents/generations/tasks、GET /volc/api/v3/contents/generations/tasks/{id}

素材库 / 真人认证：/volc/openapi?Action=<火山 Action>

这些路径与火山方舟兼容接口完全相同，客户端不需要区分线路。

与火山官方的不同点

1. 计费方式：按秒计费（火山为按 Token）

火山原生 Seedance 视频生成按 Token 结算；火山方舟（线路4）按视频时长（秒）结算。

计费秒数取任务结果里的 duration 字段（实际生成的视频时长）。

单价按「画质 + 视频输入类型」两个维度查价：

画质档位：480P / 720P / 1080P（720p 与 768p 归入 720P 档）。

视频输入类型：with_video（参考视频生视频）/ without_video（文生视频、图生视频）。

消费记录里 tokenInput / tokenOutput / tokenTotal 会显示为 0，videoOutput 为 null，这是按秒计费的正常形态，费用来自时长而非 Token，不代表未扣费。实际费用见 sell / cost 字段。

2. 分辨率为必填（火山可选）

火山原生创建视频任务时 resolution 可以不传（走模型默认）；火山方舟（线路4）要求 resolution 必填，且取值需落在该模型已配置的画质档位内。

不传或传入不受支持的分辨率时，上游会返回类似 计费参数"分辨率"的输入值不受支持，请输入以下支持的参数值：「1080p」「4k」 的错误。

请在创建任务时显式传 resolution，取值示例："480p" / "720p" / "1080p"。具体可用档位以该模型实际配置为准。

3. 真人素材：活体认证流程（腾讯独有）

Seedance 系列不支持直接上传含真人人脸的参考图 / 参考视频。火山与腾讯都需要先完成真人活体认证拿到「真人素材组」，但火山方舟（线路4）的认证由腾讯云 VOD 提供，流程如下（接口仍是火山式 Action，由网关翻译）：

调 CreateVisualValidateSession（传 CallbackURL）→ 返回 H5Link + BytedToken。

真人用浏览器打开 H5Link 完成活体认证。

认证完成后浏览器自动重定向回你传入的 CallbackURL（带 groupId），与火山原生「传 CallbackURL → 认证完跳回」体验一致。

也可不传 CallbackURL，改为轮询 GetVisualValidateResult（传 BytedToken）拿 GroupId。

用拿到的 GroupId 调 CreateAsset（传 IsRealPerson: "True"）创建真人素材。

认证页为上游提供的 H5 页面，页面品牌样式由上游决定，OneLinkAI 不改写页面内容。

4. 素材库接口：部分 Action 暂不支持

火山方舟（线路4）素材库复用火山式 /volc/openapi?Action=xxx，当前支持的 Action 及其腾讯侧行为：

火山 Action	火山方舟（线路4）支持	说明
CreateAsset	✔️	创建素材。`URL` 与 `GroupId` 必填；真人素材传 `IsRealPerson:"True"`
GetAsset	✔️	查询素材
UpdateAsset	✔️	仅支持改素材名
DeleteAsset	✔️	按素材 Id 删除
GetAssetGroup	✔️	查询素材组
UpdateAssetGroup	✔️	改组名 / 组描述
DeleteAssetGroup	✔️	按组 Id 删除整组
CreateVisualValidateSession	✔️	发起真人活体认证
GetVisualValidateResult	✔️	查询活体认证结果
CreateAssetGroup	❌	火山方舟（线路4）暂不支持单独建组，上游会返回错误
ListAssets	❌	暂不支持列举素材
ListAssetGroups	❌	暂不支持列举素材组

与火山的关键差异：

不支持惰性建组：火山可在创建素材时自动建组，火山方舟（线路4）要求 GroupId 已存在，CreateAsset 必须传已有的 GroupId。

列表类接口不可用：ListAssets / ListAssetGroups / CreateAssetGroup 当前走原样透传，腾讯不识别会返回错误。请在业务侧自行维护素材 Id / 组 Id。

5. 素材字段命名（已自动兼容）

火山素材库统一用 Id（素材 asset-xxx、组 group-xxx），腾讯用 AssetId / GroupId。网关已做双向翻译，你按火山协议传 Id 即可，响应也会翻回火山的 Id / URL / Name / Status 等字段，无需关心腾讯侧命名。

素材状态：腾讯的 DONE / SUCCESS 会翻译成火山的 Active，失败态翻成 Failed，其余为 Processing。

GetAsset 返回的 Result.URL 为腾讯返回的真实公网地址，可直接用于视频生成的素材引用。

6. 图片生成

火山方舟（线路4）为视频 / 素材库供应商。图片生成接口（/volc/api/v3/images/generations）是否可用取决于该线路实际部署的模型，请以该 API Key 实际支持的模型为准，不要默认与火山线路一致。

素材库线路一致性（与火山相同的约束）

各线路素材库相互独立，无法跨线路使用或迁移。使用火山方舟（线路4）素材库时，模型调用线路与素材库线路必须一致：在 API Key 编辑页设置「只用供应商」为火山方舟（线路4）即可自动绑定对应素材库。

素材库一旦绑定，建议不要再更换供应商线路，否则原线路素材无法在新线路使用。

若 API Key 未设置「只用供应商」，系统默认走火山线路一及其素材库，火山方舟（线路4）的翻译层不会生效。

使用建议

已接入火山兼容接口的业务，切换火山方舟（线路4）只需改 API Key 的「只用供应商」，客户端代码通常无需改动。

创建视频任务务必显式传 resolution，避免因必填校验失败。

账单核对：火山方舟（线路4）看 sell / cost 与任务 duration，Token 列为 0 属正常。

真人素材走「活体认证 → 拿 GroupId → CreateAsset(IsRealPerson:True)」，建议先传 CallbackURL 打通浏览器重定向闭环。

素材组需提前创建好并记录 GroupId（火山方舟（线路4）不支持建组 / 列表接口）。

具体字段约束、错误码请以火山方舟官方文档 + 该模型实际配置为准；如后续补齐腾讯等价接口，本文档会同步更新。

Vega（线路1）接入指南

火山方舟（线路4） Seedance 模型接入指南#

概览#

鉴权与路径（与火山一致）#

与火山官方的不同点#

1. 计费方式：按秒计费（火山为按 Token）#

2. 分辨率为必填（火山可选）#

3. 真人素材：活体认证流程（腾讯独有）#

4. 素材库接口：部分 Action 暂不支持#

5. 素材字段命名（已自动兼容）#

6. 图片生成#

素材库线路一致性（与火山相同的约束）#

使用建议#