6.6 KiB

Surový Blame Historie

天翼云 Seedance 渠道设计文档

日期: 2026-07-08 状态: 待用户审阅方案: A - 新增独立渠道类型 DoubaoVideoCompatibleTianyiYun

1. 背景与目标

天翼云 Seedance 渠道提供与 Doubao/Seedance 类似的异步视频生成能力。截图中的上游 API 使用：

提交任务: POST https://ai.ctaigw.cn/v1/contents/generations/tasks
查询任务: GET https://ai.ctaigw.cn/v1/contents/generations/tasks/{task_id}
鉴权: Authorization: Bearer {api_key}
模型:
- cdance2.0-0611
- cdance2.0-fast-0611

目标是在 new-api 中新增独立渠道类型，复用现有 Seedance/Doubao 对外入口与任务链路，不把天翼云行为混入火山 Doubao 或 Aiping 渠道。

2. 范围

2.1 包含

新增 channel type: DoubaoVideoCompatibleTianyiYun
默认 base URL: https://ai.ctaigw.cn
复用现有 new-api 侧 Seedance/Doubao 入口:
- POST /api/v3/contents/generations/tasks
- GET /api/v3/contents/generations/tasks/{task_id}
新增任务适配器，转发到天翼云上游:
- POST /v1/contents/generations/tasks
- GET /v1/contents/generations/tasks/{task_id}
支持模型列表:
- cdance2.0-0611
- cdance2.0-fast-0611
前端渠道类型枚举增加新渠道，管理员可在渠道管理中创建该渠道。
实现后使用用户提供的 key 发起一次真实最短任务验证。

2.2 不包含

不新增用户侧公开路由 /v1/contents/generations/tasks
不修改现有火山 Doubao 官方渠道语义
不修改现有 DoubaoVideoCompatibleAiping 渠道语义
不在代码、文档、日志或测试 fixture 中保存用户提供的真实 API key

3. 总体设计

新增渠道保持独立：

用户请求
  -> POST /api/v3/contents/generations/tasks
  -> 现有 token auth / distribute / task relay
  -> ChannelTypeDoubaoVideoCompatibleTianyiYun
  -> doubao_tianyiyun TaskAdaptor
  -> POST https://ai.ctaigw.cn/v1/contents/generations/tasks

查询任务：

用户请求
  -> GET /api/v3/contents/generations/tasks/{public_task_id}
  -> 本地任务表定位 upstream task id
  -> doubao_tianyiyun FetchTask
  -> GET https://ai.ctaigw.cn/v1/contents/generations/tasks/{upstream_task_id}

这样做的理由：

渠道类型边界清楚，排查日志、计费、状态映射时不会混淆 Aiping 与天翼云。
对外入口复用已有 Seedance/Doubao 任务接口，客户端不需要学习新的 new-api 路由。
上游路径差异只封装在新适配器中，后续如果天翼云返回结构变化，影响范围较小。

4. 模型与请求体

用户侧模型名直接使用天翼云模型 ID：

cdance2.0-0611
cdance2.0-fast-0611

管理员仍可使用现有模型映射能力，把内部展示模型映射到天翼云模型 ID。

请求体字段优先沿用现有 Doubao/Aiping Seedance 结构：

model
content
ratio
duration
watermark
其它已由 Doubao/Aiping 适配器支持的 Seedance 字段，在不改变语义的情况下尽量透传。

适配器不额外把 duration 改成 seconds，因为截图示例明确使用 duration。

5. 状态与响应处理

提交任务时，上游返回的 task id 存入本地任务记录；返回给用户的仍是 new-api public task id，避免暴露不同上游 ID 体系。

查询任务时，状态映射采用现有异步任务语义：

上游状态	new-api 状态
`pending`, `queued`	queued
`processing`, `running`	in_progress
`succeeded`, `success`	success
`failed`, `expired`, `cancelled`	failure
其它未知状态	in_progress

成功时从上游响应中提取视频 URL。优先兼容现有字段 content.video_url；如果真实验证发现字段不同，再按真实返回补充解析。

6. 渠道测试与真实验证

普通渠道“测试”按钮不适合直接测试异步视频渠道。该新渠道应与现有 Doubao/Vidu 类似，避免用聊天补全接口做快速测试。

实现后的验证分两层：

自动化测试
- 单元测试覆盖上游提交 URL、查询 URL、Authorization header、模型列表。
- mock 上游测试覆盖提交响应 task id 与查询状态解析。
- 回归测试确认现有 Doubao/Aiping 测试不受影响。
真实上游验证
- 使用用户本轮提供的 API key 作为运行时输入，不写入仓库。
- 发起一次最短 5 秒任务，使用 cdance2.0-0611 或 cdance2.0-fast-0611。
- 记录状态码、public task id、upstream task id、查询状态和必要错误信息。
- 输出中不回显 API key。

7. 需要修改的模块

预期实现会触及：

constant/channel.go
- 在 ChannelTypeDummy 前新增渠道类型。
- 同步 ChannelBaseURLs 与 ChannelTypeNames。
relay/channel/task/doubao_tianyiyun/
- 新增 constants.go
- 新增 adaptor.go
- 新增测试文件。
relay/relay_adaptor.go
- 注册新 task adaptor。
common/api_type.go
- 将新渠道映射到合适的 API type，建议沿用 VolcEngine/Doubao 视频相关路径。
common/endpoint_type.go
- 新渠道支持 EndpointTypeDoubaoVideo。
controller/channel-test.go
- 将新异步视频渠道加入不支持普通快速测试的列表。
web/src/constants/channel.constants.js
- 增加新渠道枚举，方便后台创建渠道。

根据实现中发现的实际依赖，可能还需要补充与模型能力、计费矩阵相关的白名单，但应保持最小改动。

8. 风险与约束

ChannelBaseURLs 是按 channel type 索引的数组，新增类型必须同步维护索引，否则会造成渠道默认 base URL 错位。
当前工作区已有其它未提交改动，实现时必须只修改本设计相关文件，不回退用户或其它任务的改动。
真实验证会消耗上游额度；只做一次最短任务验证，除非用户要求重复验证。
如果天翼云真实返回结构与截图示例不一致，应以真实响应为准补充解析，但不要扩大到无关功能。

9. 验收标准

管理后台能选择并创建 DoubaoVideoCompatibleTianyiYun 渠道。
渠道默认 base URL 为 https://ai.ctaigw.cn。
模型列表包含 cdance2.0-0611 与 cdance2.0-fast-0611。
经由现有 /api/v3/contents/generations/tasks 提交时，上游请求落到 /v1/contents/generations/tasks。
查询任务时，上游请求落到 /v1/contents/generations/tasks/{task_id}。
单元测试和相关回归测试通过。
使用真实 key 完成一次任务提交验证，并报告 task id 或明确的上游错误。

6.6 KiB Surový Blame Historie