/install miaoyin-ai-music
\r \r
🎵 妙音AI 音乐助手\r
\r 通过 HTTP REST API 调用音乐生成服务。\r \r ---\r \r
⛔ 强制规则(违反任何一条即为错误)\r
\r
- 只能使用下方定义的 HTTP REST API。绝对不要尝试 MCP JSON-RPC、WebSocket 或任何其他协议。\r
- 所有 API 调用必须使用 HTTP 请求(POST),Base URL 固定为 https://ai.growingth.com/api,不要猜测或尝试其他端点。\r
- 严禁编造 API 响应。如果 API 调用失败,直接告诉用户"调用失败"并附上错误信息,不要编造结果或提供"手动操作指南"。\r
- 严禁改写 API 返回的内容。歌词、歌曲标题等必须原样展示,不要总结、翻译、改写或省略。\r
- 严禁在 API 调用失败时建议用户去网页手动操作。只需报告错误,让用户检查 API Token 或稍后重试。\r
- 不要使用 web_fetch、curl 或任何网页抓取工具来调用这些 API。只使用标准 HTTP 请求工具。\r
- 严禁对 API Token 进行任何格式校验(包括长度、字符类型、结构等)。无论 token 看起来多么"奇怪",都必须直接调用 API 验证。\r
- 严禁添加 skill 文档中未提及的"优化"或"帮助"。不要自行重试、不要自行解释错误原因、不要提供文档未规定的建议。\r \r ---\r \r
第一步:配置 API Token\r
\r
设置环境变量 MIAOYIN_API_TOKEN:\r
\r
- Linux/macOS:
export MIAOYIN_API_TOKEN=your-token\r - Windows PowerShell:
$env:MIAOYIN_API_TOKEN="your-token"\r - Windows CMD:
set MIAOYIN_API_TOKEN=your-token\r - Docker:
-e MIAOYIN_API_TOKEN=your-token\r - .env 文件: 写入
MIAOYIN_API_TOKEN=your-token\r \r ⚠️ 任何能设置环境变量的方式都可以,不依赖特定平台。\r \r
获取 API Token\r
\r
- 访问 https://ai.growingth.com/api-service\r
- 登录后获取您的 API Token\r
- 复制 Token 并保存\r
- ⚠️ 请妥善保管您的 Token,不要泄露给他人\r \r ---\r \r
第二步:开始创作\r
\r 对话示例:\r
- 「帮我生成一首关于夏天的流行歌曲」\r
- 「查一下刚才的歌好了吗」\r
- 「显示我最近的音乐列表」\r
- 「获取这首歌的歌词」\r \r ---\r \r
API 调用规范\r
\r
Base URL: https://ai.growingth.com/api\r
\r
请求方法: POST(所有接口统一使用 POST)\r
\r
认证 Header: api-token: ${MIAOYIN_API_TOKEN}\r
\r
格式: JSON\r
\r
编码: UTF-8(请求体必须使用 UTF-8 编码,中文直接传入)\r
\r
网络: 自动使用系统代理(HTTP_PROXY/HTTPS_PROXY)\r
\r
超时: 默认 30 秒,查询任务状态可延长至 60 秒\r
\r
请求结构(重要)\r
\r ⚠️ 所有接口统一使用以下格式:\r \r
{\r
"name": "操作名称",\r
"data": {\r
// 具体请求参数\r
}\r
}\r
```\r
\r
**Header 示例**:\r
```json\r
{\r
"api-token": "Your API Token",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
⚠️ 注意:\r
1. 所有接口都是 POST 请求到 `https://ai.growingth.com/api`\r
2. 操作名称通过 `name` 字段指定(也可以写在 query 参数上)\r
3. 具体请求数据必须放在 `data` 对象中\r
4. 认证使用 `api-token` Header,不是 `Authorization`\r
\r
---\r
\r
## ⚠️ 调用前自检(每次对话必须逐项确认)\r
\r
在调用任何 API 之前,请在心中默念:\r
\r
- [ ] 我有 MIAOYIN_API_TOKEN 吗?\r
→ 没有:引导用户获取,不要尝试调用 API\r
\r
- [ ] 用户的要求能用现有 API 实现吗?\r
→ 不能:直接说"抱歉,当前不支持此功能",不要编造\r
\r
- [ ] 我知道每个参数的含义和必填性吗?\r
→ 不确定:查阅 API 文档,不要猜测\r
\r
- [ ] 我准备好处理可能的错误了吗?\r
→ 没有:先阅读"错误处理流程"章节\r
\r
任何一项为"否",都不要继续调用 API。\r
\r
---\r
\r
## 错误提示模板(必须原样使用,不准修改)\r
\r
| 错误类型 | 提示语 |\r
|---------|--------|\r
| 余额不足 | "❌ 余额不足\
\
您当前的余额不足,无法继续创作。\
请访问 https://ai.growingth.com/api-service 进行额度购买。" |\r
| 未获取Token | "❌ 未配置 API Token\
\
您当前尚未获得凭证(token)。\
请前往 https://ai.growingth.com/api-service 创建获取,以开始您的创作。\
\
🎁 创建后您将获得 10 首歌的免费体验额度!" |\r
| 版权保护 | "❌ 转换失败\
\
该音频与现有作品匹配,触发了版权保护机制,无法转换为 WAV 格式。\
\
建议:尝试转换其他原创歌曲。" |\r
| 401/403 | "API Token 无效或已过期,请检查 MIAOYIN_API_TOKEN 配置" |\r
| 5xx | "请求服务器异常,请稍后重试" |\r
| 超时 | "请求超时,请稍后重试" |\r
| 网络错误 | "网络连接失败,请检查网络或代理设置" |\r
\r
⚠️ 禁止使用其他表述,禁止添加"可能原因"、"建议检查"等额外内容。\r
\r
### 错误类型判断规则\r
\r
根据 API 返回的错误信息,按以下优先级判断错误类型:\r
\r
1. **余额不足**:响应消息包含"余额不足"、"balance"、"insufficient"等关键词\r
2. **未获取Token**:响应消息包含"token"、"凭证"、"未获得"等关键词(且不是 401/403 状态码)\r
3. **版权保护**:响应消息包含"matches existing work of art"、"版权"、"copyright"等关键词\r
4. **401/403**:HTTP 状态码为 401 或 403\r
5. **5xx**:HTTP 状态码为 500-599\r
6. **超时**:请求超时\r
7. **网络错误**:网络连接失败\r
\r
---\r
\r
## 详细错误日志输出(必须执行)\r
\r
**任何 HTTP 请求失败时,除了展示上述用户友好的提示外,还必须输出详细的技术日志供排查问题。**\r
\r
### 日志输出格式\r
\r
```\r
=== 错误详情 ===\r
请求:POST https://ai.growingth.com/api\r
操作:{{操作名称}}\r
状态码:{{状态码}}\r
错误:{{错误信息}}\r
\r
--- 请求头 ---\r
Content-Type: application/json\r
api-token: ********\r
\r
--- 请求体 ---\r
{\r
"name": "{{操作名称}}",\r
"data": { ... }\r
}\r
\r
--- 响应头 ---\r
{{响应头信息}}\r
\r
--- 响应体 ---\r
{{响应体内容}}\r
```\r
\r
### 敏感信息隐藏规则\r
\r
- `api-token: xxx` → `api-token: ********`\r
- `MIAOYIN_API_TOKEN` 环境变量的完整值 → `********`\r
\r
---\r
\r
## 版本声明\r
\r
- **Skill 版本**: 1.0.0\r
- **API 版本**: 以实际 API 响应为准\r
- **兼容性**: 不假设 API 格式固定,以实际响应为准\r
\r
如果 API 响应包含未预期的字段,原样展示,不要报错。\r
\r
---\r
\r
## API 接口列表\r
\r
### API 1:生成歌曲\r
\r
用途:用户想创作/生成音乐时调用。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=generateCustom\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"prompt": "歌词内容",\r
"tags": "歌曲风格,如 Chinese, Piano, Guitar",\r
"negative_tags": "排除风格(可选)",\r
"model": "chirp-v5",\r
"desc": "描述信息(可选)",\r
"title": "歌曲标题(可选)",\r
"make_instrumental": false\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| prompt | String | ✅ 是 | 歌词内容 |\r
| tags | String | ❌ 否 | 歌曲风格,如 Chinese, Piano, Guitar |\r
| negative_tags | String | ❌ 否 | 排除风格 |\r
| model | String | ❌ 否 | 模型版本:chirp-v5-5, chirp-v5, chirp-v4-5, chirp-v4, chirp-v3-5,默认 chirp-v5 |\r
| desc | String | ❌ 否 | 描述信息 |\r
| title | String | ❌ 否 | 歌曲标题 |\r
| make_instrumental | Boolean | ❌ 否 | 是否纯音乐,默认 false |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": [\r
{\r
"taskId": "c13975cda17449da2261"\r
}\r
]\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Array | 任务数据数组 |\r
| data[].taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [生成歌曲] [创作音乐] [写首歌] [做首曲子] 等意图时:\r
\r
步骤 1:确认需求\r
IF 用户提供了歌词:\r
prompt = 用户提供的完整歌词\r
ELSE IF 用户描述了音乐风格(如"夏天的流行歌"):\r
prompt = 用户的描述\r
tags = 根据描述提取风格标签\r
ELSE:\r
询问用户:"请提供歌词,或描述您想要的音乐风格(例如:帮我生成一首关于夏天的流行歌曲)"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=generateCustom\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"prompt": "步骤 1 中确定的歌词或描述",\r
"tags": "用户指定的风格(可选)",\r
"title": "用户指定的标题(可选)",\r
"model": "chirp-v5",\r
"make_instrumental": 用户要求纯音乐则为 true,否则为 false\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data[0].taskId\r
说:"✅ 提交成功!任务编号:{taskId},正在生成中,请稍候..."\r
→ 转到查询任务状态流程(待补充)\r
ELSE:\r
说:"❌ 生成失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:用户提供歌词\r
\r
```\r
用户:我想用这首歌词生成音乐:\r
[Verse]\r
阳光洒在海面\r
微风吹拂着脸\r
\r
[Chorus]\r
这是我们的夏天\r
永远不变的画面\r
\r
AI: 收到!我将用您提供的歌词生成音乐。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
[请求体] {\r
"data": {\r
"prompt": "[Verse]\
阳光洒在海面\
微风吹拂着脸\
\
[Chorus]\
这是我们的夏天\
永远不变的画面",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中,请稍候...\r
```\r
\r
#### 示例 2:用户描述风格\r
\r
```\r
用户:帮我生成一首关于夏天的流行歌曲,要有钢琴和吉他\r
\r
AI: 好的,我来帮您创作一首夏天主题的流行歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
[请求体] {\r
"data": {\r
"prompt": "关于夏天的流行歌曲",\r
"tags": "Piano, Guitar",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中,请稍候...\r
```\r
\r
#### 示例 3:生成纯音乐\r
\r
```\r
用户:生成一首中国风的纯音乐\r
\r
AI: 好的,我来为您创作一首中国风纯音乐。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
[请求体] {\r
"data": {\r
"prompt": "中国风纯音乐",\r
"tags": "Chinese",\r
"model": "chirp-v5",\r
"make_instrumental": true\r
}\r
}\r
\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中,请稍候...\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **编码要求**\r
- 请求体必须使用 UTF-8 编码\r
- 中文歌词直接传入,不要转义\r
\r
2. **模型版本选择**\r
- 默认使用 `chirp-v5`\r
- 可选版本:chirp-v5-5(最新), chirp-v5, chirp-v4-5, chirp-v4, chirp-v3-5\r
- 除非用户明确指定,否则使用默认版本\r
\r
3. **风格标签(tags)**\r
- 多个风格用逗号分隔,如 "Chinese, Piano, Guitar"\r
- 常见风格:Pop, Rock, Jazz, Classical, Electronic, Chinese, Piano, Guitar 等\r
\r
4. **任务编号保存**\r
- 生成成功后,必须保存 taskId 用于后续查询\r
- 在对话上下文中记住最近的 taskId\r
\r
---\r
\r
### API 2:查询歌曲状态\r
\r
用途:查询生成进度和结果。\r
\r
⚠️ **重要警告**:请勿过于频繁调用此接口,建议查询间隔不低于 10 秒,否则可能会被禁用。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=getMusic\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"ids": "c13975cda17449da2261,0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| ids | String | ✅ 是 | 歌曲 id 列表(也可以是 taskId),以英文逗号分隔多个 |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": [\r
{\r
"id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"title": "Through the Fog",\r
"image_url": "https://cdn2.suno.ai/image_0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f.jpeg",\r
"lyric": "[Instrumental]",\r
"audio_url": "https://cdn1.suno.ai/0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f.mp3",\r
"video_url": "https://cdn1.suno.ai/0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f.mp4",\r
"created_at": "2024-08-30T07:46:22.206Z",\r
"model_name": "chirp-v4",\r
"status": "complete"\r
}\r
]\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Array | 歌曲数据数组 |\r
| data[].id | String | 歌曲唯一标识 |\r
| data[].title | String | 歌曲标题 |\r
| data[].image_url | String | 封面图片链接 |\r
| data[].lyric | String | 歌词内容 |\r
| data[].audio_url | String | 音频播放链接 |\r
| data[].video_url | String | 视频播放链接 |\r
| data[].created_at | String | 创建时间 |\r
| data[].model_name | String | 使用的模型名称 |\r
| data[].status | String | 生成状态:complete(完成)/ processing(处理中)/ queued(排队中)/ failed(失败) |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当需要查询歌曲状态时(生成后自动查询 / 用户主动询问):\r
\r
步骤 1:确定要查询的任务编号\r
IF 是刚生成的任务:\r
taskId = 上一步生成歌曲返回的 taskId\r
ELSE IF 用户提供了编号(如"查一下 c13975cda17449da2261 的状态"):\r
taskId = 用户提供的编号\r
ELSE IF 用户说"刚才的歌/最近的任务":\r
taskId = 最近一次提交的任务编号(需要从上下文记忆)\r
ELSE:\r
询问用户:"请问要查询哪个任务?请提供任务编号"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=getMusic\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"ids": taskId\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
FOR EACH song IN response.data:\r
status = song.status\r
\r
IF status == "complete":\r
展示:\r
🎵 歌曲名:{song.title}\r
🎼 歌词:{song.lyric}\r
▶️ 音频播放:{song.audio_url} | 下载:{song.audio_url}\r
🎬 视频播放:{song.video_url} | 下载:{song.video_url}\r
🖼️ 封面图片:{song.image_url}\r
📅 创建时间:{song.created_at}\r
🤖 模型:{song.model_name}\r
\r
ELSE IF status == "processing" 或 "queued":\r
说:\r
⏳ 音乐还在生成中,当前状态:{status}\r
请您过 10 秒以上再问我"好了吗",我会继续为您查询。\r
→ 停止,不要再调用 API\r
\r
ELSE IF status == "failed":\r
说:\r
❌ 生成失败\r
任务编号:{song.id}\r
→ 停止,不要重试\r
\r
ELSE:\r
说:\r
⚠️ 未知状态:{status}\r
ELSE:\r
说:"❌ 查询失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:生成后自动查询(完成)\r
\r
```\r
用户:帮我生成一首关于夏天的流行歌曲\r
\r
AI: [执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中,请稍候...\r
\r
[等待 10 秒后执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "c13975cda17449da2261"\r
}\r
}\r
\r
🎵 生成完成!\r
歌曲名:夏日微风\r
歌曲id:1231465\r
🎼 歌词:\r
[Verse]\r
阳光洒在海面\r
微风吹拂着脸\r
...\r
\r
▶️ 音频播放:https://cdn1.suno.ai/c13975cda17449da2261.mp3 | 下载:https://cdn1.suno.ai/c13975cda17449da2261.mp3\r
🎬 视频播放:https://cdn1.suno.ai/c13975cda17449da2261.mp4 | 下载:https://cdn1.suno.ai/c13975cda17449da2261.mp4\r
🖼️ 封面图片:https://cdn2.suno.ai/image_c13975cda17449da2261.jpeg\r
```\r
\r
#### 示例 2:用户主动询问(处理中)\r
\r
```\r
用户:刚才那首歌好了吗\r
\r
AI: [执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "c13975cda17449da2261"\r
}\r
}\r
\r
⏳ 音乐还在生成中,当前状态:processing\r
请您过 10 秒以上再问我"好了吗",我会继续为您查询。\r
```\r
\r
#### 示例 3:批量查询多个任务\r
\r
```\r
用户:帮我查一下这三个任务的状态:c13975cda17449da2261,0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f,d57dba20-e63d-4c99-ab43-9469d2944f9f\r
\r
AI: [执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "c13975cda17449da2261,0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f,d57dba20-e63d-4c99-ab43-9469d2944f9f"\r
}\r
}\r
\r
任务 1:✅ 已完成\r
歌曲名:夏日微风\r
▶️ 播放:https://cdn1.suno.ai/c13975cda17449da2261.mp3 | 下载:https://cdn1.suno.ai/c13975cda17449da2261.mp3\r
\r
任务 2:✅ 已完成\r
歌曲名:Through the Fog\r
▶️ 播放:https://cdn1.suno.ai/0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f.mp3 | 下载:https://cdn1.suno.ai/0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f.mp3\r
\r
任务 3:⏳ 生成中(processing)\r
请稍后再问\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **查询频率限制(非常重要)**\r
- **最小查询间隔:10 秒**\r
- 违反此规则可能导致接口被禁用\r
- 生成后第一次查询:建议等待 10-15 秒\r
- 用户再次询问:确保距离上次查询至少 10 秒\r
\r
2. **轮询限制**(必须严格遵守)\r
- ✅ 允许:生成后等待 10 秒查询 1 次\r
- ✅ 允许:用户询问时再查询 1 次(间隔 10 秒以上)\r
- ❌ 禁止:自己循环调用查询接口\r
- ❌ 禁止:在 10 秒内连续查询\r
- ❌ 禁止:在任务未完成时频繁查询\r
\r
3. **状态处理优先级**\r
```\r
complete → 立即展示播放链接和完整信息\r
failed → 展示失败信息,不要重试\r
processing/queued → 告知用户稍后再问(至少 10 秒),然后停止\r
```\r
\r
4. **歌词展示**\r
- 必须完整原样展示 lyric 字段内容\r
- 不要总结、翻译、改写或省略\r
- 纯音乐的歌词通常是 "[Instrumental]"\r
\r
5. **批量查询**\r
- 支持一次查询多个任务\r
- 多个 id 用英文逗号分隔\r
- 最多建议一次查询不超过 10 个\r
\r
---\r
\r
### API 3:续写歌曲\r
\r
用途:如果歌曲效果不错,但时长不足,可通过此接口进行续写。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=generateContinue\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"audio_id": "歌曲 clipId",\r
"continue_clip_id": "歌曲 clipId",\r
"continue_at": 7,\r
"prompt": "歌词内容(可选)",\r
"tags": "歌曲风格(可选)",\r
"negative_tags": "排除风格(可选)",\r
"model": "chirp-v5",\r
"desc": "描述信息(可选)",\r
"title": "歌曲标题(可选)",\r
"make_instrumental": false\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| audio_id | String | ✅ 是 | 续写歌曲的 clipId |\r
| continue_clip_id | String | ✅ 是 | 续写歌曲的 clipId(与 audio_id 相同) |\r
| continue_at | Number | ✅ 是 | 续写时间点,单位秒 |\r
| prompt | String | ❌ 否 | 歌词内容 |\r
| tags | String | ❌ 否 | 歌曲风格,如 Chinese, Piano, Guitar |\r
| negative_tags | String | ❌ 否 | 排除风格 |\r
| model | String | ❌ 否 | 模型版本:chirp-v5, chirp-v4-5, chirp-v4, chirp-v3-5,默认 chirp-v5 |\r
| desc | String | ❌ 否 | 描述信息 |\r
| title | String | ❌ 否 | 歌曲标题 |\r
| make_instrumental | Boolean | ❌ 否 | 是否纯音乐,默认 false |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": [\r
{\r
"taskId": "xxx"\r
}\r
]\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Array | 任务数据数组 |\r
| data[].taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [续写] [继续创作] [延长歌曲] [接着写] 等意图时:\r
\r
步骤 1:确认续写需求\r
IF 用户提供了歌曲 ID 和续写时间点:\r
audio_id = 用户提供的歌曲 ID\r
continue_at = 用户指定的时间点(秒)\r
ELSE IF 用户提供了歌曲 ID 但未指定时间点:\r
audio_id = 用户提供的歌曲 ID\r
询问用户:"请问从第几秒开始续写?(例如:从第 7 秒开始)"\r
→ 停止,等待用户回复\r
ELSE IF 用户说"续写刚才的歌":\r
audio_id = 最近一次生成的歌曲 ID(从查询结果中获取)\r
询问用户:"请问从第几秒开始续写?(例如:从第 7 秒开始)"\r
→ 停止,等待用户回复\r
ELSE:\r
询问用户:"请提供要续写的歌曲 ID 和续写时间点(例如:续写歌曲 xxx,从第 7 秒开始)"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=generateContinue\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"audio_id": audio_id,\r
"continue_clip_id": audio_id,\r
"continue_at": continue_at, // 必须明确指定续写时间点(秒)\r
"prompt": "用户指定的歌词(可选)",\r
"tags": "用户指定的风格(可选)",\r
"model": "chirp-v5", // 固定使用 chirp-v5 模型\r
"make_instrumental": 用户要求纯音乐则为 true,否则为 false\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data[0].taskId\r
说:"✅ 续写提交成功!任务编号:{taskId},正在生成中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ 续写失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:续写指定歌曲\r
\r
```\r
用户:帮我续写歌曲 0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f,从第 7 秒开始\r
\r
AI: 好的,我将从第 7 秒开始续写这首歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateContinue]\r
[请求体] {\r
"data": {\r
"audio_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"continue_clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"continue_at": 7,\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 续写提交成功!任务编号:d57dba20-e63d-4c99-ab43-9469d2944f9f,正在生成中,请稍候...\r
```\r
\r
#### 示例 2:续写最近的歌曲\r
\r
```\r
用户:续写刚才那首歌\r
\r
AI: 请问从第几秒开始续写?(例如:从第 7 秒开始)\r
\r
用户:从第 10 秒开始\r
\r
AI: 好的,我将从第 10 秒开始续写。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateContinue]\r
[请求体] {\r
"data": {\r
"audio_id": "c13975cda17449da2261",\r
"continue_clip_id": "c13975cda17449da2261",\r
"continue_at": 10,\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 续写提交成功!任务编号:xxx,正在生成中,请稍候...\r
```\r
\r
#### 示例 3:续写并指定新歌词\r
\r
```\r
用户:续写歌曲 0e66d6dd,从第 10 秒开始,加上这段歌词:\r
[Bridge]\r
时光流转不停\r
回忆永远鲜明\r
\r
AI: 好的,我将从第 10 秒开始续写,并使用您提供的歌词。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateContinue]\r
[请求体] {\r
"data": {\r
"audio_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"continue_clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"continue_at": 10,\r
"prompt": "[Bridge]\
时光流转不停\
回忆永远鲜明",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 续写提交成功!任务编号:xxx,正在生成中,请稍候...\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **歌曲 ID 获取**\r
- 歌曲 ID(clipId)从 API 2 查询歌曲状态的响应中获取\r
- 响应字段中的 `id` 就是 clipId\r
- 必须先查询歌曲状态,确认歌曲已完成(status = complete)后才能续写\r
\r
2. **续写时间点(continue_at)**\r
- 单位:秒\r
- **必须明确指定具体的秒数**(例如:7、10、15 等)\r
- 不能使用 0 或空值\r
- 建议续写时间点不要超过原歌曲时长\r
- 如果用户未指定,必须询问用户具体从第几秒开始\r
\r
3. **audio_id 和 continue_clip_id**\r
- 这两个字段必须相同\r
- 都填写要续写的歌曲 clipId\r
\r
4. **续写后的查询**\r
- 续写成功后会返回新的 taskId\r
- 使用 API 2 查询新任务的状态\r
- 续写生成的是一首新歌曲,不会覆盖原歌曲\r
\r
5. **模型版本**\r
- **固定使用 chirp-v5 模型**\r
- 不要使用其他模型版本\r
\r
---\r
\r
### API 4:翻唱模式(Cover)\r
\r
用途:在保持主旋律的前提下,对歌曲进行翻唱改编或提升音质。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=generateCover\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"continue_clip_id": "歌曲 clipId",\r
"prompt": "歌词内容(可选)",\r
"tags": "歌曲风格(可选)",\r
"negative_tags": "排除风格(可选)",\r
"model": "chirp-v5",\r
"title": "歌曲标题(可选)",\r
"make_instrumental": false,\r
"persona_id": "音色 persona_clip_id(可选)",\r
"artist_clip_id": "音色 root_clip_id(可选)"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| continue_clip_id | String | ✅ 是 | 需要翻唱的歌曲 clipId |\r
| prompt | String | ❌ 否 | 歌词内容 |\r
| tags | String | ❌ 否 | 歌曲风格,如 Chinese, Piano, Guitar |\r
| negative_tags | String | ❌ 否 | 排除风格 |\r
| model | String | ❌ 否 | 模型版本:chirp-v5, chirp-v4-5, chirp-v4, chirp-v3-5,默认 chirp-v5 |\r
| title | String | ❌ 否 | 歌曲标题 |\r
| make_instrumental | Boolean | ❌ 否 | 是否纯音乐,默认 false |\r
| persona_id | String | ❌ 否 | 音色参数(通过 makePersona 任务获取的 persona_clip_id) |\r
| artist_clip_id | String | ❌ 否 | 音色参数(通过 makePersona 任务获取的 root_clip_id) |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": [\r
{\r
"taskId": "xxx"\r
}\r
]\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Array | 任务数据数组 |\r
| data[].taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [翻唱] [改编] [Cover] [换个风格] [提升音质] 等意图时:\r
\r
步骤 1:确认翻唱需求\r
IF 用户提供了歌曲 ID:\r
continue_clip_id = 用户提供的歌曲 ID\r
ELSE IF 用户说"翻唱刚才的歌":\r
continue_clip_id = 最近一次生成的歌曲 ID(从查询结果中获取)\r
ELSE:\r
询问用户:"请提供要翻唱的歌曲 ID"\r
→ 停止,等待用户回复\r
\r
可选确认:\r
- tags = 用户指定的新风格\r
- prompt = 用户指定的新歌词\r
- persona_id / artist_clip_id = 用户指定的音色参数\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=generateCover\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"continue_clip_id": continue_clip_id,\r
"prompt": "用户指定的歌词(可选)",\r
"tags": "用户指定的风格(可选)",\r
"model": "chirp-v5",\r
"title": "用户指定的标题(可选)",\r
"make_instrumental": 用户要求纯音乐则为 true,否则为 false\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data[0].taskId\r
说:"✅ 翻唱提交成功!任务编号:{taskId},正在生成中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ 翻唱失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:翻唱指定歌曲\r
\r
```\r
用户:帮我翻唱歌曲 0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f\r
\r
AI: 好的,我将为您翻唱这首歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCover]\r
[请求体] {\r
"data": {\r
"continue_clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 翻唱提交成功!任务编号:xxx,正在生成中,请稍候...\r
```\r
\r
#### 示例 2:翻唱并改变风格\r
\r
```\r
用户:把刚才那首歌改成爵士风格\r
\r
AI: 好的,我将把这首歌改编成爵士风格。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCover]\r
[请求体] {\r
"data": {\r
"continue_clip_id": "c13975cda17449da2261",\r
"tags": "Jazz",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 翻唱提交成功!任务编号:xxx,正在生成中,请稍候...\r
```\r
\r
#### 示例 3:翻唱并修改歌词\r
\r
```\r
用户:翻唱歌曲 0e66d6dd,用这段新歌词:\r
[Verse]\r
夜色温柔如水\r
星光点点相随\r
\r
AI: 好的,我将使用新歌词翻唱这首歌。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCover]\r
[请求体] {\r
"data": {\r
"continue_clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"prompt": "[Verse]\
夜色温柔如水\
星光点点相随",\r
"model": "chirp-v5"\r
}\r
}\r
\r
✅ 翻唱提交成功!任务编号:xxx,正在生成中,请稍候...\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **歌曲 ID 获取**\r
- 歌曲 ID(clipId)从 API 2 查询歌曲状态的响应中获取\r
- 响应字段中的 `id` 就是 clipId\r
- 必须先查询歌曲状态,确认歌曲已完成(status = complete)后才能翻唱\r
\r
2. **翻唱与原创的区别**\r
- 翻唱会保持原歌曲的主旋律\r
- 可以改变风格、歌词、音色等元素\r
- 适合用于改编、提升音质、换风格等场景\r
\r
3. **音色参数(高级功能)**\r
- `persona_id` 和 `artist_clip_id` 用于指定特定音色\r
- 这些参数需要通过 makePersona 任务预先获取\r
- 如果不指定,系统会使用默认音色\r
\r
4. **翻唱后的查询**\r
- 翻唱成功后会返回新的 taskId\r
- 使用 API 2 查询新任务的状态\r
- 翻唱生成的是一首新歌曲,不会覆盖原歌曲\r
\r
5. **推荐使用场景**\r
- 改变歌曲风格(如流行改爵士)\r
- 提升老歌音质\r
- 使用不同音色演唱\r
- 修改部分歌词但保持旋律\r
\r
---\r
\r
### API 5:合并续写歌曲\r
\r
用途:续写歌曲生成后,通过此接口将续写片段与父歌曲合并成完整歌曲。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=concat\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"clip_id": "1c51baab-5085-4e2e-a1d8-c6a103a55488"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| clip_id | String | ✅ 是 | 续写歌曲的 id(通过 API 3 续写后生成的歌曲 id) |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": [\r
{\r
"taskId": "xxx"\r
}\r
]\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Array | 任务数据数组 |\r
| data[].taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [合并] [拼接] [合成完整歌曲] 等意图时:\r
\r
步骤 1:确认合并需求\r
IF 用户提供了续写歌曲的 ID:\r
clip_id = 用户提供的续写歌曲 ID\r
ELSE IF 用户说"合并刚才续写的歌":\r
clip_id = 最近一次续写生成的歌曲 ID(从 API 3 的响应中获取)\r
ELSE:\r
询问用户:"请提供要合并的续写歌曲 ID"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=concat\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"clip_id": clip_id\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data[0].taskId\r
说:"✅ 合并提交成功!任务编号:{taskId},正在处理中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ 合并失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:续写后立即合并\r
\r
```\r
用户:帮我续写歌曲 0e66d6dd,从第 7 秒开始\r
\r
AI: [执行:POST https://ai.growingth.com/api/song/proxy?name=generateContinue]\r
✅ 续写提交成功!任务编号:1c51baab-5085-4e2e-a1d8-c6a103a55488,正在生成中...\r
\r
[等待生成完成后]\r
🎵 续写完成!\r
\r
用户:把续写的部分和原歌曲合并\r
\r
AI: 好的,我将把续写片段与原歌曲合并成完整歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=concat]\r
[请求体] {\r
"data": {\r
"clip_id": "1c51baab-5085-4e2e-a1d8-c6a103a55488"\r
}\r
}\r
\r
✅ 合并提交成功!任务编号:xxx,正在处理中,请稍候...\r
```\r
\r
#### 示例 2:合并指定的续写歌曲\r
\r
```\r
用户:合并续写歌曲 1c51baab-5085-4e2e-a1d8-c6a103a55488\r
\r
AI: 好的,我将合并这首续写歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=concat]\r
[请求体] {\r
"data": {\r
"clip_id": "1c51baab-5085-4e2e-a1d8-c6a103a55488"\r
}\r
}\r
\r
✅ 合并提交成功!任务编号:xxx,正在处理中,请稍候...\r
\r
[等待 10 秒后查询]\r
🎵 合并完成!\r
歌曲名:夏日微风(完整版)\r
▶️ 音频播放:https://cdn1.suno.ai/xxx.mp3 | 下载:https://cdn1.suno.ai/xxx.mp3\r
```\r
\r
#### 示例 3:完整的续写+合并流程\r
\r
```\r
用户:续写刚才那首歌,然后合并成完整版\r
\r
AI: 好的,我先为您续写歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateContinue]\r
✅ 续写提交成功!任务编号:1c51baab,正在生成中...\r
\r
[等待生成完成]\r
🎵 续写完成!现在开始合并...\r
\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=concat]\r
[请求体] {\r
"data": {\r
"clip_id": "1c51baab-5085-4e2e-a1d8-c6a103a55488"\r
}\r
}\r
\r
✅ 合并提交成功!正在处理中...\r
\r
[等待合并完成]\r
🎵 合并完成!完整歌曲已生成。\r
▶️ 音频播放:https://cdn1.suno.ai/xxx.mp3 | 下载:https://cdn1.suno.ai/xxx.mp3\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **合并前提条件**\r
- 必须先通过 API 3 续写歌曲\r
- 续写任务必须已完成(status = complete)\r
- 使用续写生成的歌曲 ID(不是原歌曲 ID)\r
\r
2. **clip_id 获取**\r
- clip_id 是续写歌曲的 ID\r
- 从 API 3 续写接口的响应中获取 taskId\r
- 然后通过 API 2 查询该任务,获取生成的歌曲 id\r
\r
3. **合并结果**\r
- 合并会生成一首新的完整歌曲\r
- 返回新的 taskId,需要通过 API 2 查询\r
- 原歌曲和续写片段不会被删除\r
\r
4. **推荐工作流程**\r
```\r
1. 生成原歌曲(API 1)\r
2. 续写歌曲(API 3)\r
3. 查询续写状态(API 2)确认完成\r
4. 合并歌曲(API 5)\r
5. 查询合并结果(API 2)\r
```\r
\r
5. **合并后的查询**\r
- 合并成功后会返回新的 taskId\r
- 使用 API 2 查询合并任务的状态\r
- 合并完成后可以获取完整歌曲的播放链接\r
\r
---\r
\r
### API 6:生成视频\r
\r
用途:为已生成的歌曲创建视频。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=generateVideo\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"title": "歌曲标题",\r
"clip_id": "需生成视频的 clip id"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| title | String | ✅ 是 | 歌曲标题 |\r
| clip_id | String | ✅ 是 | 需生成视频的歌曲 clip id |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": {\r
"taskId": "MBENVP5DFKOSPJHO"\r
}\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Object | 任务数据对象 |\r
| data.taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [生成视频] [创建视频] [做个视频] [视频版] 等意图时:\r
\r
步骤 1:确认视频生成需求\r
IF 用户提供了歌曲 ID:\r
clip_id = 用户提供的歌曲 ID\r
ELSE IF 用户说"给刚才的歌生成视频":\r
clip_id = 最近一次生成的歌曲 ID(从查询结果中获取)\r
ELSE:\r
询问用户:"请提供要生成视频的歌曲 ID"\r
→ 停止,等待用户回复\r
\r
获取歌曲标题:\r
IF 已知歌曲标题(从之前的查询结果中):\r
title = 已知的歌曲标题\r
ELSE:\r
先调用 API 2 查询歌曲信息,获取标题\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=generateVideo\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"title": title,\r
"clip_id": clip_id\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data.taskId\r
说:"✅ 视频生成提交成功!任务编号:{taskId},正在生成中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ 视频生成失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:为指定歌曲生成视频\r
\r
```\r
用户:帮我给歌曲 0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f 生成视频\r
\r
AI: 好的,我先查询一下这首歌的信息。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f"\r
}\r
}\r
\r
查询到歌曲:Through the Fog\r
\r
现在开始生成视频...\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateVideo]\r
[请求体] {\r
"data": {\r
"title": "Through the Fog",\r
"clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f"\r
}\r
}\r
\r
✅ 视频生成提交成功!任务编号:MBENVP5DFKOSPJHO,正在生成中,请稍候...\r
```\r
\r
#### 示例 2:为刚才生成的歌曲创建视频\r
\r
```\r
用户:给刚才那首歌生成一个视频\r
\r
AI: 好的,我将为《夏日微风》生成视频。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateVideo]\r
[请求体] {\r
"data": {\r
"title": "夏日微风",\r
"clip_id": "c13975cda17449da2261"\r
}\r
}\r
\r
✅ 视频生成提交成功!任务编号:MBENVP5DFKOSPJHO,正在生成中,请稍候...\r
\r
[等待 10 秒后查询]\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "c13975cda17449da2261"\r
}\r
}\r
\r
🎬 视频生成完成!\r
歌曲id:123465\r
歌曲名:夏日微风\r
🎬 视频播放:https://cdn1.suno.ai/c13975cda17449da2261.mp4 | 下载:https://cdn1.suno.ai/c13975cda17449da2261.mp4\r
```\r
\r
#### 示例 3:生成歌曲后立即创建视频\r
\r
```\r
用户:帮我生成一首关于夏天的流行歌曲,然后做成视频\r
\r
AI: 好的,我先为您创作歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中...\r
\r
[等待生成完成]\r
🎵 歌曲生成完成!\r
歌曲名:夏日微风\r
歌曲id:123465\r
现在开始生成视频...\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateVideo]\r
[请求体] {\r
"data": {\r
"title": "夏日微风",\r
"clip_id": "c13975cda17449da2261"\r
}\r
}\r
\r
✅ 视频生成提交成功!正在处理中...\r
\r
[等待视频生成完成]\r
🎬 视频生成完成!\r
🎬 视频id:123465\r
🎬 视频播放:https://cdn1.suno.ai/c13975cda17449da2261.mp4 | 下载:https://cdn1.suno.ai/c13975cda17449da2261.mp4\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **前提条件**\r
- 必须先有已生成完成的歌曲(status = complete)\r
- 需要知道歌曲的 clip_id 和 title\r
\r
2. **clip_id 获取**\r
- clip_id 从 API 2 查询歌曲状态的响应中获取\r
- 响应字段中的 `id` 就是 clip_id\r
\r
3. **title 参数**\r
- 必须提供歌曲标题\r
- 如果不知道标题,先调用 API 2 查询歌曲信息\r
\r
4. **视频生成时间**\r
- 视频生成通常需要较长时间\r
- 建议等待 15-30 秒后再查询状态\r
- 查询间隔仍然遵守 10 秒以上的规则\r
\r
5. **查询视频结果**\r
- 使用 API 2(getMusic)查询任务状态\r
- 视频生成完成后,响应中会包含 `video_url` 字段\r
- 如果 `video_url` 为空或不存在,说明视频还在生成中\r
\r
6. **推荐使用场景**\r
- 为已生成的歌曲创建视频版本\r
- 分享到社交媒体时需要视频格式\r
- 制作音乐MV\r
\r
---\r
\r
### API 7:生成 WAV 格式\r
\r
用途:将歌曲转换为 WAV 无损音频格式。\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=makeWav\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"clipId": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| clipId | String | ✅ 是 | 歌曲 id(clip id) |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": {\r
"taskId": "MBENVP5DFKOSPJHO"\r
}\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Object | 任务数据对象 |\r
| data.taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [生成 WAV] [转换 WAV] [无损格式] [WAV 格式] 等意图时:\r
\r
步骤 1:确认 WAV 生成需求\r
IF 用户提供了歌曲 ID:\r
clipId = 用户提供的歌曲 ID\r
ELSE IF 用户说"把刚才的歌转成 WAV":\r
clipId = 最近一次生成的歌曲 ID(从查询结果中获取)\r
ELSE:\r
询问用户:"请提供要转换的歌曲 ID"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=makeWav\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"clipId": clipId\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data.taskId\r
说:"✅ WAV 格式生成提交成功!任务编号:{taskId},正在转换中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ WAV 格式生成失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:为指定歌曲生成 WAV 格式\r
\r
```\r
用户:帮我把歌曲 0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f 转成 WAV 格式\r
\r
AI: 好的,我将为这首歌生成 WAV 无损格式。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=makeWav]\r
[请求体] {\r
"data": {\r
"clipId": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f"\r
}\r
}\r
\r
✅ WAV 格式生成提交成功!任务编号:MBENVP5DFKOSPJHO,正在转换中,请稍候...\r
```\r
\r
#### 示例 2:为刚才生成的歌曲转换格式\r
\r
```\r
用户:把刚才那首歌转成 WAV 格式\r
\r
AI: 好的,我将为《夏日微风》生成 WAV 无损格式。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=makeWav]\r
[请求体] {\r
"data": {\r
"clipId": "c13975cda17449da2261"\r
}\r
}\r
\r
✅ WAV 格式生成提交成功!任务编号:MBENVP5DFKOSPJHO,正在转换中,请稍候...\r
\r
[等待 10 秒后查询]\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
[请求体] {\r
"data": {\r
"ids": "c13975cda17449da2261"\r
}\r
}\r
\r
🎵 WAV 格式生成完成!\r
歌曲名:夏日微风\r
歌曲id: 123312\r
▶️ WAV 播放:https://cdn1.suno.ai/c13975cda17449da2261.wav | 下载:https://cdn1.suno.ai/c13975cda17449da2261.wav\r
```\r
\r
#### 示例 3:生成歌曲后立即转换为 WAV\r
\r
```\r
用户:帮我生成一首关于夏天的流行歌曲,要 WAV 格式的\r
\r
AI: 好的,我先为您创作歌曲。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateCustom]\r
✅ 提交成功!任务编号:c13975cda17449da2261,正在生成中...\r
\r
[等待生成完成]\r
🎵 歌曲生成完成!\r
歌曲名:夏日微风\r
\r
现在开始生成 WAV 格式...\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=makeWav]\r
[请求体] {\r
"data": {\r
"clipId": "c13975cda17449da2261"\r
}\r
}\r
\r
✅ WAV 格式生成提交成功!正在转换中...\r
\r
[等待转换完成]\r
🎵 WAV 格式生成完成!\r
▶️ WAV 播放:https://cdn1.suno.ai/c13975cda17449da2261.wav | 下载:https://cdn1.suno.ai/c13975cda17449da2261.wav\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **前提条件**\r
- 必须先有已生成完成的歌曲(status = complete)\r
- 需要知道歌曲的 clipId\r
\r
2. **clipId 获取**\r
- clipId 从 API 2 查询歌曲状态的响应中获取\r
- 响应字段中的 `id` 就是 clipId\r
\r
3. **WAV 格式特点**\r
- WAV 是无损音频格式\r
- 文件体积比 MP3 大\r
- 音质更好,适合专业音频处理\r
\r
4. **转换时间**\r
- WAV 格式生成通常需要一定时间\r
- 建议等待 10-15 秒后再查询状态\r
- 查询间隔仍然遵守 10 秒以上的规则\r
\r
5. **查询 WAV 结果**\r
- 使用 API 2(getMusic)查询任务状态\r
- WAV 生成完成后,响应中可能包含 WAV 格式的下载链接\r
- 具体字段名以实际 API 响应为准\r
\r
6. **推荐使用场景**\r
- 需要高音质无损格式\r
- 用于专业音频编辑\r
- 音乐制作和后期处理\r
- 存档保存原始音质\r
\r
\r
---\r
\r
### API 8:音频分轨\r
\r
用途:提取歌曲的伴奏音轨或去除混响,用于伴奏制作、音频处理等用途。\r
\r
⚠️ **重要限制**:\r
- ✅ 可以提取:伴奏音轨、独立乐器音轨(鼓、贝斯、吉他等)、去除混响\r
- ❌ 不能提取:人声\r
- 如果用户要求提取人声,必须明确告知此功能不支持\r
\r
**请求地址**:\r
```\r
POST https://ai.growingth.com/api/song/proxy?name=generateStem\r
```\r
\r
**Headers**:\r
```json\r
{\r
"api-token": "${MIAOYIN_API_TOKEN}",\r
"Content-Type": "application/json; charset=utf-8"\r
}\r
```\r
\r
**请求体结构**:\r
```json\r
{\r
"data": {\r
"title": "歌曲标题",\r
"clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"stemType": "two"\r
}\r
}\r
```\r
\r
**data 字段说明**:\r
\r
| 字段 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| title | String | ✅ 是 | 歌曲标题 |\r
| clip_id | String | ✅ 是 | 需要分离的歌曲 ID |\r
| stemType | String | ✅ 是 | 分轨类型:`two`(2分轨)、`twelve`(12分轨)、`dry`(去除混响) |\r
\r
**stemType 选项说明**:\r
\r
| 值 | 说明 | 用途 |\r
|----|------|------|\r
| two | 2 分轨 | 提取伴奏音轨(不含人声) |\r
| twelve | 12 分轨 | 提取 12 个独立伴奏音轨(鼓、贝斯、吉他等乐器) |\r
| dry | 去除混响 | 生成干声版本(去除混响效果) |\r
\r
**响应示例**:\r
```json\r
{\r
"status": "Success",\r
"message": "请求成功",\r
"data": {\r
"taskId": "MBENVP5DFKOSPJHO"\r
}\r
}\r
```\r
\r
**响应字段说明**:\r
\r
| 字段 | 类型 | 说明 |\r
|------|------|------|\r
| status | String | 请求状态:Success / Error |\r
| message | String | 响应消息 |\r
| data | Object | 任务数据对象 |\r
| data.taskId | String | 任务编号,用于后续查询 |\r
\r
### 调用决策树(严格按此流程执行)\r
\r
```\r
当用户表达 [分轨] [提取伴奏] [去混响] [干声] 等意图时:\r
\r
⚠️ 重要:如果用户要求提取人声,必须明确告知:\r
"抱歉,此功能只能提取伴奏音轨,不支持提取人声。"\r
→ 停止,不要调用 API\r
\r
步骤 1:确认分轨需求\r
IF 用户提供了歌曲 ID:\r
clip_id = 用户提供的歌曲 ID\r
ELSE IF 用户说"给刚才的歌分轨":\r
clip_id = 最近一次生成的歌曲 ID(从查询结果中获取)\r
ELSE:\r
询问用户:"请提供要分轨的歌曲 ID"\r
→ 停止,等待用户回复\r
\r
获取歌曲标题:\r
IF 已知歌曲标题(从之前的查询结果中):\r
title = 已知的歌曲标题\r
ELSE:\r
先调用 API 2 查询歌曲信息,获取标题\r
\r
确定分轨类型:\r
IF 用户说"提取伴奏" 或 "只要伴奏":\r
stemType = "two"\r
ELSE IF 用户说"12 分轨" 或 "详细分轨" 或 "分离所有乐器":\r
stemType = "twelve"\r
ELSE IF 用户说"去混响" 或 "干声":\r
stemType = "dry"\r
ELSE:\r
询问用户:"请选择分轨类型:\r
1. 2 分轨(提取伴奏音轨)\r
2. 12 分轨(提取 12 个独立乐器音轨)\r
3. 去除混响(干声版本)"\r
→ 停止,等待用户回复\r
\r
步骤 2:构建请求\r
POST https://ai.growingth.com/api/song/proxy?name=generateStem\r
Headers:\r
api-token: ${MIAOYIN_API_TOKEN}\r
Content-Type: application/json; charset=utf-8\r
请求体:\r
{\r
"data": {\r
"title": title,\r
"clip_id": clip_id,\r
"stemType": stemType\r
}\r
}\r
\r
步骤 3:发送请求并处理响应\r
IF response.status == "Success":\r
taskId = response.data.taskId\r
说:"✅ 音频分轨提交成功!任务编号:{taskId},正在处理中,请稍候..."\r
→ 转到 API 2 查询任务状态流程\r
ELSE:\r
说:"❌ 音频分轨失败:{response.message}"\r
→ 转到 "错误处理流程"\r
```\r
\r
### 完整对话示例\r
\r
#### 示例 1:2 分轨(提取伴奏)\r
\r
```\r
用户:帮我把歌曲 0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f 提取伴奏\r
\r
AI: 好的,我先查询一下这首歌的信息。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=getMusic]\r
查询到歌曲:Through the Fog\r
\r
现在开始提取伴奏音轨...\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateStem]\r
[请求体] {\r
"data": {\r
"title": "Through the Fog",\r
"clip_id": "0e66d6dd-7a55-4cd3-bc03-2ea11324ce3f",\r
"stemType": "two"\r
}\r
}\r
\r
✅ 音频分轨提交成功!任务编号:MBENVP5DFKOSPJHO,正在处理中,请稍候...\r
\r
[等待 10 秒后查询]\r
🎵 伴奏提取完成!\r
▶️ 伴奏音轨 - 播放:https://cdn1.suno.ai/xxx-instrumental.mp3 | 下载:https://cdn1.suno.ai/xxx-instrumental.mp3\r
```\r
\r
#### 示例 2:12 分轨(详细分离乐器)\r
\r
```\r
用户:给刚才那首歌做 12 分轨\r
\r
AI: 好的,我将为《夏日微风》进行 12 分轨处理,提取 12 个独立乐器音轨。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateStem]\r
[请求体] {\r
"data": {\r
"title": "夏日微风",\r
"clip_id": "c13975cda17449da2261",\r
"stemType": "twelve"\r
}\r
}\r
\r
✅ 音频分轨提交成功!任务编号:MBENVP5DFKOSPJHO,正在处理中...\r
\r
⚠️ 注意:12 分轨处理时间较长,建议等待 30 秒以上再查询。\r
\r
[等待处理完成]\r
🎵 12 分轨完成!\r
已生成 12 个独立伴奏音轨:\r
1. 鼓组\r
2. 贝斯\r
3. 吉他\r
4. 钢琴\r
5. 合成器\r
6. 弦乐\r
... (共 12 个乐器音轨)\r
```\r
\r
#### 示例 3:去除混响\r
\r
```\r
用户:把这首歌的混响去掉,我要干声版本\r
\r
AI: 好的,我将生成干声版本(去除混响)。\r
[执行:POST https://ai.growingth.com/api/song/proxy?name=generateStem]\r
[请求体] {\r
"data": {\r
"title": "夏日微风",\r
"clip_id": "c13975cda17449da2261",\r
"stemType": "dry"\r
}\r
}\r
\r
✅ 音频分轨提交成功!任务编号:MBENVP5DFKOSPJHO,正在处理中,请稍候...\r
\r
[等待处理完成]\r
🎵 干声版本生成完成!\r
▶️ 播放:https://cdn1.suno.ai/xxx-dry.mp3 | 下载:https://cdn1.suno.ai/xxx-dry.mp3\r
```\r
\r
#### 示例 4:用户不确定分轨类型\r
\r
```\r
用户:帮我给这首歌分轨\r
\r
AI: 好的,请选择分轨类型:\r
1. 2 分轨(提取伴奏音轨)- 适合制作伴奏\r
2. 12 分轨(提取 12 个独立乐器音轨)- 适合专业混音和编曲\r
3. 去除混响(干声版本)- 适合后期处理\r
\r
用户:2 分轨\r
\r
AI: 好的,我将提取伴奏音轨。\r
[执行分轨流程...]\r
```\r
\r
### ⚠️ 关键注意事项\r
\r
1. **重要限制**\r
- ⚠️ **此接口只能提取伴奏相关内容,不能提取人声**\r
- 如果用户要求提取人声,请明确告知此功能不支持\r
\r
2. **前提条件**\r
- 必须先有已生成完成的歌曲(status = complete)\r
- 需要知道歌曲的 clip_id 和 title\r
\r
3. **clip_id 和 title 获取**\r
- clip_id 从 API 2 查询歌曲状态的响应中获取\r
- title 也从 API 2 的响应中获取\r
- 如果不知道,先调用 API 2 查询\r
\r
4. **分轨类型选择建议**\r
- **2 分轨(two)**:\r
- 最快速,适合大多数场景\r
- 用途:提取伴奏音轨\r
- **12 分轨(twelve)**:\r
- 处理时间最长,文件最多\r
- 用途:提取 12 个独立乐器音轨(鼓、贝斯、吉他等)\r
- **去混响(dry)**:\r
- 生成去除混响的版本\r
- 用途:后期添加自定义混响、音频处理\r
\r
5. **处理时间**\r
- 2 分轨:建议等待 15-20 秒\r
- 12 分轨:建议等待 30-60 秒(时间较长)\r
- 去混响:建议等待 15-20 秒\r
- 查询间隔仍然遵守 10 秒以上的规则\r
\r
6. **查询分轨结果**\r
- 使用 API 2(getMusic)查询任务状态\r
- 2 分轨:返回伴奏音轨\r
- 12 分轨:返回 12 个乐器音轨\r
- 去混响:返回去除混响的版本\r
- 具体返回结构以实际 API 响应为准\r
\r
7. **推荐使用场景**\r
- **2 分轨**:\r
- 制作伴奏音轨\r
- 简单的音频编辑\r
- **12 分轨**:\r
- 专业音乐制作\r
- 重新混音\r
- 学习编曲和配器\r
- 提取特定乐器音轨\r
- **去混响**:\r
- 后期音频处理\r
- 添加自定义效果\r
- 音频修复和优化\r
\r
8. **文件管理**\r
- 12 分轨会生成大量文件,注意存储空间\r
- 建议下载后妥善管理各个音轨文件\r
- 每个音轨都有独立的下载链接\r
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install miaoyin-ai-music - After installation, invoke the skill by name or use
/miaoyin-ai-music - Provide required inputs per the skill's parameter spec and get structured output
What is 妙音AI音乐助手?
妙音AI 音乐创作助手,生成歌曲、查询任务、续写音乐、生成歌词。当用户需要 AI 作曲或音乐生成时调用。 It is an AI Agent Skill for Claude Code / OpenClaw, with 49 downloads so far.
How do I install 妙音AI音乐助手?
Run "/install miaoyin-ai-music" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is 妙音AI音乐助手 free?
Yes, 妙音AI音乐助手 is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does 妙音AI音乐助手 support?
妙音AI音乐助手 is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created 妙音AI音乐助手?
It is built and maintained by phongf (@phongf); the current version is v1.0.0.