> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Suno API：翻唱音乐
> 将音乐曲目翻唱为新风格，同时保留原有核心旋律。该功能集成了 Suno 的上传功能，预期效果是在原旋律不变的基础上生成全新风格的曲目。
### 重要说明
* 需要提供指向已上传音频文件的 `audio_url`
* 对于已有音乐，Suno 可能会上传失败
* 支持两种模式：`simple`（简单）和 `custom`（自定义）
* `simple` 模式下，`prompt` 为必填项
* `custom` 模式下，`title` 和 `tags` 为必填项；若 `instrumental=false`，则 `lyrics` 也为必填项
如需基于上传音频快速生成翻唱，建议从 `mode=simple` 开始使用。
### 音乐翻唱（简单模式）
通过简短的提示词对上传的音乐进行翻唱。
```json 简单翻唱 theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "simple",
"model": "v5",
"instrumental": false,
"prompt": "Create a cover with a softer, more intimate vocal delivery."
}
}
```
```json 纯音乐翻唱 theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "simple",
"model": "v5",
"instrumental": true,
"prompt": "Instrumental cover with warm piano and gentle ambience."
}
}
```
### 音乐翻唱（自定义模式）
自定义翻唱支持对风格和歌词进行精细控制。需提供 `title`、`tags` 及 `lyrics`（纯音乐模式除外）。
```json 自定义翻唱 theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "custom",
"model": "v5",
"instrumental": false,
"title": "Midnight Addiction (Cover)",
"tags": "Western R&B, female vocal, dark, sensual",
"lyrics": "[Verse 1]\nI still taste your words in the dark...",
"vocal_gender": "f",
"style_weight": 0.85,
"audio_weight": 0.6,
"weirdness_constraint": 0.2,
"negative_tags": "metal, aggressive"
}
}
```
### 获取任务结果
提交任务后，使用统一查询端点查看进度并获取结果：
了解如何查询 Suno 任务状态及获取生成结果
## OpenAPI
````yaml zh/suno-api/cover-music.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
title: Crun Suno 翻唱音乐 API
description: crun.ai Suno 翻唱音乐 API 文档
version: 1.0.0
contact:
name: 技术支持
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务器
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/CreateTask:
post:
summary: 基于上传音频的 Suno 翻唱音乐
operationId: suno/music-cover
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- suno/music-cover
description: |-
用于生成的模型名称，必填字段。
- 使用本端点时必须填写 `suno/music-cover`
callback_url:
type: string
format: uri
description: |-
可选。用于接收任务完成通知的回调 URL。
- 生成完成后，系统将以 POST 方式向该 URL 推送任务状态与结果
- 回调数据结构与任务状态查询接口返回的 `data` 对象一致
- 您的回调端点需支持接收包含结果的 JSON 格式 POST 请求
- 成功接收后需返回 HTTP 200 状态码
example: https://your-domain.com/api/callback
input:
$ref: '#/components/schemas/SunoMusicCoverInput'
example:
model: suno/music-cover
callback_url: https://your-domain.com/api/callback
input:
audio_url: https://example.com/uploaded-audio.mp3
mode: custom
model: v5
instrumental: false
title: Midnight Addiction (Cover)
tags: Western R&B, female vocal, dark, sensual
lyrics: |-
[Verse 1]
I still taste your words in the dark...
vocal_gender: f
style_weight: 0.85
audio_weight: 0.6
weirdness_constraint: 0.2
negative_tags: metal, aggressive
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，可通过获取任务详情接口查询任务状态
example: task_12345678
example:
code: 200
message: success
data:
task_id: task_12345678
'422':
description: 验证错误
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: 详细的验证错误信息
items:
type: string
example:
- specific error field message
example:
code: 422
message: Missing Params or Type Error
errors:
- specific error field message
'500':
$ref: '#/components/responses/Error'
components:
schemas:
SunoMusicCoverInput:
type: object
description: |-
基于上传音频文件进行翻唱的输入参数。
规则：
- `audio_url` 为必填项，须指向已上传的音频文件。
- `mode=simple`：`prompt` 为必填项。
- `mode=custom`：`title` 和 `tags` 为必填项。
- `mode=custom` 且 `instrumental=false`：`lyrics` 为必填项。
- `model=v4`：`tags` 最大长度为 200，`lyrics` 最大长度为 3000。
properties:
audio_url:
type: string
format: uri
description: 参考音乐文件的 URL。请确保上传的音频时长不超过 8 分钟。
example: https://example.com/reference-music.mp3
mode:
type: string
enum:
- simple
- custom
description: 音乐生成模式。
example: simple
model:
type: string
enum:
- v5.5
- v5
- v4.5plus
- v4.5
- v4.5all
- v4
description: |-
Suno 音乐模型版本。
- **v5.5**：专为匹配您的独特品味而定制的模型。
- **v5**：更卓越的音乐表现力，生成速度更快。
- **v4.5plus**：音效更丰富，创作方式更多样，最长支持 8 分钟。
- **v4.5**：支持更智能的提示词，生成速度更快，最长支持 8 分钟。
- **v4.5all**：支持更智能的提示词，生成速度更快，最长支持 8 分钟。
- **v4**：提升人声质量，最长支持 4 分钟。
example: v5
instrumental:
type: boolean
description: 是否仅生成纯音乐（无歌词）。
example: false
title:
type: string
maxLength: 100
description: 音乐标题。`custom` 模式下必填。
example: Midnight Addiction (Cover)
prompt:
type: string
maxLength: 500
description: '`simple` 模式下用于引导音乐生成的文字提示词，当 mode 为 `simple` 时必填。'
example: Create a cover with a softer, more intimate vocal delivery.
lyrics:
type: string
maxLength: 5000
description: >-
自定义模式下的歌词。当 mode 为 `custom` 且 `instrumental` 为 `false` 时必填。`v4`
模型最大长度为 3000，其他模型为 5000。
example: |-
[Verse 1]
I still taste your words in the dark...
tags:
type: string
maxLength: 1000
description: 音乐风格标签。`custom` 模式下必填。`v4` 模型最大长度为 200，其他模型为 1000。
example: Western R&B, female vocal, dark, sensual, slow tempo
vocal_gender:
type: string
enum:
- m
- f
description: 人声性别偏好：`m` 为男声，`f` 为女声。仅在 `custom` 模式下有效。
example: f
negative_tags:
type: string
maxLength: 1000
description: 需要排除的音乐风格。
example: metal, aggressive, harsh vocals
style_weight:
type: number
minimum: 0
maximum: 1
description: 风格参考强度，取值范围 0.0 至 1.0。
example: 0.85
audio_weight:
type: number
minimum: 0
maximum: 1
description: 音频特征与其他因素的平衡权重，取值范围 0.0 至 1.0。
example: 0.6
weirdness_constraint:
type: number
minimum: 0
maximum: 1
description: 控制实验性/创意偏差程度，取值范围 0.0 至 1.0。
example: 0.2
persona_id:
type: string
description: >-
所选 Persona 模型的 ID。可通过 [Suno Persona
生成](/zh/suno-api/suno-persona-generate) 创建。
example: persona_123456
persona_model:
type: string
enum:
- style_persona
- voice_persona
description: |-
Persona 模型类型。与 `persona_id` 配合使用以应用已保存的 Persona。
- **style_persona**：应用以风格为主的 Persona 特征。
- **voice_persona**：应用以音色为主的 Persona 特征（仅支持 v5 模型）。
default: style_persona
example: style_persona
required:
- audio_url
- mode
- model
- instrumental
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
description: |-
响应状态码
- **200**: 成功 - 请求已成功处理
- **401**: 未授权 - 身份凭证缺失或无效
- **402**: 额度不足 - 账户余额不足以完成本次操作
- **404**: 未找到 - 请求的资源或端点不存在
- **422**: 验证错误 - 请求参数未通过验证
- **429**: 请求限速 - 该资源的请求次数已超出限制
- **455**: 服务不可用 - 系统正在维护中
- **500**: 服务器错误 - 处理请求时发生意外错误
- **501**: 生成失败 - 内容生成任务失败
- **505**: 功能已禁用 - 所请求的功能当前已被禁用
message:
type: string
description: 响应消息，失败时为错误描述
example: success
responses:
Error:
description: 服务器错误
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: |-
所有 API 均需通过 API Key 进行身份验证。
获取 API Key：
1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取您的 API Key
使用方式：
将以下内容添加至请求头：
x-api-key: YOUR_API_KEY
注意事项：
- 请妥善保管您的 API Key，切勿与他人共享
- 若怀疑 API Key 已泄露，请立即在管理页面进行重置
````