# 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`

接口：

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

提交请求头：

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

自定义模式请求体：

```json
{
  "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`

接口：

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

提交请求体：

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

约束：

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

## 3. 环境变量

```text
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. 验收

建议执行：

```bash
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. 在视觉小说结果页提交背景音乐或音效生成，生成完成后确认场景音频槽位可播放。