Suno API 快速开始

欢迎使用 Suno API

Suno API 基于先进的AI模型，为您提供全面的音乐生成和音频处理服务。无论您需要音乐创作、歌词生成、音频编辑还是人声分离，我们的API都能满足您的所有创意需求。

音乐生成

从文本描述生成高质量音乐

歌词创作

为您的歌曲创建AI驱动的歌词

音频处理

扩展、转换和分离音频轨道

音乐视频

从音频生成可视化音乐视频

身份验证

所有 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"
  }'

const response = await fetch('https://api.sunoapi.org/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: '一首宁静的原声吉他旋律配柔和人声，民谣风格',
    customMode: false,
    instrumental: false,
    model: 'V4_5ALL',
    callBackUrl: 'https://your-server.com/callback'
  })
});

const data = await response.json();
console.log('任务ID:', data.data.taskId);

import requests

url = "https://api.sunoapi.org/api/v1/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "prompt": "一首宁静的原声吉他旋律配柔和人声，民谣风格",
    "customMode": False,
    "instrumental": False,
    "model": "V4_5ALL",
    "callBackUrl": "https://your-server.com/callback"
}

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

print(f"任务ID: {result['data']['taskId']}")

<?php
$url = 'https://api.sunoapi.org/api/v1/generate';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$payload = [
    'prompt' => '一首宁静的原声吉他旋律配柔和人声，民谣风格',
    'customMode' => false,
    'instrumental' => false,
    'model' => 'V4_5ALL',
    'callBackUrl' => 'https://your-server.com/callback'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "任务ID: " . $result['data']['taskId'];
?>

第二步：检查任务状态

使用返回的任务ID检查生成状态：

curl -X GET "https://api.sunoapi.org/api/v1/generate/record-info?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(`https://api.sunoapi.org/api/v1/generate/record-info?taskId=${taskId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();

if (result.data.status === 'SUCCESS') {
  console.log('生成完成！');
  console.log('音频URLs:', result.data.response.data);
} else if (result.data.status === 'GENERATING') {
  console.log('正在生成中...');
} else {
  console.log('生成失败:', result.data.status);
}

import requests
import time

def check_task_status(task_id, api_key):
    url = f"https://api.sunoapi.org/api/v1/generate/record-info?taskId={task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, headers=headers)
    result = response.json()
    
    status = result['data']['status']
    
    if status == 'SUCCESS':
        print("生成完成！")
        audio_data = result['data']['response']['data']
        for i, audio in enumerate(audio_data):
            print(f"音轨 {i+1}: {audio['audio_url']}")
        return audio_data
    elif status == 'GENERATING':
        print("正在生成中...")
        return None
    else:
        print(f"生成失败: {status}")
        return None

# 轮询直到完成
task_id = "YOUR_TASK_ID"
while True:
    audio_data = check_task_status(task_id, "YOUR_API_KEY")
    if audio_data:
        break
    time.sleep(30)  # 等待30秒后再次检查

响应格式

成功响应：

{
  "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分钟

V5_5

释放你的声音Unleash Your Voice: Custom Models Tailored to Your Unique Taste.

关键参数

string

音乐生成的文本描述。提供详细、具体的描述以获得更好的结果。根据模型的字符限制：

V4：最多 3000 字符
V4_5、V4_5PLUS、V4_5ALL、V5、V5_5：最多 5000 字符

提示词技巧：

描述音乐风格和流派
包含情绪和氛围
指定乐器和人声
添加节拍和能量描述

string

必填

要使用的模型版本：

V4 - 最佳音频质量，最长4分钟
V4_5 - 高级功能，最长8分钟
V4_5PLUS - 更丰富音色，最长8分钟
V4_5ALL - V4.5-all 更好的歌曲结构，最长8分钟
V5 - 生成速度更快，更卓越音乐表现力，最长8分钟
V5_5 - Unleash Your Voice: Custom Models Tailored to Your Unique Taste.

boolean

启用自定义参数模式以进行高级控制。当为 true 时，需要额外的参数如 style 和 title。

boolean

生成无人声的纯音乐。默认为 false。

string

音乐风格或流派（自定义模式下必需）。示例：“爵士”、“摇滚”、“古典”、“电子”根据模型的字符限制：

V4：最多 200 字符
V4_5、V4_5PLUS、V4_5ALL、V5、V5_5：最多 1000 字符

string

歌曲标题（自定义模式下必需）。根据模型的字符限制：

V4 和 V4_5ALL：最多 80 字符
V4_5、V4_5PLUS、V5、V5_5：最多 100 字符

string

接收完成通知的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重新生成内容
考虑为关键内容实施本地备份策略

下一步

生成音乐

音乐生成的完整API参考

创建歌词

AI驱动的歌词生成

音频处理

扩展、转换和分离音频

回调设置

设置自动通知

支持

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

邮箱: support@sunoapi.org
文档: docs.sunoapi.org
API状态: 查看我们的状态页面了解实时API健康状况

​欢迎使用 Suno API

音乐生成

歌词创作

音频处理

音乐视频

​身份验证

​API 基础 URL

​身份验证请求头

​快速开始指南

​第一步：生成您的第一首歌曲

​第二步：检查任务状态

​响应格式

​核心功能

​音乐生成

​歌词创作

​音频扩展

​上传翻唱

​模型版本

V4

V4_5

V4_5PLUS

V4_5ALL

V5

V5_5

​关键参数

​完整工作流程示例

​高级功能

​上传并扩展

​音频格式转换

​音乐视频生成

​使用回调

了解更多关于回调

​任务状态说明

​最佳实践

​文件存储和访问

​下一步

生成音乐

创建歌词

音频处理

回调设置

​支持

欢迎使用 Suno API

身份验证

API 基础 URL

身份验证请求头

快速开始指南

第一步：生成您的第一首歌曲

第二步：检查任务状态

响应格式

核心功能

音乐生成

歌词创作

音频扩展

上传翻唱

模型版本

关键参数

完整工作流程示例

高级功能

上传并扩展

音频格式转换

音乐视频生成

使用回调

任务状态说明

最佳实践

文件存储和访问

下一步

支持