AI 音乐创作
AI 音乐，基于 LLM 大模型，实现使用文本（描述、歌词）生成歌曲的功能。目前接入的是：
- Suno AI 的 Suno 模型：通过 Suno 中转调用，接口与 Java 调用见 《【模型接入】Suno》
模型选择：
Suno 是目前芋道支持最完整的音乐模型，支持灵感、自定义、续写、合并、上传等功能。
如果你有其它需求，也可以按需评估国产的音乐模型，例如说：
- MiniMax 的 MiniMax Music (opens new window)
- Mureka 的 Mureka API (opens new window)
- 火山引擎的 豆包音乐大模型 (opens new window)
它们使用各自独立的 API / 模型服务，项目暂未接入，需要自行适配，不能在当前音乐模块里直接切换。
整个功能，涉及到 3 个表：
- 【配置】
ai_api_key：API 密钥表 - 【配置】
ai_model：模型表 - 【音乐】
ai_music：音乐表
补充说明：
ai_api_key、ai_model 已经在 《功能开启》 讲解，就不重复赘述。
# 1. 前置准备
# 1.1 配置 API 密钥
芋道通过 Suno 中转提供音乐创作，渠道需要提供的接口与 Suno 的申请方式，见 《【模型接入】Suno》。
在 [AI 大模型 -> 控制台 -> API 密钥] 菜单，新增一个密钥：
- 所属平台：选择「Suno」
- 密钥：填写中转渠道提供的密钥
- 自定义 API URL：填写中转的根地址，系统按渠道选择接口路径
中转渠道示例：
目前已实测的中转渠道有 InfAI、SalpX、apimax，密钥填写渠道提供的 Suno 密钥，各自的自定义 API URL、模型标识与实测范围，见 《【模型接入】Suno》 的「1.2 中转方式」。实际可用的模型版本、价格、分组，以渠道最新文档为准。
# 1.2 配置音乐模型
在 [AI 大模型 -> 控制台 -> 模型配置] 菜单，新增一个模型：
- 所属平台：选择「Suno」
- 模型类型：选择「音乐」，对应 AiModelTypeEnum 的 MUSIC（
type为 7）。创作时会校验模型必须是 Suno 平台的音乐模型 - API 秘钥：选择上一步配置的密钥
- 模型名字：展示名称，例如说
Suno v5 - 模型标识：填写中转支持的 Suno 版本标识，以渠道文档为准。例如说 InfAI 填写
chirp-v6，SalpX 填写V6，apimax 填写suno_music - 模型简介、模型图标：选填，对应
ai_model表的description、icon_url字段（见 《功能开启》 的「4.2 模型表」），会展示在创作页的模型下拉框里
可以配置多个音乐模型，用户创作时在下拉框中选择。
# 1.3 开启定时任务
Suno 生成歌曲是异步的，需要定时执行 AiMusicSyncJob 任务（JobHandler 名字为 aiMusicSyncJob），查询生成进度，并把封面、音频转存到项目的文件服务。建议每 10 秒执行一次，即 Cron 表达式 0/10 * * * * ?。
具体怎么配置定时任务，可以参考 《定时任务》 文档。默认 SQL 里已经有「AI 音乐同步 Job」任务，只是处于暂停状态，开启即可。
# 2. 音乐创作
前端对应 [AI 大模型 -> AI 音乐] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/music/index 目录，提供给普通用户使用。
左边是创作面板，右边是【我的作品】【音乐广场】。有作品在生成中时，【我的作品】会自动刷新。后端 HTTP 接口，由 yudao-module-ai 模块的 music 包的 AiMusicController 实现。
# 2.1 灵感模式
只需要输入一段「歌曲描述」，由 Suno 自动生成歌词、风格和名称。打开「纯音乐」，则只生成伴奏。
# 2.2 自定义模式
自己填写「歌词」「音乐风格」「歌曲名称」：
- 歌词：可以点击【AI 生成歌词】按钮，输入一个主题后，使用 [模型配置] 中排序最靠前、已开启的对话模型生成歌词和名称
- 音乐风格：可以直接输入英文风格，也可以点选下方的预置标签
提交后，一次生成一般会得到 2 首歌曲，每首各占一条作品记录。
# 2.3 续写与合并
已完成的作品，可以进行续写和合并：
- 续写：点击作品的【续写】按钮，填写续写起点（秒）和续写部分的歌词，生成接在原曲后面的新片段。续写会沿用原曲的模型和 API 密钥
- 合并：续写完成后，点击续写作品的【合并】按钮，把续写片段与原曲合并成一首完整的歌曲
续写、合并的入口按钮，以及“续写”“完整歌曲”标签，可见「2.2 自定义模式」的截图。点击【续写】后，左侧创作面板会切换为「续写歌曲」：顶部展示原曲的封面、名称、模型和时长，下方填写续写起点（默认原曲结尾）、歌词、风格和名称；点击【取消续写】可回到普通创作。
# 2.4 上传音频
点击创作面板底部的【上传音乐】按钮（可见「2.2 自定义模式」的截图），上传 mp3 或 wav 格式的音频。上传的作品会出现在【我的作品】中，带有“用户上传”标签，完成后可以作为续写的来源。
- 音频先通过项目通用的文件上传，保存到文件服务，前端再只把文件地址（
fileUrl）提交到/ai/music/upload接口 - 后端按地址下载文件，根据实际内容校验是 mp3 或 wav，再把地址交给中转，所以中转需要能访问这个地址（私有存储会使用预签名地址）
- 前端限制音频不超过 50MB；经后端上传时，同时受
spring.servlet.multipart.max-file-size配置限制（默认 16MB）
中转要求：
合并（/suno/submit/concat）、上传（/suno/uploads/audio-url）不是 New API 官方 SunoAPI 插件的标准路径，需要渠道额外提供。不支持时，作品会直接失败，失败原因一般为“当前中转不支持该接口（HTTP 404）”。
# 2.5 我的作品
在【我的作品】中，可以对作品进行播放、下载、编辑（名称、封面）、公开到音乐广场、删除等操作。点击【详情】，可以查看歌词、来源等信息。
公开的作品，会展示在【音乐广场】中，同一租户的其它用户都可以播放。
# 3. 音乐管理
前端对应 [AI 大模型 -> 控制台 -> 音乐管理] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/music/manager 目录，提供给管理员使用，查看所有用户的音乐记录，可以修改是否公开、删除。
# 4. 音乐表
ai_music：音乐表，一首歌曲一条记录。同一次生成的多首歌曲，共用同一个 task_id。
省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段
CREATE TABLE `ai_music` (
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',
`user_id` bigint NOT NULL COMMENT '用户编号',
`generate_mode` tinyint NOT NULL COMMENT '生成模式：1 灵感 2 自定义 3 续写 4 拼接 5 上传',
`platform` varchar(32) NOT NULL COMMENT '平台',
`model_id` bigint NOT NULL COMMENT '模型编号',
`model` varchar(64) NOT NULL COMMENT '模型标识（mv）',
`api_key_id` bigint NOT NULL COMMENT 'API 密钥编号（提交时绑定）',
`title` varchar(128) NULL COMMENT '音乐名称',
`prompt` varchar(2048) NULL COMMENT '歌曲描述（灵感模式）',
`lyric` text NULL COMMENT '歌词',
`tags` varchar(1024) NULL COMMENT '音乐风格',
`make_instrumental` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否纯音乐',
`ref_music_id` bigint NULL COMMENT '来源音乐编号（续写、拼接）',
`extend_seconds` int NULL COMMENT '续写起点（秒）',
`cover_url` varchar(1024) NULL COMMENT '封面地址',
`audio_url` varchar(1024) NULL COMMENT '音频地址',
`video_url` varchar(1024) NULL COMMENT '视频地址（中转返回，可空）',
`duration` double NULL COMMENT '时长（秒）',
`status` tinyint NOT NULL COMMENT '状态：10 待处理 20 生成中 30 转存中 40 已完成 50 已失败',
`progress` tinyint NOT NULL DEFAULT 0 COMMENT '进度（0-100）',
`error_message` varchar(1024) NULL COMMENT '错误信息',
`public_status` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否公开',
`play_count` int NOT NULL DEFAULT 0 COMMENT '播放次数',
`task_id` varchar(64) NULL COMMENT '中转任务编号',
`clip_id` varchar(64) NULL COMMENT '中转歌曲编号',
`finish_time` datetime NULL COMMENT '完成时间',
PRIMARY KEY (`id`),
KEY `idx_user_id` (`user_id`),
UNIQUE KEY `uk_api_key_task_clip` (`api_key_id`, `task_id`, `clip_id`),
KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI 音乐表';
① user_id 字段：对应 system_users 表的 id 字段，表示哪个用户的作品。
generate_mode 字段：生成模式，对应 AiMusicGenerateModeEnum 枚举。
② platform、model_id、model、api_key_id 字段：提交时使用的模型和 API 密钥。后续查询进度、续写、合并，都使用提交时绑定的 api_key_id，即使模型后来换了密钥也不受影响。
③ title、prompt、lyric、tags、make_instrumental 字段：创作参数。灵感模式只有 prompt（歌曲描述），自定义模式填写其它字段；生成完成后，会更新为中转返回的名称、歌词、风格。
ref_music_id、extend_seconds 字段：续写、拼接时，记录来源作品；续写时，extend_seconds 记录续写起点。
④ cover_url、audio_url、video_url、duration 字段：生成结果。封面、音频会转存到文件服务，转存前是中转返回的地址；视频不转存。
⑤ status 字段：音乐状态，对应 AiMusicStatusEnum 枚举。整体流程是：
- 用户提交时，先插入一条 10 待处理的记录，提交中转成功后，记录
task_id，更新为 20 生成中 - AiMusicSyncJob 定时查询中转进度。生成成功后，按返回的歌曲拆分为每首一条记录，记录
clip_id，更新为 30 转存中 - AiMusicSyncJob 把音频、封面转存到文件服务，更新为 40 已完成。封面是可选的，转存失败时置空，不影响完成
- 中转确认失败，或从提交开始超过 30 分钟仍未完成（例如音频一直转存失败），更新为 50 已失败，失败原因记录在
error_message字段
progress 字段：生成进度，生成中时取自中转，展示在【我的作品】中。
⑥ public_status 字段：是否公开，默认为 false 不公开。公开后展示在【音乐广场】中。
play_count 字段：播放次数。
⑦ task_id、clip_id 字段：中转返回的任务编号、歌曲编号，续写和合并时需要用到。因为不同中转可能返回相同的编号，所以唯一键带上了 api_key_id。
finish_time 字段：完成时间，已完成、已失败时记录。
最最最关键的代码！！！大家可以重点看看！！！
- AiMusicServiceImpl：创作、同步（查询、拆分、转存、超时）的实现
- SunoApi：调用 Suno 中转接口的实现（兼容 New API 的
/suno/*路径，以及 apimax 的生成接口/v1/music/generations），可见 《【模型接入】Suno》