Genarrative/docs/technical/VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md

VectorEngine 音频生成接入方案 2026-05-08

1. 范围

本方案用于把 VectorEngine / Apifox 文档中的 Suno 文生背景音乐与 Vidu 文生音效接入视觉小说结果页。

本次只接入 visual-novel 现有场景资产槽位，不新增独立音频系统、不新增 SpacetimeDB 表、不把供应商密钥下发到前端。

2. 参考接口

2.1 Suno 文生背景音乐

参考文档：

• https://vectorengine.apifox.cn/api-349239190
• https://vectorengine.apifox.cn/api-349239199

接口：

POST /suno/submit/music
GET /suno/fetch/{task_id}

提交请求头：

Content-Type: application/json
Accept: application/json
Authorization: Bearer {VECTOR_ENGINE_API_KEY}

自定义模式请求体：

{
  "prompt": "音乐描述或歌词",
  "mv": "chirp-v4",
  "title": "曲名",
  "tags": "风格标签",
  "continue_at": 120,
  "continue_clip_id": "",
  "task": ""
}

首版只使用 prompt、mv、title、tags。返回体按 code = success 且 data 为供应商任务 ID 处理。

2.2 Vidu 文生音效

参考文档：

• https://vectorengine.apifox.cn/api-417728889
• https://vectorengine.apifox.cn/api-417728893

接口：

POST /ent/v2/text2audio
GET /ent/v2/tasks/{id}/creations

提交请求体：

{
  "model": "audio1.0",
  "prompt": "雨滴落在窗户上的声音，伴随着轻柔的雷声",
  "duration": 5,
  "seed": 0
}

约束：

• prompt 最长 1500 字符。
• duration 范围为 2 到 10 秒，默认 5 秒。
• model 首版固定为 audio1.0。

3. 环境变量

VECTOR_ENGINE_BASE_URL=
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000

说明：

1. VECTOR_ENGINE_BASE_URL 只保存供应商代理 API 基础地址，不在代码中写死私有网关。
2. VECTOR_ENGINE_API_KEY 只能进入本地或生产私密环境文件，不提交到 Git。
3. 缺少任一必配项时，后端返回 503 SERVICE_UNAVAILABLE，前端沿用现有错误展示。

4. 后端路由

视觉小说创作链新增 4 个鉴权路由：

方法	路由	用途
POST	/api/creation/visual-novel/audio/background-music	提交 Suno 背景音乐任务
POST	/api/creation/visual-novel/audio/background-music/{task_id}/asset	查询 Suno 任务，完成后下载并写入平台资产
POST	/api/creation/visual-novel/audio/sound-effect	提交 Vidu 音效任务
POST	/api/creation/visual-novel/audio/sound-effect/{task_id}/asset	查询 Vidu 任务，完成后下载并写入平台资产

生成资产回包写入既有视觉小说字段：

• Suno 背景音乐：VisualNovelSceneDraft.musicSrc
• Vidu 文生音效：VisualNovelSceneDraft.ambientSoundSrc

5. 资产落点

音频文件由后端下载后通过 OssClient::put_object 写入平台 OSS，并确认 asset_object 与 asset_entity_binding。

对象规划：

类型	assetKind	entityKind	slot	旧路径前缀
背景音乐	visual_novel_music	visual_novel_scene	music	generated-custom-world-scenes
场景音效	visual_novel_ambient_sound	visual_novel_scene	ambient_sound	generated-custom-world-scenes

确认后的 audioSrc 使用 OSS 返回的 legacy public path，继续由前端 resolveAssetReadUrl 换签播放。

6. 前端交互

视觉小说场景编辑弹层新增两类音频能力：

1. 音乐 保留上传能力，并新增 Suno 生成按钮。
2. 音效 使用 ambientSoundSrc，支持上传和 Vidu 生成。

交互要求：

1. 生成参数放在独立弹层中，不在当前场景面板下方展开。
2. 弹层只保留必要字段、提交、关闭和状态反馈，不展示供应商规则说明。
3. 任务提交成功后前端轮询资产接口；若供应商仍在处理，保持弹层状态。
4. 资产生成完成后自动写回当前场景字段。

7. 验收

建议执行：

npm run check:encoding
npm run typecheck

cd server-rs
cargo test -p shared-contracts visual_novel
cargo check -p api-server

涉及真实 API smoke 时：

1. 只在本地私密环境设置 VECTOR_ENGINE_API_KEY。
2. 使用 npm run api-server 重启后端。
3. 确认 /healthz。
4. 在视觉小说结果页提交背景音乐或音效生成，生成完成后确认场景音频槽位可播放。