欢迎使用 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": "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": "existing_audio_123",
  "defaultParamFlag": true,
  "prompt": "继续添加吉他独奏",
  "continueAt": 120,
  "model": "V3_5"
}

上传翻唱

用新风格转换现有音频:
{
  "uploadUrl": "https://example.com/original-audio.mp3",
  "customMode": true,
  "style": "爵士",
  "title": "爵士版本",
  "prompt": "转换为流畅的爵士风格"
}

模型版本

为您的需求选择合适的模型:

V3_5

平衡型创意多样性的扎实编排,最长4分钟

V4

高质量最佳音频质量和精细的歌曲结构,最长4分钟

V4_5

高级卓越的流派融合和智能提示,最长8分钟

关键参数

prompt
string
音乐生成的文本描述。提供详细、具体的描述以获得更好的结果。提示词技巧:
  • 描述音乐风格和流派
  • 包含情绪和氛围
  • 指定乐器和人声
  • 添加节拍和能量描述
model
string
required
要使用的模型版本:
  • V3_5 - 创意多样性,最长4分钟
  • V4 - 最佳音频质量,最长4分钟
  • V4_5 - 高级功能,最长8分钟
customMode
boolean
启用自定义参数模式以进行高级控制。当为 true 时,需要额外的参数如 styletitle
instrumental
boolean
生成无人声的纯音乐。默认为 false
style
string
音乐风格或流派(自定义模式下必需)。示例:“爵士”、“摇滚”、“古典”、“电子”
title
string
歌曲标题(自定义模式下必需)。最多80个字符。
callBackUrl
string
接收完成通知的URL。详见回调文档。

完整工作流程示例

以下是完整的音乐生成和处理示例:
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.lyricsData[0].text);
    
    // 使用自定义参数生成音乐
    console.log('正在生成音乐...');
    const musicTaskId = await api.generateMusic({
      prompt: lyricsResult.lyricsData[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: 'audio_123',
  callBackUrl: 'https://your-server.com/wav-callback'
});

音乐视频生成

创建可视化音乐视频:
const videoTaskId = await api.createMusicVideo({
  taskId: 'music_task_id',
  audioId: 'audio_123',
  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回调以在您的音乐准备就绪时接收自动通知。

任务状态说明

GENERATING
处理中
任务正在处理中
SUCCESS
已完成
任务成功完成
FAILED
已失败
任务未能完成
PENDING
排队中
任务正在排队等待处理

最佳实践

文件存储和访问

生成的音频文件在自动删除前存储 15天。下载URL可能有有限的有效期。
  • 音频文件在生成后15天内保持可访问
  • 下载并保存重要文件到您自己的存储
  • 如需要,在过期后使用API重新生成内容
  • 考虑为关键内容实施本地备份策略

下一步

支持

需要帮助吗?我们的技术支持团队随时为您提供帮助。

准备开始创建令人惊叹的AI音乐了吗?获取您的API密钥,立即开始创作!