> ## 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. # 替换音乐分区 > 替换现有音乐的指定时间段。 ### 使用指南 * 此接口可以替换已生成音乐中的特定时间段 * 需要提供原始音乐的任务ID和要替换的时间范围，或用户上传的音频URL和模型版本 * 替换后的音频会与原音乐自然融合 ### 两种操作模式 **模式 1：使用已有音频** * 提供 `taskId` 和 `audioId` 来替换已生成音乐中的指定分区 **模式 2：使用用户上传音频** * 提供 `uploadUrl` 和 `model` 来使用您自己上传的音频进行分区替换 ### 参数详情 * **通用必需参数**： * `prompt`：替换后的歌词 * `tags`：音乐风格标签 * `title`：音乐标题 * `infillStartS`：开始替换的时间点（秒，保留2位小数） * `infillEndS`：结束替换的时间点（秒，保留2位小数） * `fullLyrics`：修改后的完整歌词，包含修改和未修改歌词的合并 * **模式 1 必需参数**： * `taskId`：原始音乐的父任务ID * `audioId`：要替换的音频ID（生成完成后的回调数据中返回） * **模式 2 必需参数**： * `uploadUrl`：用户上传的自定义音频URL * `model`：AI模型版本（V4、V4\_5、V4\_5PLUS、V4\_5ALL、V5、V5\_5） * **可选参数**： * `negativeTags`：要排除的音乐风格 * `callBackUrl`：任务完成后的回调URL ### 时间范围说明 * `infillStartS` 必须小于 `infillEndS` * 时间值精确到小数点后2位，例如：10.50秒 * 替换时间范围必须在 **6 秒到 60 秒** 之间 * 替换时长建议不超过原音乐总时长的50% ### 开发者注意事项 * 替换片段会根据提供的 `prompt` 和 `tags` 重新生成 * 生成的替换片段会自动与原音乐前后部分融合 * 生成的文件将保留 **14 天** * 查询任务状态使用与生成音乐相同的接口：[获取音乐详情](./get-music-generation-details) ## OpenAPI ````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/replace-section 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/replace-section: post: tags: - Music Generation summary: 替换音乐分区 description: |- 替换现有音乐的指定时间段。 此接口可以替换已生成音乐中的特定时间段，需要提供原始音乐的任务 ID 和要替换的时间范围，替换后的音频会与原音乐自然融合。 ### 时间范围说明 - `infillStartS` 必须小于 `infillEndS` - 时间值精确到小数点后 2 位，例如：10.50 秒 - 替换时间范围必须在 **6 秒到 60 秒** 之间 - 替换时长建议不超过原音乐总时长的 50% ### 开发者注意事项 - 替换片段会根据提供的 `prompt` 和 `tags` 重新生成 - 生成的替换片段会自动与原音乐前后部分融合 - 生成的文件将保留 **14 天** - 查询任务状态使用与生成音乐相同的接口：[获取音乐详情](/cn/suno-api/get-music-generation-details) operationId: replace-section requestBody: required: true content: application/json: schema: type: object required: - prompt - tags - title - infillStartS - infillEndS - fullLyrics oneOf: - title: 使用已有音频进行分区替换 required: - taskId - audioId type: object properties: taskId: type: string description: 原始任务ID（父任务），用于标识要进行分区替换的源音乐。 example: 2fac****9f72 audioId: type: string description: 要替换的音频曲目的唯一标识符。此ID在音乐生成完成后的回调数据中返回。 example: e231****-****-****-****-****8cadc7dc - title: 使用用户上传音频进行分区替换 required: - uploadUrl - model type: object properties: uploadUrl: type: string format: uri description: 用户上传的自定义音频URL。 example: https://example.com/audio.mp3 model: type: string description: |- 用于生成的AI模型版本。 - 可用选项： - **`V5_5`**：量身定制的专属模型，贴合您的独特品味。 - **`V5`**：更卓越的音乐表现力，生成速度更快。 - **`V4_5PLUS`**：V4.5+ 的音色更丰富，新的创作方式，最长8分钟。 - **`V4_5`**：V4.5 更智能的提示词，更快的生成速度，最长8分钟。 - **`V4_5ALL`**：V4.5ALL 更智能的提示词，更快的生成速度，最长8分钟。 - **`V4`**：V4 改进的人声质量，最长4分钟。 enum: - V4 - V4_5 - V4_5PLUS - V4_5ALL - V5 - V5_5 example: V4 properties: prompt: type: string description: 替换后的歌词 example: A calm and relaxing piano track. tags: type: string description: 音乐的风格标签，如爵士、电子等 example: Jazz title: type: string description: 音乐的标题 example: Relaxing Piano negativeTags: type: string description: 排除的音乐风格，用于避免特定风格元素出现在替换片段中 example: Rock infillStartS: type: number description: >- 开始替换的时间点（秒），保留2位小数。必须小于 infillEndS，且 infillEndS 与 infillStartS 的时间差必须在 6 秒到 60 秒之间。 minimum: 0 example: 10.5 infillEndS: type: number description: >- 结束替换的时间点（秒），保留2位小数。必须大于 infillStartS，且 infillEndS 与 infillStartS 的时间差必须在 6 秒到 60 秒之间。 minimum: 0 example: 20.75 fullLyrics: type: string description: 修改后的完整歌词，包含修改和未修改歌词的合并。此参数包含在分区替换后整首歌曲将使用的完整歌词文本。 example: |- [主歌1] 原始歌词内容 [副歌] 此部分的修改歌词 [主歌2] 更多原始歌词 callBackUrl: type: string format: uri description: 生成任务完成后的回调URL。系统将在替换完成时向此URL发送POST请求，包含任务状态和结果。 example: https://example.com/callback example: taskId: 2fac****9f72 audioId: e231****-****-****-****-****8cadc7dc prompt: A calm and relaxing piano track. tags: Jazz title: Relaxing Piano negativeTags: Rock infillStartS: 10.5 infillEndS: 20.75 fullLyrics: |- [主歌1] 原始歌词内容 [副歌] 此部分的修改歌词 [主歌2] 更多原始歌词 callBackUrl: https://example.com/callback responses: '200': description: 请求成功 content: application/json: schema: type: object properties: code: type: integer enum: - 200 - 401 - 402 - 404 - 409 - 422 - 429 - 451 - 455 - 500 description: |- 响应状态码 - **200**: 成功 - 请求已成功处理 - **401**: 未授权 - 身份验证凭据缺失或无效 - **402**: 积分不足 - 账户没有足够的积分执行此操作 - **404**: 未找到 - 请求的资源或端点不存在 - **409**: 冲突 - WAV记录已存在 - **422**: 验证错误 - 请求参数未通过验证检查 - **429**: 超出限制 - 已超过对此资源的请求限制 - **451**: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。 - **455**: 服务不可用 - 系统当前正在进行维护 - **500**: 服务器错误 - 处理请求时发生意外错误 msg: type: string description: 当 code != 200 时的错误信息 example: success data: type: object properties: taskId: type: string description: >- 任务ID，用于追踪任务状态。可使用此ID通过 [获取音乐详情](/cn/suno-api/get-music-generation-details) 接口查询任务详情和结果。 example: 5c79****be8e security: - BearerAuth: [] components: 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 泄露，请立即在管理页面重置 ````