> ## 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 音乐轨道创建续写内容，以扩展或修改已有音乐。
### 重要说明
* 此端点需要提供有效的 `suno_id`，用于引用现有的 Suno 音乐。如果你需要上传音频进行扩展，请参考：[上传音频扩展](/zh/suno-api/extend-music-upload)。
* 支持两种扩展模式：`simple` 和 `custom`
* 在 `simple` 模式下，其他可选参数将继承自原始 `suno_id`
* 在 `custom` 模式下，必须提供 `continue_at`、`title`、`tags` 和 `prompt`
如果你只是对现有曲目进行少量修改，建议优先使用 `mode=simple`。
### 扩展音乐（Simple 模式）
使用已有歌曲的 `suno_id` 扩展 Suno 音乐。可选参数将继承自原始歌曲。
```json simple extend theme={null} theme={null}
{
"model": "suno/music-extend",
"callback_url": "",
"input": {
"suno_id": "suno_abc123",
"mode": "simple",
"model": "v5"
}
}
```
```json simple extend with continue_at theme={null} theme={null}
{
"model": "suno/music-extend",
"callback_url": "",
"input": {
"suno_id": "suno_abc123",
"mode": "simple",
"model": "v5",
"continue_at": 30
}
}
```
### 扩展音乐（Custom 模式）
自定义扩展允许你控制续写位置和生成内容。你必须指定 `continue_at`、`title`、`tags` 和 `prompt`。
```json custom extend theme={null} theme={null}
{
"model": "suno/music-extend",
"callback_url": "",
"input": {
"suno_id": "suno_abc123",
"mode": "custom",
"model": "v5",
"continue_at": 30,
"title": "Midnight Addiction (Extended)",
"tags": "Western R&B, female vocal, dark, sensual",
"prompt": "保持相同的暗黑 R&B 氛围，并扩展新的桥段和结尾部分。",
"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/extend-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-extend
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- suno/music-extend
description: |-
用于生成的模型名称。必填字段。
- 此接口必须使用 `suno/music-extend`
callback_url:
type: string
format: uri
description: |-
可选。用于接收任务完成通知的回调 URL。
- 当生成完成后，系统会向该 URL 发送任务状态和结果
- 回调数据结构与任务状态查询接口返回的 `data` 对象一致
- 你的回调接口应支持接收包含 JSON 数据的 POST 请求
- 成功接收后需返回 HTTP 200 状态码
example: https://your-domain.com/api/callback
input:
$ref: '#/components/schemas/SunoMusicExtendInput'
example:
model: suno/music-extend
callback_url: https://your-domain.com/api/callback
input:
suno_id: suno_abc123
mode: custom
model: v5
continue_at: 30
title: Midnight Addiction (Extended)
tags: Western R&B, female vocal, dark, sensual
prompt: >-
Keep the same dark R&B mood and extend with a new bridge and
outro.
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:
SunoMusicExtendInput:
type: object
description: >-
Suno 音乐扩展的输入参数。
规则：
- `suno_id` 为必填项，且必须引用现有的 Suno 歌曲。
- `mode=simple`：其他可选字段将继承自原始 `suno_id`。
- `mode=custom`：必须提供 `continue_at`、`title`、`tags` 和 `prompt`。
- `model=v4`：`tags` 最大长度为 200，`prompt` 最大长度为 3000；其他模型：`tags` 最大长度为
1000，`prompt` 最大长度为 5000。
properties:
suno_id:
type: string
description: 需要扩展的 Suno 歌曲 ID。
example: suno_abc123
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**：v4.5+ 提供更丰富的音质、全新的创作方式，最长支持 8 分钟。
- **v4.5**：支持更智能的提示词与更快的生成速度，最长支持 8 分钟。
- **v4.5all**：支持更智能的提示词与更快的生成速度，最长支持 8 分钟。
- **v4**：提升人声质量，最长支持 4 分钟。
example: v5
continue_at:
type: integer
minimum: 1
description: 从第几秒开始扩展（必须大于 0）。在 `custom` 模式下为必填项。
example: 30
title:
type: string
maxLength: 80
description: 音乐标题。在 `custom` 模式下为必填项。
example: Midnight Addiction (Extended)
prompt:
type: string
maxLength: 5000
description: 描述音乐应如何继续或变化。在 `custom` 模式下为必填项。对于 `v4` 模型最大长度为 3000，其他模型为 5000。
example: 保持相同的暗黑 R&B 氛围，并扩展新的桥段和结尾部分。
tags:
type: string
maxLength: 1000
description: 音乐风格标签。在 `custom` 模式下为必填项。对于 `v4` 模型最大长度为 200，其他模型为 1000。
example: Western R&B, female vocal, dark, sensual
negative_tags:
type: string
maxLength: 1000
description: 需要排除的音乐风格。
example: metal, aggressive, harsh vocals
vocal_gender:
type: string
enum:
- m
- f
description: 人声性别偏好：`m` 表示男声，`f` 表示女声。
example: f
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 模型对应的 Persona ID。可通过 [Suno Persona
Generate](/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:
- suno_id
- mode
- model
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/zh/user-api-key) 获取你的 API Key
使用方式：
在请求头中添加：
x-api-key: YOUR_API_KEY
注意：
- 请妥善保管你的 API Key，不要泄露给他人
- 如果怀疑 API Key 已泄露，请立即在管理页面中重置
````