Genarrative/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md

画板音乐生成入口设计

日期：2026-06-18

范围

本次只在 /editor/canvas 图片画布编辑器内新增底部 生成音乐 入口，用于生成完整游戏音效或游戏背景音乐。该入口属于画板生成类工具，不新增平台玩法入口、不进入作品发布链路，也不修改现有视觉小说音频生成开关。

入口与交互

1. 底部 AI 画布工具栏新增 生成音乐。
2. 点击 生成音乐 后先弹出页面级 fixed 选项框，选项为：
   • 生成游戏音效
   • 生成游戏背景音乐
3. 选择某一项后创建独立 generation-dialog 画布生成对象，并通过现有 placement 模型避让已有图层和占位。
4. 面板 UI 复用 生成角色形象 的紧凑结构：上方为字段区，底部为参数 / 模型 / 生成按钮区，不写规则说明类文案。音效参数按钮靠左下角，固定模型胶囊紧贴生成按钮；背景音乐同样在右下角显示固定模型胶囊并紧贴生成按钮。
5. 生成中隐藏设置面板，只保留画布中的音频生成占位；失败后恢复面板并展示短错误。

面板字段

生成游戏音效

• prompt：用户输入的音效提示词。前端与 BFF 对内仍使用 prompt，提交到 VectorEngine Vidu 时同时写入 prompt 与 sound 同值，兼容线上网关对 sound 字段的反序列化要求。
• model：固定默认 audio1.0，UI 以禁用态模型胶囊显示为 Vidu，位置紧贴生成按钮；暂不展示 Suno 文生音效模型入口。
• duration：Vidu 音频时长，UI 以一个无标题参数按钮展示当前秒数，点击后展开与视频时长一致的滑动条，范围 2-10 秒，步进 1 秒，默认 5 秒。
• 提交到 VectorEngine 时映射为 Vidu 文生音频字段：model: "audio1.0"、prompt、sound: prompt、duration、可选 seed。当前编辑器音效固定使用 Vidu audio1.0，不再走 Suno task: "sound" / metadata_params 文生音效契约。

生成游戏背景音乐

• gpt_description_prompt：用户输入的背景音乐提示词。
• make_instrumental：固定传 true，不在 UI 中展示为可改字段。
• 提交到 VectorEngine 时映射为 Suno 纯音乐模式字段：mv、gpt_description_prompt、make_instrumental: true。mv 后端固定使用默认 Suno 模型，UI 以禁用态模型胶囊显示 Suno。
• gpt_description_prompt 按 Apifox 契约限制 200 字，超出时由 BFF 返回参数错误。

画布数据

• 生成器继续保存到画布 layout JSON 的 itemType: "generation-dialog"，不新增表。
• 新增生成器模式：
  • audio-sound-effect
  • audio-background-music
• 新增结果图层媒体类型 mediaType="audio"。
• 新增素材类型：
  • assetKind="sound-effect"
  • assetKind="background-music"
• 音频结果以小型音频卡加入画布，卡片底部使用融入卡片的自定义播放器组件承载进度、时间和音量，播放 / 暂停只收口到卡片中央图标按钮；生成成功后同时保存为 OSS 私有对象、画布资源和账号级素材库素材，响应携带 objectKey / assetObjectId 供后续换签和复用。
• 从素材库拖放音效或背景音乐时，卡片中心必须落在鼠标松手对应的画布位置，不叠加点击添加素材时使用的级联错位量；音频卡除中央播放按钮、底部进度 / 音量控件、标签和信息按钮外，其余卡片区域都作为选择与拖拽热区。
• 普通素材上传入口首版支持图片、MP3 和 MP4；MP3 / MP4 先走 OSS 直传和 asset object confirm，再以素材库素材保存，其他音视频格式暂不开放。
• 音频结果卡片底部显示播放器辅助控件，不在卡片左下角或悬停左上角展示时长；提示词固定显示在卡片左上角。
• 音频结果卡片底部播放器辅助控件仅在鼠标悬停音频卡片时从下方滑入显示，移出后向下滑出收起。
• 音频卡片中央播放区按状态切换：未悬停且未播放时显示音效 / 背景音乐图标，悬停且未播放时显示播放按钮，播放中始终显示暂停按钮。
• generated 私有音频资源播放前必须通过 /api/assets/read-url 换签；画布卡片不得直接把 /generated-* 或 generated OSS 私有地址交给 <audio> 裸请求。
• 音频元数据弹窗使用 时长，不使用图片 / 视频的分辨率语义；音频生成占位不显示分辨率或时长角标。
• 音频图层右上角标签显示在信息按钮左侧，和其他素材卡右上角信息区保持一致。
• 元数据弹窗按音频显示 音频信息 / 音频类型 / 时长，生成输入快照只展示用户面板字段。
• 音频图层上方浮动工具栏只保留 改造 和 下载按钮。点击 改造 后打开对应的音效或背景音乐生成面板，不展示参考图组件；面板底部模型与参数位置和原生成入口一致，并允许继续修改后再次生成，新结果落在原音频旁边。

前端提交契约

前端新增两个 BFF client：

POST /api/editor/audios/sound-effects/generations
{
  prompt: string,
  model: "audio1.0",
  duration: number,
  priceMudPoints: 10
}

