> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.
# 延长音乐
> 延长或修改现有音乐作品。
### 参数使用指南
* **model**（string，必填）：`V4_5ALL`、`V4`、`V4_5`、`V4_5PLUS`、`V5`、`V5_5`。**`V5_5`**：释放你的声音：定制模型，贴合你的独特品味 — 与 **`V5`** 的自定义参数字数上限一致。
* 当 defaultParamFlag 为 true（自定义参数）时：
* 需要提供 `prompt`、`style`、`title` 和 `continueAt`
* 按模型的字符限制：
* **V4**：`prompt` 最多 3000，`style` 最多 200，`title` 最多 80
* **V4\_5ALL**：`prompt` 最多 5000，`style` 最多 1000，`title` 最多 80
* **V4\_5、V4\_5PLUS、V5、V5\_5**：`prompt` 最多 5000，`style` 最多 1000，`title` 最多 100
* 当 defaultParamFlag 为 false（使用默认参数）时：
* 业务参数仅需 `audioId`；接口仍**必填** **`model`** 与 **`callBackUrl`**
* 其余创作相关字段沿用原音频参数
### 可选参数
以下字段为可选控制项：
* vocalGender（string）：偏好人声性别。允许值：`m`（男）、`f`（女）
* styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
* weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
* audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
* personaId（string）：使用自定义参数时可传入 Persona ID 或 Suno Voice 生成的 `voiceId`。如果使用 Voice 生成的 ID，`personaModel` 必须设置为 `voice_persona`。
* personaModel（string）：Persona 类型。生成 Persona 接口返回的 ID 使用 `style_persona`，Suno Voice 生成的 ID 使用 `voice_persona`。
```json 请求示例 theme={null}
{
"defaultParamFlag": true,
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "加入更柔和的桥段并延长结尾",
"style": "Indie Pop",
"title": "Evening Sky (Extended)",
"continueAt": 60,
"model": "V4_5ALL",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
```
### 开发者注意事项
1. 生成的文件将保留15天
2. 模型版本必须与源音乐保持一致
3. 此功能非常适合通过延长现有音乐创作更长的作品
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/extend
openapi: 3.0.0
info:
title: intro
description: 这是生成音频的API接口文档
version: 1.0.0
contact:
name: 技术支持
email: support@api.box
servers:
- url: https://apibox.erweima.ai
description: API 服务器
security:
- BearerAuth: []
tags:
- name: Music Generation
description: 用于创建和管理音乐生成任务的接口
- name: Lyrics Generation
description: 用于歌词生成和管理的接口
- name: WAV Conversion
description: 用于将音乐转换为WAV格式的接口
- name: Vocal Removal
description: 用于从音乐轨道中移除人声的接口
- name: Music Video Generation
description: 用于生成MP4视频的接口
- name: Account Management
description: 用于账户和积分管理的接口
- name: Audio Enhancement
description: 用于增强和修改现有音频的伴奏和人声元素的接口
paths:
/api/v1/generate/extend:
post:
summary: 延长音乐
operationId: extend-music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- defaultParamFlag
- audioId
- callBackUrl
- model
properties:
defaultParamFlag:
type: boolean
description: >-
控制参数使用模式。
- `true`：使用自定义参数（需要提供 `continueAt`、`prompt`、`style` 和
`title`）。
- `false`：使用原始音频参数（只需提供 `audioId`）。
example: true
audioId:
type: string
description: 要延长的音轨的音频ID。这是将要继续的源音轨。
example: e231****-****-****-****-****8cadc7dc
prompt:
type: string
description: 描述音乐应如何延长。当 defaultParamFlag 为 true 时必填。
example: 用更多舒缓的音符延长音乐
style:
type: string
description: 音乐风格，例如爵士、古典、电子等
example: 古典
title:
type: string
description: 音乐标题
example: 宁静钢琴延长版
continueAt:
type: number
description: |-
音频开始扩展的时间点（以秒为单位）。
- 当 `defaultParamFlag` 为 `true` 时必填。
- 取值范围：大于0且小于该生成音频的总时长。
- 指定从原始音频的哪个时间点开始进行扩展。
example: 60
personaId:
type: string
description: >-
仅在开启自定义参数时可用。应用到生成音乐的 Persona ID，可选。你可以传入以下两类 ID：
- 通过 [生成
Persona](https://docs.api.box/cn/suno-api/generate-persona)
接口生成的 Persona ID。此时可使用 `personaModel: style_persona`，或省略
`personaModel` 使用默认值。
- 通过 [Suno
Voice](https://docs.api.box/cn/suno-api/suno-voice-generate)
流程生成的 `voiceId`。当使用 Voice 生成的 ID 时，必须设置 `personaModel:
voice_persona`。
example: persona_123
personaModel:
type: string
description: >-
使用 `personaId` 时应用的 Persona 模型类型，可选。
- `style_persona`（默认）：用于生成 Persona 接口返回的 Persona ID。
- `voice_persona`：当 `personaId` 使用 Suno Voice 生成的 `voiceId`
时必须选择该值。该选项仅在 V5 与 V5_5 模型下可用。
enum:
- style_persona
- voice_persona
default: style_persona
example: style_persona
model:
type: string
description: |-
用于生成的AI模型版本。
- 所有请求都必填。
- 可用选项：
- **`V5`**：更卓越的音乐表现力，生成速度更快。
- **`V5_5`**：释放你的声音：定制模型，贴合你的独特品味。与 **V5** 的自定义模式下 `prompt`、`style` 字数上限一致（5000 / 1000）。
- **`V4_5PLUS`**：V4.5+ 音色更丰富，新的创作方式，最长8分钟。
- **`V4_5`**：V4.5 更智能的提示词，更快的生成速度，最长8分钟。
- **`V4`**：V4 改进的人声质量，最长4分钟。
- **`V4_5ALL`**：V4.5-all 更好的歌曲结构，最长8分钟。
enum:
- V4_5ALL
- V4
- V4_5
- V4_5PLUS
- V5
- V5_5
example: V4_5ALL
negativeTags:
type: string
description: 需要在生成中排除的音乐风格
example: 舒缓钢琴
callBackUrl:
type: string
format: uri
description: >-
在音乐延长完成时接收任务完成通知的URL。
- 详细的回调格式和实现指南，请参见
[音乐延长回调](https://docs.api.box/cn/suno-api/extend-music-callbacks)
- 或者，您也可以使用获取音乐生成详情接口来轮询任务状态
example: https://api.example.com/callback
vocalGender:
type: string
description: 偏好人声性别。可选。允许值：'m'（男）、'f'（女）
enum:
- m
- f
example: m
styleWeight:
type: number
description: 风格贴合权重。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: 创造性/新颖度约束。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: 音频一致性与其他控制项的相对权重。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: 任务ID，用于后续查询任务状态
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioExtend:
'{$request.body#/callBackUrl}':
post:
description: |-
当音频生成完成时，系统会调用此回调通知结果。
### 回调示例
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "8551****662c",
"audio_url": "https://example.cn/****.mp3",
"source_audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"source_stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"source_image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] 夜晚城市 灯火辉煌",
"model_name": "chirp-v3-5",
"title": "钢铁侠",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 状态码
example: 200
msg:
type: string
description: 返回消息
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
回调类型：text（文本生成完成）、first（第一首生成完成）、complete（全部生成完成）
enum:
- text
- first
- complete
task_id:
type: string
description: 任务ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: 音频唯一标识
audio_url:
type: string
description: 音频文件URL
source_audio_url:
type: string
description: 原始音频文件URL
stream_audio_url:
type: string
description: 流式音频URL
source_stream_audio_url:
type: string
description: 原始流式音频URL
image_url:
type: string
description: 封面图片URL
source_image_url:
type: string
description: 原始封面图片URL
prompt:
type: string
description: 生成提示词/歌词
model_name:
type: string
description: 使用的模型名称
title:
type: string
description: 音乐标题
tags:
type: string
description: 音乐标签
createTime:
type: string
description: 创建时间
format: date-time
duration:
type: number
description: 音频时长（秒）
responses:
'200':
description: 回调接收成功
method: post
type: path
path: '{$request.body#/callBackUrl}'
components:
schemas:
ApiResponse:
type: object
properties:
code:
type: integer
description: |-
# 状态码说明
- ✅ 200 - 请求成功
- ⚠️ 400 - 参数错误
- ⚠️ 401 - 没有访问权限
- ⚠️ 404 - 请求方式或者路径错误
- ⚠️ 405 - 调用超过限制
- ⚠️ 413 - 主题或者prompt过长
- ⚠️ 429 - 积分不足
- ⚠️ 430 - 您的调用频率过高。请稍后再试。
- ⚠️ 455 - 网站维护
- ❌ 500 - 服务器异常
example: 200
enum:
- 200
- 400
- 401
- 404
- 405
- 413
- 429
- 430
- 455
- 500
msg:
type: string
description: 当 code != 200 时，展示错误信息
example: success
responses:
Error:
description: 服务器异常
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: |-
# 🔑 API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
## 获取 API Key
1. 访问 [API Key 管理页面](https://api.box/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **⚠️ 注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````