欢迎使用 Suno API
Suno API 基于先进的AI模型,为您提供全面的音乐生成和音频处理服务。无论您需要音乐创作、歌词生成、音频编辑还是人声分离,我们的API都能满足您的所有创意需求。身份验证
所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。请妥善保管您的 API 密钥,切勿公开分享。如果怀疑密钥泄露,请立即重置。
API 基础 URL
复制
https://api.sunoapi.org
身份验证请求头
复制
Authorization: Bearer YOUR_API_KEY
快速开始指南
第一步:生成您的第一首歌曲
从一个简单的音乐生成请求开始:复制
curl -X POST "https://api.sunoapi.org/api/v1/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "一首宁静的原声吉他旋律配柔和人声,民谣风格",
"customMode": false,
"instrumental": false,
"model": "V4_5ALL",
"callBackUrl": "https://your-server.com/callback"
}'
第二步:检查任务状态
使用返回的任务ID检查生成状态:复制
curl -X GET "https://api.sunoapi.org/api/v1/generate/record-info?taskId=YOUR_TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
响应格式
成功响应:复制
{
"code": 200,
"msg": "success",
"data": {
"taskId": "suno_task_abc123"
}
}
复制
{
"code": 200,
"msg": "success",
"data": {
"taskId": "suno_task_abc123",
"status": "SUCCESS",
"response": {
"data": [
{
"id": "audio_123",
"audio_url": "https://example.com/generated-music.mp3",
"title": "生成的歌曲",
"tags": "民谣, 原声",
"duration": 180.5
}
]
}
}
}
核心功能
音乐生成
从文本描述创建完整歌曲:复制
{
"prompt": "一首充满活力的电子舞曲,带有合成器主音",
"customMode": true,
"style": "电子舞曲",
"title": "数字梦境",
"instrumental": false,
"model": "V4_5"
}
歌词创作
独立生成AI驱动的歌词:复制
{
"prompt": "一首关于克服挑战和找到内在力量的歌曲",
"callBackUrl": "https://your-server.com/lyrics-callback"
}
音频扩展
扩展现有音乐轨道:复制
{
"audioId": "e231****-****-****-****-****8cadc7dc",
"defaultParamFlag": true,
"prompt": "继续添加吉他独奏",
"continueAt": 120,
"model": "V4_5ALL"
}
上传翻唱
用新风格转换现有音频:复制
{
"uploadUrl": "https://example.com/original-audio.mp3",
"customMode": true,
"style": "爵士",
"title": "爵士版本",
"prompt": "转换为流畅的爵士风格"
}
模型版本
为您的需求选择合适的模型:V4
高质量最佳音频质量和精细的歌曲结构,最长4分钟
V4_5
高级卓越的流派融合和智能提示,最长8分钟
V4_5PLUS
更丰富音色音色更丰富,新的创作方式,最长8分钟
V4_5ALL
更好的结构V4.5-all 更好的歌曲结构,最长8分钟
V5
生成更快更卓越的音乐表现力,速度更快,最长8分钟
关键参数
音乐生成的文本描述。提供详细、具体的描述以获得更好的结果。根据模型的字符限制:
- V4:最多 3000 字符
- V4_5、V4_5PLUS、V4_5ALL、V5:最多 5000 字符
- 描述音乐风格和流派
- 包含情绪和氛围
- 指定乐器和人声
- 添加节拍和能量描述
要使用的模型版本:
V4- 最佳音频质量,最长4分钟V4_5- 高级功能,最长8分钟V4_5PLUS- 更丰富音色,最长8分钟V4_5ALL- V4.5-all 更好的歌曲结构,最长8分钟V5- 生成速度更快,更卓越音乐表现力,最长8分钟
启用自定义参数模式以进行高级控制。当为
true 时,需要额外的参数如 style 和 title。生成无人声的纯音乐。默认为
false。音乐风格或流派(自定义模式下必需)。示例:“爵士”、“摇滚”、“古典”、“电子”根据模型的字符限制:
- V4:最多 200 字符
- V4_5、V4_5PLUS、V4_5ALL、V5:最多 1000 字符
歌曲标题(自定义模式下必需)。根据模型的字符限制:
- V4 和 V4_5ALL:最多 80 字符
- V4_5、V4_5PLUS、V5:最多 100 字符
接收完成通知的URL。详见回调文档。
完整工作流程示例
以下是完整的音乐生成和处理示例:- JavaScript
- Python
复制
class SunoAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://api.sunoapi.org/api/v1';
}
async generateMusic(options) {
const response = await fetch(`${this.baseUrl}/generate`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(options)
});
const result = await response.json();
if (result.code !== 200) {
throw new Error(`生成失败: ${result.msg}`);
}
return result.data.taskId;
}
async generateLyrics(prompt) {
const response = await fetch(`${this.baseUrl}/lyrics`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt,
callBackUrl: 'https://your-server.com/lyrics-callback'
})
});
const result = await response.json();
return result.data.taskId;
}
async waitForCompletion(taskId, maxWaitTime = 600000) { // 最长等待10分钟
const startTime = Date.now();
while (Date.now() - startTime < maxWaitTime) {
const status = await this.getTaskStatus(taskId);
if (status.status === 'SUCCESS') {
return status.response;
} else if (status.status === 'FAILED') {
throw new Error(`生成失败: ${status.errorMessage}`);
}
// 等待30秒后再次检查
await new Promise(resolve => setTimeout(resolve, 30000));
}
throw new Error('生成超时');
}
async getTaskStatus(taskId) {
const response = await fetch(`${this.baseUrl}/generate/record-info?taskId=${taskId}`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`
}
});
const result = await response.json();
return result.data;
}
async extendMusic(audioId, options) {
const response = await fetch(`${this.baseUrl}/generate/extend`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
audioId,
...options
})
});
const result = await response.json();
return result.data.taskId;
}
async separateVocals(taskId, audioId) {
const response = await fetch(`${this.baseUrl}/vocal-removal/generate`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
taskId,
audioId,
callBackUrl: 'https://your-server.com/vocal-callback'
})
});
const result = await response.json();
return result.data.taskId;
}
async getRemainingCredits() {
const response = await fetch(`${this.baseUrl}/get-credits`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`
}
});
const result = await response.json();
return result.data.credits;
}
}
// 使用示例
async function main() {
const api = new SunoAPI('YOUR_API_KEY');
try {
// 检查剩余积分
const credits = await api.getRemainingCredits();
console.log(`剩余积分: ${credits}`);
// 首先生成歌词
console.log('正在生成歌词...');
const lyricsTaskId = await api.generateLyrics(
'一首关于冒险和发现的歌曲,振奋人心且鼓舞人心'
);
const lyricsResult = await api.waitForCompletion(lyricsTaskId);
console.log('歌词已生成:', lyricsResult.data[0].text);
// 使用自定义参数生成音乐
console.log('正在生成音乐...');
const musicTaskId = await api.generateMusic({
prompt: lyricsResult.data[0].text,
customMode: true,
style: '民谣流行',
title: '冒险之歌',
instrumental: false,
model: 'V4_5',
callBackUrl: 'https://your-server.com/music-callback'
});
// 等待完成
const musicResult = await api.waitForCompletion(musicTaskId);
console.log('音乐生成成功!');
musicResult.data.forEach((track, index) => {
console.log(`音轨 ${index + 1}:`);
console.log(` 标题: ${track.title}`);
console.log(` 时长: ${track.duration}秒`);
console.log(` 音频URL: ${track.audio_url}`);
});
// 扩展第一个音轨
const originalTrack = musicResult.data[0];
console.log('正在扩展音乐...');
const extendTaskId = await api.extendMusic(originalTrack.id, {
defaultParamFlag: true,
prompt: '继续添加美妙的器乐尾奏',
continueAt: originalTrack.duration - 30, // 从结束前30秒开始扩展
model: 'V4_5'
});
const extendedResult = await api.waitForCompletion(extendTaskId);
console.log('扩展版本已创建:', extendedResult.data[0].audio_url);
// 分离人声
console.log('正在分离人声...');
const separationTaskId = await api.separateVocals(musicTaskId, originalTrack.id);
const separationResult = await api.waitForCompletion(separationTaskId);
console.log('人声分离完成:');
console.log(` 伴奏: ${separationResult.vocal_removal_info.instrumental_url}`);
console.log(` 纯人声: ${separationResult.vocal_removal_info.vocal_url}`);
} catch (error) {
console.error('错误:', error.message);
}
}
main();
复制
import requests
import time
class SunoAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://api.sunoapi.org/api/v1'
self.headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
def generate_music(self, **options):
response = requests.post(f'{self.base_url}/generate',
headers=self.headers, json=options)
result = response.json()
if result['code'] != 200:
raise Exception(f"生成失败: {result['msg']}")
return result['data']['taskId']
def generate_lyrics(self, prompt):
response = requests.post(f'{self.base_url}/lyrics',
headers=self.headers,
json={
'prompt': prompt,
'callBackUrl': 'https://your-server.com/lyrics-callback'
})
result = response.json()
return result['data']['taskId']
def wait_for_completion(self, task_id, max_wait_time=600):
start_time = time.time()
while time.time() - start_time < max_wait_time:
status = self.get_task_status(task_id)
if status['status'] == 'SUCCESS':
return status['response']
elif status['status'] == 'FAILED':
raise Exception(f"生成失败: {status.get('errorMessage')}")
time.sleep(30) # 等待30秒
raise Exception('生成超时')
def get_task_status(self, task_id):
response = requests.get(f'{self.base_url}/generate/record-info?taskId={task_id}',
headers={'Authorization': f'Bearer {self.api_key}'})
return response.json()['data']
def extend_music(self, audio_id, **options):
response = requests.post(f'{self.base_url}/generate/extend',
headers=self.headers,
json={'audioId': audio_id, **options})
return response.json()['data']['taskId']
def separate_vocals(self, task_id, audio_id):
response = requests.post(f'{self.base_url}/vocal-removal/generate',
headers=self.headers,
json={
'taskId': task_id,
'audioId': audio_id,
'callBackUrl': 'https://your-server.com/vocal-callback'
})
return response.json()['data']['taskId']
def get_remaining_credits(self):
response = requests.get(f'{self.base_url}/get-credits',
headers={'Authorization': f'Bearer {self.api_key}'})
return response.json()['data']['credits']
# 使用示例
def main():
api = SunoAPI('YOUR_API_KEY')
try:
# 检查剩余积分
credits = api.get_remaining_credits()
print(f'剩余积分: {credits}')
# 首先生成歌词
print('正在生成歌词...')
lyrics_task_id = api.generate_lyrics(
'一首关于冒险和发现的歌曲,振奋人心且鼓舞人心'
)
lyrics_result = api.wait_for_completion(lyrics_task_id)
print('歌词已生成:', lyrics_result['data'][0]['text'])
# 使用自定义参数生成音乐
print('正在生成音乐...')
music_task_id = api.generate_music(
prompt=lyrics_result['data'][0]['text'],
customMode=True,
style='民谣流行',
title='冒险之歌',
instrumental=False,
model='V4_5',
callBackUrl='https://your-server.com/music-callback'
)
# 等待完成
music_result = api.wait_for_completion(music_task_id)
print('音乐生成成功!')
for i, track in enumerate(music_result['data']):
print(f'音轨 {i + 1}:')
print(f' 标题: {track["title"]}')
print(f' 时长: {track["duration"]}秒')
print(f' 音频URL: {track["audio_url"]}')
# 扩展第一个音轨
original_track = music_result['data'][0]
print('正在扩展音乐...')
extend_task_id = api.extend_music(
original_track['id'],
defaultParamFlag=True,
prompt='继续添加美妙的器乐尾奏',
continueAt=original_track['duration'] - 30,
model='V4_5'
)
extended_result = api.wait_for_completion(extend_task_id)
print('扩展版本已创建:', extended_result['data'][0]['audio_url'])
# 分离人声
print('正在分离人声...')
separation_task_id = api.separate_vocals(music_task_id, original_track['id'])
separation_result = api.wait_for_completion(separation_task_id)
print('人声分离完成:')
vocal_info = separation_result['vocal_removal_info']
print(f' 伴奏: {vocal_info["instrumental_url"]}')
print(f' 纯人声: {vocal_info["vocal_url"]}')
except Exception as error:
print(f'错误: {error}')
if __name__ == '__main__':
main()
高级功能
上传并扩展
上传您自己的音频并用AI扩展:复制
const extendTaskId = await api.generateMusic({
uploadUrl: 'https://example.com/my-song.mp3',
defaultParamFlag: true,
prompt: '添加摇滚吉他独奏部分',
continueAt: 60,
model: 'V4_5'
});
音频格式转换
将音乐转换为高质量WAV格式:复制
const wavTaskId = await api.convertToWav({
taskId: 'original_task_id',
audioId: 'e231****-****-****-****-****8cadc7dc',
callBackUrl: 'https://your-server.com/wav-callback'
});
音乐视频生成
创建可视化音乐视频:复制
const videoTaskId = await api.createMusicVideo({
taskId: 'music_task_id',
audioId: 'e231****-****-****-****-****8cadc7dc',
author: '艺术家姓名',
domainName: 'your-brand.com',
callBackUrl: 'https://your-server.com/video-callback'
});
使用回调
设置webhook回调以获得自动通知:复制
// 您的回调端点
app.post('/music-callback', (req, res) => {
const { code, data } = req.body;
if (code === 200) {
console.log('音乐准备就绪:', data.data);
data.data.forEach(track => {
console.log(`标题: ${track.title}`);
console.log(`音频: ${track.audio_url}`);
});
} else {
console.log('生成失败:', req.body.msg);
}
res.status(200).json({ status: 'received' });
});
了解更多关于回调
设置webhook回调以在您的音乐准备就绪时接收自动通知。
任务状态说明
任务正在处理中
任务成功完成
任务未能完成
任务正在排队等待处理
最佳实践
提示词优化
提示词优化
- 使用详细、具体的音乐风格和情绪描述
- 包含乐器规格和人声要求
- 指定节拍、能量水平和歌曲结构
- 避免冲突或过于复杂的描述
模型选择
模型选择
- 选择V4获得标准长度的最高音频质量
- 选择V4_5获得高级功能和更长的音轨
- V4_5PLUS提供更丰富的音色和新的创作方式
- 使用V4_5ALL获得更好的歌曲结构(最长8分钟)
- V5生成速度更快,更卓越的音乐表现力
- 考虑您的具体用例和质量要求
性能优化
性能优化
- 使用回调而不是频繁轮询
- 为失败的请求实施适当的重试逻辑
- 监控您的积分使用情况并相应规划
- 缓存结果以避免重新生成相似内容
错误处理
错误处理
- 为瞬时故障实施适当的重试逻辑
- 监控任务状态并处理超时场景
- 在发出请求前验证输入参数
- 记录错误以便调试和监控
文件存储和访问
生成的音频文件在自动删除前存储 15天。下载URL可能有有限的有效期。
- 音频文件在生成后15天内保持可访问
- 下载并保存重要文件到您自己的存储
- 如需要,在过期后使用API重新生成内容
- 考虑为关键内容实施本地备份策略
下一步
支持
需要帮助吗?我们的技术支持团队随时为您提供帮助。
- 邮箱: [email protected]
- 文档: docs.sunoapi.org
- API状态: 查看我们的状态页面了解实时API健康状况
准备开始创建令人惊叹的AI音乐了吗?获取您的API密钥,立即开始创作!
