跳转到主要内容
POST
/
api
/
v1
/
generate
/
replace-section
替换音乐分区
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/replace-section \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'
import requests

url = "https://api.sunoapi.org/api/v1/generate/replace-section"

payload = {
"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"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};

fetch('https://api.sunoapi.org/api/v1/generate/replace-section', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sunoapi.org/api/v1/generate/replace-section",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.sunoapi.org/api/v1/generate/replace-section"

payload := strings.NewReader("{\n \"taskId\": \"2fac****9f72\",\n \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n \"prompt\": \"A calm and relaxing piano track.\",\n \"tags\": \"Jazz\",\n \"title\": \"Relaxing Piano\",\n \"negativeTags\": \"Rock\",\n \"infillStartS\": 10.5,\n \"infillEndS\": 20.75,\n \"fullLyrics\": \"[主歌1]\\n原始歌词内容\\n[副歌]\\n此部分的修改歌词\\n[主歌2]\\n更多原始歌词\",\n \"callBackUrl\": \"https://example.com/callback\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.sunoapi.org/api/v1/generate/replace-section")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taskId\": \"2fac****9f72\",\n \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n \"prompt\": \"A calm and relaxing piano track.\",\n \"tags\": \"Jazz\",\n \"title\": \"Relaxing Piano\",\n \"negativeTags\": \"Rock\",\n \"infillStartS\": 10.5,\n \"infillEndS\": 20.75,\n \"fullLyrics\": \"[主歌1]\\n原始歌词内容\\n[副歌]\\n此部分的修改歌词\\n[主歌2]\\n更多原始歌词\",\n \"callBackUrl\": \"https://example.com/callback\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.sunoapi.org/api/v1/generate/replace-section")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taskId\": \"2fac****9f72\",\n \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n \"prompt\": \"A calm and relaxing piano track.\",\n \"tags\": \"Jazz\",\n \"title\": \"Relaxing Piano\",\n \"negativeTags\": \"Rock\",\n \"infillStartS\": 10.5,\n \"infillEndS\": 20.75,\n \"fullLyrics\": \"[主歌1]\\n原始歌词内容\\n[副歌]\\n此部分的修改歌词\\n[主歌2]\\n更多原始歌词\",\n \"callBackUrl\": \"https://example.com/callback\"\n}"

response = http.request(request)
puts response.read_body
{
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

使用指南

  • 此接口可以替换已生成音乐中的特定时间段
  • 需要提供原始音乐的任务ID和要替换的时间范围,或用户上传的音频URL和模型版本
  • 替换后的音频会与原音乐自然融合

两种操作模式

模式 1:使用已有音频
  • 提供 taskIdaudioId 来替换已生成音乐中的指定分区
模式 2:使用用户上传音频
  • 提供 uploadUrlmodel 来使用您自己上传的音频进行分区替换

参数详情

  • 通用必需参数
    • 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%

开发者注意事项

  • 替换片段会根据提供的 prompttags 重新生成
  • 生成的替换片段会自动与原音乐前后部分融合
  • 生成的文件将保留 14 天
  • 查询任务状态使用与生成音乐相同的接口:获取音乐详情

授权

Authorization
string
header
必填

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

  1. 访问 API Key 管理页面 获取您的 API Key

使用方式

在请求头中添加:

Authorization: Bearer YOUR_API_KEY

⚠️ 注意:

  • 请妥善保管您的 API Key,不要泄露给他人
  • 如果怀疑 API Key 泄露,请立即在管理页面重置

请求体

application/json
taskId
string
必填

原始任务ID(父任务),用于标识要进行分区替换的源音乐。

示例:

"2fac****9f72"

audioId
string
必填

要替换的音频曲目的唯一标识符。此ID在音乐生成完成后的回调数据中返回。

示例:

"e231****-****-****-****-****8cadc7dc"

prompt
string
必填

替换后的歌词

示例:

"A calm and relaxing piano track."

tags
string
必填

音乐的风格标签,如爵士、电子等

示例:

"Jazz"

title
string
必填

音乐的标题

示例:

"Relaxing Piano"

infillStartS
number
必填

开始替换的时间点(秒),保留2位小数。必须小于 infillEndS,且 infillEndS 与 infillStartS 的时间差必须在 6 秒到 60 秒之间。

必填范围: x >= 0
示例:

10.5

infillEndS
number
必填

结束替换的时间点(秒),保留2位小数。必须大于 infillStartS,且 infillEndS 与 infillStartS 的时间差必须在 6 秒到 60 秒之间。

必填范围: x >= 0
示例:

20.75

fullLyrics
string
必填

修改后的完整歌词,包含修改和未修改歌词的合并。此参数包含在分区替换后整首歌曲将使用的完整歌词文本。

示例:

"[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词"

negativeTags
string

排除的音乐风格,用于避免特定风格元素出现在替换片段中

示例:

"Rock"

callBackUrl
string<uri>

生成任务完成后的回调URL。系统将在替换完成时向此URL发送POST请求,包含任务状态和结果。

示例:

"https://example.com/callback"

响应

200 - application/json

请求成功

code
enum<integer>

响应状态码

  • 200: 成功 - 请求已成功处理
  • 401: 未授权 - 身份验证凭据缺失或无效
  • 402: 积分不足 - 账户没有足够的积分执行此操作
  • 404: 未找到 - 请求的资源或端点不存在
  • 409: 冲突 - WAV记录已存在
  • 422: 验证错误 - 请求参数未通过验证检查
  • 429: 超出限制 - 已超过对此资源的请求限制
  • 451: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。
  • 455: 服务不可用 - 系统当前正在进行维护
  • 500: 服务器错误 - 处理请求时发生意外错误
可用选项:
200,
401,
402,
404,
409,
422,
429,
451,
455,
500
msg
string

当 code != 200 时的错误信息

示例:

"success"

data
object