POST /api/editor/audios/background-music/generations
{
  gptDescriptionPrompt: string,
  makeInstrumental: true,
  priceMudPoints: 5
}

统一响应：

{
  ok: true,
  audioSrc: string,
  objectKey?: string | null,
  assetObjectId?: string | null,
  width: 420,
  height: 120,
  sourceType: "generated",
  prompt: string,
  actualPrompt?: string | null,
  model: string,
  provider: string,
  taskId: string,
  priceMudPoints: number,
  audioKind: "sound-effect" | "background-music",
  durationSeconds?: number | null
}

后端实现

• 在 shared-contracts/src/assets.rs 增加编辑器音频请求 / 响应 DTO。
• 在 platform-audio 增加编辑器专用 body builder 和 submit 函数：
  • 背景音乐 body 使用 mv、gpt_description_prompt、make_instrumental。
  • Suno 音乐接口路径固定为 /suno/submit/music；VECTOR_ENGINE_BASE_URL 即使配置为带 /v1 的图片接口根，也要在 platform-audio 中归一为根路径后再拼接，避免误请求 /v1/suno/submit/music。
  • 音效 body 使用 Vidu 文生音频契约：提交 /ent/v2/text2audio，请求体包含 model: "audio1.0"、prompt、sound: prompt、duration 和可选 seed；model 和 prompt 为文档必填，sound 用于兼容线上网关实际校验，prompt 最长 1500 字符，duration 按 Vidu 文档限制在 2-10 秒。
  • 编辑器音效轮询使用 Vidu 路径 /ent/v2/tasks/{taskId}/creations，不再使用 Suno /suno/fetch/{taskId}；Suno 文生音效 task: "sound" 暂不从编辑器入口暴露。
  • Suno 提交成功后的任务 ID 兼容与 wav clip 轮询逻辑只保留给背景音乐链路；/suno/fetch/{taskId} 返回 audiopipe.suno.ai/?item_id=... 时，该地址只作为 clip id 来源，不作为最终下载文件，后端继续调用 /suno/act/wav/{clipId} 获取稳定 wav URL，避免 worker 在不完整 chunked body 上卡满超时。
  • VectorEngine 音频响应的 code 需要兼容 "success"、"ok"、"0"、"200" 以及数字 0 / 200；HTTP 非 2xx 时后端错误信息应透出安全的上游状态和短响应摘要，避免前端只显示笼统提交失败。
• 在 api-server 增加编辑器音频 BFF：
  • /api/editor/audios/sound-effects/generations
  • /api/editor/audios/background-music/generations
• BFF 复用现有 vector_engine_audio_generation 的任务轮询、下载、OSS 持久化和计费包装；音效 10 泥点，背景音乐 5 泥点。
• 生成音频持久化后返回 OSS objectKey 与 assetObjectId；前端保存素材库时继续使用 audioSrc 作为兼容路径，并把 OSS 身份写入素材记录。

验收

• 底部工具栏显示 生成音乐。
• 点击 生成音乐 只出现选项框，不立刻创建占位。
• 点击 生成游戏音效 后出现音效面板，文本字段为 prompt；底部左侧只有一个无标题时长参数按钮，右侧为固定 Vidu 模型胶囊和生成按钮。
• 音效时长使用滑动条选择 2-10 秒，步进 1 秒，默认 5 秒，提交到 BFF 的字段为 duration。
• 音效面板模型显示 Vidu，提交 model: "audio1.0"；后端转发到 Vidu 时同时携带 prompt 和 sound；不显示 Suno 文生音效模型或 Suno 音效入口。
• 点击 生成游戏背景音乐 后出现背景音乐面板，字段为 gpt_description_prompt，右侧固定显示 Suno 模型胶囊，不展示 make_instrumental。
• 音效提交到 /api/editor/audios/sound-effects/generations，背景音乐提交到 /api/editor/audios/background-music/generations。
• 成功后画布新增音频卡，能通过卡片中央播放按钮播放，底部进度、时间和音量控件可操作。
• 从素材库拖放音效或背景音乐后，音频卡中心位于鼠标松手位置；拖动卡片任意非播放 / 播放器控件区域都能移动图层，点击中央播放按钮只播放或暂停，不启动拖拽。
• 成功后音频素材自动出现在账号级素材库；从素材库再次添加到画布时仍恢复为 mediaType="audio" 音频图层。
• 普通素材上传 MP3 / MP4 会写入 OSS 并进入素材库；MP3 添加到画布为音频图层，MP4 添加到画布为视频图层。
• 成功后的音频卡展示提示词；卡片中央按未悬停图标、悬停播放、播放中暂停切换，不在底部重复显示播放 / 暂停按钮，播放器辅助控件直接融入卡片底部。
• 鼠标未悬停音频卡时底部播放器辅助控件不可见，悬停时从底部滑动显现；提示词位于卡片左上角。
• 音频卡片、悬停角标和待生成占位不显示时长；信息弹窗显示时长。
• 音频素材浮动工具栏只显示 改造 与 下载按钮，改造 复用对应生成面板且没有参考图组件。
• 私有 generated 音频能先换签再预览播放，不出现播放条一直为 0:00 的裸路径失败状态。
• 刷新后 layout 能恢复音频生成器和音频图层。