欢迎使用 Suno API
Suno API 基于先进的AI模型,为您提供全面的音乐生成和音频处理服务。无论您需要音乐创作、歌词生成、音频编辑还是人声分离,我们的API都能满足您的所有创意需求。
身份验证
所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥,切勿公开分享。如果怀疑密钥泄露,请立即重置。
API 基础 URL
身份验证请求头
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": "V3_5",
"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": "V3_5"
}
上传翻唱
用新风格转换现有音频:
{
"uploadUrl": "https://example.com/original-audio.mp3",
"customMode": true,
"style": "爵士",
"title": "爵士版本",
"prompt": "转换为流畅的爵士风格"
}
模型版本
为您的需求选择合适的模型:
V4
高质量最佳音频质量和精细的歌曲结构,最长4分钟
关键参数
音乐生成的文本描述。提供详细、具体的描述以获得更好的结果。提示词技巧:
- 描述音乐风格和流派
- 包含情绪和氛围
- 指定乐器和人声
- 添加节拍和能量描述
要使用的模型版本:
V3_5
- 创意多样性,最长4分钟
V4
- 最佳音频质量,最长4分钟
V4_5
- 高级功能,最长8分钟
启用自定义参数模式以进行高级控制。当为 true
时,需要额外的参数如 style
和 title
。
音乐风格或流派(自定义模式下必需)。示例:“爵士”、“摇滚”、“古典”、“电子”
完整工作流程示例
以下是完整的音乐生成和处理示例:
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();
高级功能
上传并扩展
上传您自己的音频并用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回调以在您的音乐准备就绪时接收自动通知。
任务状态说明
最佳实践
- 使用详细、具体的音乐风格和情绪描述
- 包含乐器规格和人声要求
- 指定节拍、能量水平和歌曲结构
- 避免冲突或过于复杂的描述
- 使用V3_5进行创意和实验性音乐
- 选择V4获得标准长度的最高音频质量
- 选择V4_5获得高级功能和更长的音轨
- 考虑您的具体用例和质量要求
- 使用回调而不是频繁轮询
- 为失败的请求实施适当的重试逻辑
- 监控您的积分使用情况并相应规划
- 缓存结果以避免重新生成相似内容
- 为瞬时故障实施适当的重试逻辑
- 监控任务状态并处理超时场景
- 在发出请求前验证输入参数
- 记录错误以便调试和监控
文件存储和访问
生成的音频文件在自动删除前存储 15天。下载URL可能有有限的有效期。
- 音频文件在生成后15天内保持可访问
- 下载并保存重要文件到您自己的存储
- 如需要,在过期后使用API重新生成内容
- 考虑为关键内容实施本地备份策略
下一步
准备开始创建令人惊叹的AI音乐了吗?获取您的API密钥,立即开始创作!