> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt > Use this file to discover all available pages before exploring further. # 上传并扩展音乐 > 此 API 在保留音频轨道原始样式的同时扩展了音轨。它包括 Suno 的上传功能，允许用户上传音频文件进行处理。预期的结果是更长的音轨，无缝地延续输入的风格。 ### 参数使用指南 * 当 defaultParamFlag 为 true（自定义参数）时： * 如果 instrumental 为 true：需要提供 style 、 title和uploadUrl * 如果 instrumental 为 false：需要提供 style、prompt 、 title和uploadUrl * prompt 根据模型的长度限制： * **V4**：最大 3000 字符 * **V4\_5、V4\_5PLUS、V4\_5ALL、V5 和 V5\_5**：最大 5000 字符 * style 根据模型的长度限制： * **V4**：最大 200 字符 * **V4\_5、V4\_5PLUS、V4\_5ALL、V5 和 V5\_5**：最大 1000 字符 * title 根据模型的长度限制： * **V4 和 V4\_5ALL**：最大 80 字符 * **V4\_5、V4\_5PLUS、V5 和 V5\_5**：最大 100 字符 * continueAt 音频开始扩展的秒数（该参数需大于0,且小于所上传视频的时长） * uploadUrl 用于指定音频文件的上传位置;确保上传的音频长度不超过 8 分钟。 * **重要提示**：使用 **V4\_5ALL** 模型时，上传的音频文件长度不得超过 **1 分钟**。 * 当 defaultParamFlag 为 false（使用默认参数）时： * 无论 instrumental 设置如何，仅需提供 uploadUrl和prompt * 其他参数将使用原音频的参数 ### 可选参数 * personaId（string）：使用自定义参数时可传入 Persona ID 或 Suno Voice 生成的 `voiceId`。如果使用 Voice 生成的 ID，`personaModel` 必须设置为 `voice_persona`。 * personaModel（string）：Persona 类型。生成 Persona 接口返回的 ID 使用 `style_persona`，Suno Voice 生成的 ID 使用 `voice_persona`。 ### 开发者注意事项 1. 生成的文件将保留14天 2. 模型版本必须与源音乐保持一致 3. **V4\_5ALL 模型上传限制**：使用 V4\_5ALL 模型时，上传的音频文件长度不得超过 **1 分钟**。 4. 此功能非常适合通过延长现有音乐创作更长的作品 5. uploadUrl 参数用于指定音频文件的上传位置;请提供有效的 URL。 ## OpenAPI ````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/upload-extend openapi: 3.0.0 info: title: intro description: 这是生成音频的API接口文档 version: 1.0.0 contact: name: 技术支持 email: support@sunoapi.org servers: - url: https://api.sunoapi.org 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: 用于账户和积分管理的接口 paths: /api/v1/generate/upload-extend: post: summary: 上传并扩展音乐 operationId: upload-and-extend-audio requestBody: required: true content: application/json: schema: type: object required: - defaultParamFlag - callBackUrl - model - uploadUrl properties: uploadUrl: type: string format: uri description: >- 用于上传音频文件的 URL，无论 defaultParamFlag 是 true 还是 false，都是必需的。确保上传的音频长度不超过 8 分钟。 example: https://api.example.com/upload defaultParamFlag: type: boolean description: >- 启用自定义模式进行高级音频生成设置。 - 设为 `true` 使用自定义参数模式（需要提供 `style` 、 `title`和`uploadUrl`；如果 `instrumental` 为 `false`，则需要提供 `uploadUrl`和`prompt`）。如果 `instrumental` 为 `false`，提示词将严格用作歌词。 - 设为 `false` 使用非自定义模式（只需要提供 `uploadUrl`）。歌词将根据提示词自动生成。 example: true instrumental: type: boolean description: >- 决定音频是否为纯音乐（无歌词）。 - 在自定义参数模式下（`defaultParamFlag: true`）： - 如果为 `true`：只需提供 `style` 、 `title`和`uploadUrl`。 - 如果为 `false`：需要提供 `style`、`title` 、 `prompt`（`prompt` 将作为精确歌词使用）和`uploadUrl`。 - 在非自定义参数模式下（`defaultParamFlag: false`）：不影响必填字段（只需 `uploadUrl`）。如果为 `false`，将自动生成歌词。 example: true prompt: type: string description: |- 描述音乐应如何延长。当 defaultParamFlag 为 true 时必填。根据模型的字符限制： - **V4**：最大 3000 字符 - **V4_5、V4_5PLUS、V4_5ALL、V5 和 V5_5**：最大 5000 字符 example: 用更多舒缓的音符延长音乐 style: type: string description: |- 音乐风格，例如爵士、古典、电子等。根据模型的字符限制： - **V4**：最大 200 字符 - **V4_5、V4_5PLUS、V4_5ALL、V5 和 V5_5**：最大 1000 字符 example: 古典 title: type: string description: |- 音乐标题。根据模型的字符限制： - **V4 和 V4_5ALL**：最大 80 字符 - **V4_5、V4_5PLUS、V5 和 V5_5**：最大 100 字符 example: 宁静钢琴延长版 continueAt: type: number description: |- 音频开始扩展的时间点（以秒为单位）。 - 当 `defaultParamFlag` 为 `true` 时必填。 - 取值范围：大于0且小于上传音频的总时长。 - 指定从原始音频的哪个时间点开始进行扩展。 example: 60 personaId: type: string description: >- 仅在开启自定义参数时可用。应用到生成音乐的 Persona ID，可选。你可以传入以下两类 ID： - 通过 [生成 Persona](https://docs.sunoapi.org/cn/suno-api/generate-persona) 接口生成的 Persona ID。此时可使用 `personaModel: style_persona`，或省略 `personaModel` 使用默认值。 - 通过 [Suno Voice](https://docs.sunoapi.org/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: 使用的模型版本，必须与源音频保持一致 enum: - V4 - V4_5 - V4_5PLUS - V4_5ALL - V5 - V5_5 example: V4_5ALL negativeTags: type: string description: 需要在生成中排除的音乐风格 example: 舒缓钢琴 vocalGender: type: string description: 期望的人声性别（可选） enum: - m - f example: m styleWeight: type: number description: 风格指引权重，范围 0.00–1.00 minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 weirdnessConstraint: type: number description: 创意发散/奇异度约束，范围 0.00–1.00 minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 audioWeight: type: number description: 输入音频影响力权重（如适用），范围 0.00–1.00 minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 callBackUrl: type: string format: uri description: >- 在音乐延长完成时接收任务完成通知的URL。 - 详细的回调格式和实现指南，请参见 [上传并扩展音频回调](https://docs.sunoapi.org/cn/suno-api/upload-and-extend-audio-callbacks) - 或者，您也可以使用获取音乐生成详情接口来轮询任务状态 example: https://api.example.com/callback 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: 音频唯一标识（audioId） 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://sunoapi.org/api-key) 获取您的 API Key ## 使用方式 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` > **⚠️ 注意：** > - 请妥善保管您的 API Key，不要泄露给他人 > - 如果怀疑 API Key 泄露，请立即在管理页面重置 ````