Replace a section
curl --request POST \
--url https://apistable.com/api/v1/tasks/create_task \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "suno_replace_section",
"input": {
"audio_id": "YOUR_AUDIO_ID",
"prompt": "[Verse] A new beginning",
"tags": "Pop",
"title": "New verse",
"infill_start_s": 20,
"infill_end_s": 40,
"full_lyrics": "Original full lyrics"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'suno_replace_section',
input: {
audio_id: 'YOUR_AUDIO_ID',
prompt: '[Verse] A new beginning',
tags: 'Pop',
title: 'New verse',
infill_start_s: 20,
infill_end_s: 40,
full_lyrics: 'Original full lyrics'
}
})
};
fetch('https://apistable.com/api/v1/tasks/create_task', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://apistable.com/api/v1/tasks/create_task"
payload = {
"model": "suno_replace_section",
"input": {
"audio_id": "YOUR_AUDIO_ID",
"prompt": "[Verse] A new beginning",
"tags": "Pop",
"title": "New verse",
"infill_start_s": 20,
"infill_end_s": 40,
"full_lyrics": "Original full lyrics"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"code": 200,
"msg": "success",
"data": {
"task_id": "<string>"
}
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}接口参考
替换片段
指定歌曲中的一段时间，用新歌词或风格重写这一段。
POST
/
api
/
v1
/
tasks
/
create_task
Replace a section
curl --request POST \
--url https://apistable.com/api/v1/tasks/create_task \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "suno_replace_section",
"input": {
"audio_id": "YOUR_AUDIO_ID",
"prompt": "[Verse] A new beginning",
"tags": "Pop",
"title": "New verse",
"infill_start_s": 20,
"infill_end_s": 40,
"full_lyrics": "Original full lyrics"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'suno_replace_section',
input: {
audio_id: 'YOUR_AUDIO_ID',
prompt: '[Verse] A new beginning',
tags: 'Pop',
title: 'New verse',
infill_start_s: 20,
infill_end_s: 40,
full_lyrics: 'Original full lyrics'
}
})
};
fetch('https://apistable.com/api/v1/tasks/create_task', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://apistable.com/api/v1/tasks/create_task"
payload = {
"model": "suno_replace_section",
"input": {
"audio_id": "YOUR_AUDIO_ID",
"prompt": "[Verse] A new beginning",
"tags": "Pop",
"title": "New verse",
"infill_start_s": 20,
"infill_end_s": 40,
"full_lyrics": "Original full lyrics"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"code": 200,
"msg": "success",
"data": {
"task_id": "<string>"
}
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。
调用步骤
指定歌曲中的一段时间，用新歌词或风格重写这一段。-
- 按下方示例准备输入，将占位地址和 ID 换成你有权使用的资源。
-
- 将 model 设为 suno_replace_section，参数放在 input 内。提交一次并保存返回的 task_id。
-
- 查询已保存的任务，或接收回调。任务仍在处理中时继续等待，不重新提交同一操作。
- 从 result.data.data 读取作品。每首歌曲都有独立的本站 id，后续任务可将其作为 audio_id。
创建任务
一次操作只有一个执行项，后台记录供应商、账号、各阶段上游任务和输出映射。所有公开 ID 均为本站 ID。当前未启用音乐积分扣除。{
"model": "suno_replace_section",
"input": {
"audio_id": "YOUR_AUDIO_ID",
"prompt": "[Verse] A new beginning",
"tags": "Pop",
"title": "New verse",
"infill_start_s": 20,
"infill_end_s": 40,
"full_lyrics": "Original full lyrics"
}
}
参数速查
| 字段 | 类型 | 必填 | 说明与限制 |
|---|---|---|---|
| vocal_gender | string | 否 / 依条件 | m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。 values: m, f |
| style_weight | number | 否 / 依条件 | 风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 |
| weirdness_constraint | number | 否 / 依条件 | 创意约束，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 |
| audio_weight | number | 否 / 依条件 | 音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。 min: 0; max: 1 |
| variety | integer | 否 / 依条件 | 多样性，0–4 整数，自定义生成默认 1。 min: 0; max: 4 |
| persona_id | string | 否 / 依条件 | 本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。 maxLength: 200 |
| persona_model | string | 否 / 依条件 | style_persona 或 voice_persona，须与资源真实来源匹配。 values: style_persona, voice_persona |
| audio_id | string | 是 | 本站歌曲 ID；服务端通过主键关联校验账户、选中执行与上游歌曲。翻唱/续写不传源 task_id 或外部 upload_url。 maxLength: 200 |
| prompt | string | 是 | 简单描述最多 3000 字符；自定义模式歌词最多 5000 字符，lyrics 优先于 prompt。 maxLength: 5000 |
| tags | string | 是 | 此操作的音乐风格，最多 1000 字符。 maxLength: 1000 |
| title | string | 是 | 标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。 maxLength: 100 |
| infill_start_s | number | 是 | 替换开始位置（秒），最多两位小数。 min: 0 |
| infill_end_s | number | 是 | 替换结束位置。至少替换 10 秒且不超过原曲时长的一半；超过 120 秒的 PayAPI 组合暂未开放。 min: 0 |
| full_lyrics | string | 是 | 包含替换段落并放在正确位置的完整歌词。 maxLength: 5000 |
| lyrics | string | 否 / 依条件 | 歌词，最多 5000 字符；同时支持 prompt 时以 lyrics 为准。 maxLength: 5000 |
| negative_tags | string | 否 / 依条件 | 排除的风格；增加伴奏或人声时必填。 maxLength: 1000 |
| result_mode | string | 否 / 依条件 | 续写/替换：full_song（默认）或 segment；加轨：mixed（默认）或 stem；完整/混合结果等待合并完成。 values: full_song, segment; default: full_song |
输入与限制
下方 Schema 包含全部支持字段、必填项、枚举、范围和默认值；未知参数会被拒绝。URL 参数仅接受公开 HTTPS 地址，不接受文件对象。{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"vocal_gender": {
"type": "string",
"enum": [
"m",
"f"
],
"description": "m or f. A vocal tendency, not a guaranteed voice identity. Custom generation only."
},
"style_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Style influence, 0–1 with at most two decimal places. Custom generation only."
},
"weirdness_constraint": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Creativity constraint, 0–1 with at most two decimal places. Custom generation only."
},
"audio_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Audio influence, 0–1 with at most two decimal places. Generation requires custom, non-instrumental mode."
},
"variety": {
"type": "integer",
"minimum": 0,
"maximum": 4,
"description": "Variety: integer 0–4, default 1 in custom generation."
},
"persona_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "APIstable Voice or Persona ID; provider root and artist mapping remain server-side."
},
"persona_model": {
"type": "string",
"enum": [
"style_persona",
"voice_persona"
],
"description": "style_persona or voice_persona; must match the resource's actual origin."
},
"audio_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "APIstable song ID. Server resolves ownership, selected attempt and supplier clip using primary-key joins. No source task_id or external upload_url is accepted for cover/extend."
},
"prompt": {
"type": "string",
"maxLength": 5000,
"description": "Simple description: up to 3000 characters. In custom mode, lyrics takes precedence over prompt (up to 5000)."
},
"tags": {
"type": "string",
"maxLength": 1000,
"description": "Musical style for this operation, up to 1000 characters."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Title. Generate/cover: up to 80 characters; extend and other operations: up to 100. Required for custom generation."
},
"infill_start_s": {
"type": "number",
"minimum": 0,
"description": "Replacement start in seconds, at most two decimal places."
},
"infill_end_s": {
"type": "number",
"minimum": 0,
"description": "Replacement end. Replace at least 10 seconds and at most half the source duration. PayAPI ranges above 120 seconds are not enabled."
},
"full_lyrics": {
"type": "string",
"maxLength": 5000,
"description": "Full song lyrics with the replacement in its intended position."
},
"lyrics": {
"type": "string",
"maxLength": 5000,
"description": "Lyrics, up to 5000 characters; takes precedence over prompt where both are accepted."
},
"negative_tags": {
"type": "string",
"maxLength": 1000,
"description": "Styles to exclude; required for adding instrumental backing or vocals."
},
"result_mode": {
"default": "full_song",
"type": "string",
"enum": [
"full_song",
"segment"
],
"description": "Extension/replacement: full_song (default) or segment. Added stem: mixed (default) or stem. Full/mixed results wait for assembly."
}
},
"required": [
"audio_id",
"prompt",
"tags",
"title",
"infill_start_s",
"infill_end_s",
"full_lyrics"
],
"additionalProperties": false
}
重要条件
- 歌曲音频按供应商真实格式返回，可能是 MP3 或 M4A，不将 M4A 冒充 MP3。需要 MP3 时使用 suno_export_mp3；可选封面无法获取时返回 null，不影响音频使用。
- 完整歌曲续写/替换与混合加轨需要等待合并；合并失败不会将片段冒充整曲；双曲部分成功会在结果消息中注明。
- PayAPI 差异：超过 120 秒的替换、歌曲声音 Persona 翻唱/续写和 Persona 替换组合待验证；原生单轨抽取目前开放文档明确的 Piano。
- 上传文件 24 小时，生成文件 14 天，任务详情 30 天。MP3 复用不延长原文件有效期；有效 Voice 的最小身份映射不会随任务日志清理。
输出
创建响应为 {code:200,msg:“success”,data:{task_id}}，轮询 GET /api/v1/tasks/{task_id}。成功时 data.result 为符合下方 Schema 的对象，其他状态为 null；input 仍为 JSON 字符串。{
"type": "object",
"required": [
"code",
"msg",
"data"
],
"properties": {
"code": {
"const": 200
},
"msg": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"callbackType",
"task_id",
"data"
],
"properties": {
"callbackType": {
"const": "complete"
},
"task_id": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"audio_url",
"stream_audio_url",
"image_url",
"prompt",
"lyrics",
"model_name",
"title",
"createTime",
"duration",
"tags",
"source_audio_url",
"source_image_url",
"source_stream_audio_url"
],
"properties": {
"id": {
"type": "string"
},
"audio_url": {
"type": "string"
},
"stream_audio_url": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"prompt": {
"type": "string"
},
"lyrics": {
"type": [
"string",
"null"
]
},
"model_name": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"createTime": {
"type": [
"integer",
"null"
]
},
"duration": {
"type": [
"number",
"null"
]
},
"tags": {
"type": [
"string",
"null"
]
},
"source_audio_url": {
"type": "string"
},
"source_image_url": {
"type": [
"string",
"null"
]
},
"source_stream_audio_url": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
}
}
相关流程
Voice 完整四步 文件上传 回调授权
Every valid key can submit and query its own account. Revoked keys are rejected.
请求体
application/json