> ## 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.
# 替换音乐分区
> 替换现有音乐的指定时间段。
### 参数使用指南
此端点支持两种指定源音频的模式：
**模式一：使用已有音频进行分区替换**
* 需要提供 `taskId` 和 `audioId`
* 不能提供 `uploadUrl` 和 `model`
**模式二：使用用户上传音频进行分区替换**
* 需要提供 `uploadUrl` 和 `model`
* 不能提供 `taskId` 和 `audioId`
### 公共必需参数
* **prompt**（string，必填）：替换后的歌词
* **tags**（string，必填）：音乐的风格标签，如爵士、电子等
* **title**（string，必填）：音乐的标题
* **infillStartS**（number，必填）：开始替换的时间点（秒，保留2位小数）
* **infillEndS**（number，必填）：结束替换的时间点（秒，保留2位小数）
* **fullLyrics**（string，必填）：修改后的完整歌词，包含修改和未修改歌词的合并
### 可选参数
以下字段为可选控制项：
* negativeTags（string）：排除的音乐风格，用于避免特定风格元素出现在替换片段中
* callBackUrl（string）：生成任务完成后的回调URL。详细回调格式请参见 [替换音乐分区回调](/cn/suno-api/replace-section-callbacks)。
### 时间范围说明
* `infillStartS` 必须小于 `infillEndS`
* 时间值精确到小数点后 2 位，例如：`10.50` 秒
* 替换时间范围必须在 **6 秒到 60 秒** 之间
* 替换时长建议不超过原音乐总时长的 **50%**
```json 使用已有音频替换 theme={null}
{
"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]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
```
```json 使用上传音频替换 theme={null}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V4",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
```
### 开发者注意事项
1. 替换片段会根据提供的 `prompt` 和 `tags` 重新生成
2. 生成的替换片段会自动与原音乐前后部分融合
3. 生成的文件将保留 **14 天**
4. 查询任务状态使用与生成音乐相同的接口：[获取音乐详情](/cn/suno-api/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@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/replace-section:
post:
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
properties:
taskId:
type: string
description: 原始任务ID（父任务），用于标识要进行分区替换的源音乐。
example: 2fac****9f72
audioId:
type: string
description: 要替换的音频曲目的唯一标识符。此ID在音乐生成完成后的回调数据中返回。
example: e231****-****-****-****-****8cadc7dc
- title: 使用用户上传音频进行分区替换
required:
- uploadUrl
- model
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请求，包含任务状态和结果。
- 您的回调端点应能接受包含替换结果的JSON载荷的POST请求
- 详细的回调格式和实现指南，请参见
[替换音乐分区回调](/cn/suno-api/replace-section-callbacks)
- 或者，您也可以使用获取音乐详情接口来轮询任务状态
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:
allOf:
- 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
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: 任务ID，用于追踪任务状态。可使用此ID通过 "获取音乐详情" 接口查询任务详情和结果。
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: |-
当音频生成完成时，系统会调用此回调通知结果。
### 回调示例
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "e231****-****-****-****-****8cadc7dc",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"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
},
{
"id": "bd15****1873",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"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": 228.28
}
]
}
}
```
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
stream_audio_url:
type: string
description: 流式音频URL
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: 回调接收成功
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: |-
响应状态码
- **200**: 成功 - 请求已成功处理
- **400**: 验证错误 - 歌词包含受版权保护的内容。
- **408**: 超出限制 - 超时。
- **413**: 冲突 - 上传的音频与现有艺术作品匹配。
- **500**: 服务器错误 - 处理请求时发生意外错误
- **501**: 音频生成失败。
- **531**: 服务器错误 - 抱歉，由于问题生成失败。您的积分已退还。请重试。
msg:
type: string
description: 当 code != 200 时的错误信息
example: success
example:
code: 200
msg: success
method: post
type: path
path: '{request.body#/callBackUrl}'
components:
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 泄露，请立即在管理页面重置
````