欢迎使用 Suno API

Suno API 让您能够使用最先进的AI模型创建高质量的AI生成音乐、歌词和音频内容。无论您是在构建音乐应用、自动化创意工作流程,还是开发音频内容,我们的API都为音乐生成和音频处理提供了全面的工具。

身份验证

所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥,切勿公开分享。如果怀疑密钥泄露,请立即重置。

API 基础 URL

https://api.kie.ai

身份验证请求头

Authorization: Bearer YOUR_API_KEY

快速开始指南

第一步:生成您的第一个音乐曲目

从一个简单的音乐生成请求开始:
curl -X POST "https://api.kie.ai/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一首平静舒缓的钢琴曲,带有柔和的旋律",
    "customMode": false,
    "instrumental": true,
    "model": "V3_5",
    "callBackUrl": "https://your-app.com/callback"
  }'

第二步:检查任务状态

使用返回的任务ID检查生成状态:
async function checkTaskStatus(taskId) {
  try {
    const response = await fetch(`https://api.kie.ai/api/v1/generate/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      const taskData = result.data;
      
      switch (taskData.status) {
        case 'SUCCESS':
          console.log('所有音轨生成成功!');
          console.log('音频轨道:', taskData.response.sunoData);
          return taskData.response;
          
        case 'FIRST_SUCCESS':
          console.log('第一个音轨生成完成');
          if (taskData.response.sunoData && taskData.response.sunoData.length > 0) {
            console.log('音频轨道:', taskData.response.sunoData);
          }
          return taskData.response;
          
        case 'TEXT_SUCCESS':
          console.log('歌词/文本生成成功');
          return taskData.response;
          
        case 'PENDING':
          console.log('任务等待处理中...');
          return taskData.response;
          
        case 'CREATE_TASK_FAILED':
          console.log('创建任务失败');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData.response;
          
        case 'GENERATE_AUDIO_FAILED':
          console.log('音频生成失败');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData.response;
          
        case 'CALLBACK_EXCEPTION':
          console.log('回调过程中出错');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData.response;
          
        case 'SENSITIVE_WORD_ERROR':
          console.log('内容因敏感词被过滤');
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData.response;
          
        default:
          console.log('未知状态:', taskData.status);
          if (taskData.errorMessage) {
            console.error('错误信息:', taskData.errorMessage);
          }
          return taskData.response;
      }
    } else {
      console.error('查询失败:', result.msg || '未知错误');
      return null;
    }
  } catch (error) {
    console.error('查询状态失败:', error.message);
    return null;
  }
}

响应格式

成功响应:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
任务状态响应(成功):
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "parentMusicId": "",
    "param": "{\"prompt\":\"一首平静舒缓的钢琴曲\",\"style\":\"平静, 舒缓, 钢琴\"}",
    "response": {
      "taskId": "5c79****be8e",
      "sunoData": [
        {
          "id": "e231****-****-****-****-****8cadc7dc",
          "audioUrl": "https://example.cn/****.mp3",
          "streamAudioUrl": "https://example.cn/****",
          "imageUrl": "https://example.cn/****.jpeg",
          "prompt": "[Verse] 夜晚城市 灯火辉煌",
          "modelName": "chirp-v3-5",
          "title": "钢铁侠",
          "tags": "electrifying, rock",
          "createTime": "2025-01-01 00:00:00",
          "duration": 198.44
        }
      ]
    },
    "status": "SUCCESS",
    "type": "GENERATE",
    "errorCode": null,
    "errorMessage": null
  }
}
任务状态响应(失败):
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "parentMusicId": "",
    "param": "{\"prompt\":\"一首平静舒缓的钢琴曲\",\"style\":\"平静, 舒缓, 钢琴\"}",
    "response": {
      "taskId": "5c79****be8e",
      "sunoData": [],
      "errorMessage": "生成失败,请重试或联系客服"
    },
    "status": "GENERATE_AUDIO_FAILED",
    "type": "GENERATE",
    "errorCode": 501,
    "errorMessage": "生成失败,请重试或联系客服"
  }
}

核心功能

  • 文本转音乐:输入文字描述,生成相应的音乐作品
  • 延长音乐:基于现有音频,无缝创建更长版本
  • 生成歌词:从创意提示生成结构化歌词内容
  • 上传翻唱:上传音频文件,转换为不同的音乐风格
  • 添加伴奏:为上传的音频文件生成伴奏音乐
  • 添加人声:为上传的音频文件添加自定义风格的人声演唱
  • 人声分离:将音乐分离为人声、伴奏等独立轨道
  • 格式转换:支持WAV等多种高质量音频格式输出

AI 模型

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

V3_5

更好的歌曲结构最长4分钟,改进的歌曲组织

V4

改进的人声最长4分钟,增强的人声质量

V4_5

智能提示词最长8分钟,更快的生成速度

V4_5PLUS

更丰富的音色最长8分钟,新的创作方式

生成模式

customMode
boolean
required
控制参数复杂度:
  • false: 简单模式,仅需要提示词
  • true: 高级模式,需要风格和标题
instrumental
boolean
required
决定音乐是否包含人声:
  • true: 仅纯音乐(无歌词)
  • false: 包含人声/歌词

关键参数

prompt
string
required
对所需音乐的文本描述。请具体说明流派、情绪和乐器。字符限制:
  • 非自定义模式:400字符
  • 自定义模式(V3_5 & V4):3000字符
  • 自定义模式(V4_5 & V4_5PLUS):5000字符
style
string
音乐风格规范(仅自定义模式)。示例: 爵士、古典、电子、流行、摇滚、嘻哈字符限制:
  • V3_5 & V4:200字符
  • V4_5 & V4_5PLUS:1000字符
title
string
生成音乐曲目的标题(仅自定义模式)。最大长度: 80字符

完整工作流程示例

以下是一个生成带歌词音乐并等待完成的完整示例:
class SunoAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.kie.ai/api/v1';
  }
  
  async generateMusic(prompt, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        customMode: options.customMode || false,
        instrumental: options.instrumental || false,
        model: options.model || 'V3_5',
        style: options.style,
        title: options.title,
        negativeTags: options.negativeTags,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback'
      })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`生成失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data.taskId;
  }
  
  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,
        defaultParamFlag: options.defaultParamFlag || false,
        model: options.model || 'V3_5',
        prompt: options.prompt,
        style: options.style,
        title: options.title,
        continueAt: options.continueAt,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback'
      })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`延长失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data.taskId;
  }
  
  async generateLyrics(prompt, callBackUrl) {
    const response = await fetch(`${this.baseUrl}/lyrics`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        callBackUrl
      })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`歌词生成失败: ${result.msg || '未知错误'}`);
    }
    
    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);
      
      switch (status.status) {
        case 'SUCCESS':
          console.log('所有音轨生成成功!');
          return status.response;
          
        case 'FIRST_SUCCESS':
          console.log('第一个音轨生成完成!');
          return status.response;
          
        case 'TEXT_SUCCESS':
          console.log('歌词/文本生成成功!');
          return status.response;
          
        case 'PENDING':
          console.log('任务等待处理中...');
          break;
          
        case 'CREATE_TASK_FAILED':
          const createError = status.errorMessage || '创建任务失败';
          console.error('错误信息:', createError);
          throw new Error(createError);
          
        case 'GENERATE_AUDIO_FAILED':
          const audioError = status.errorMessage || '音频生成失败';
          console.error('错误信息:', audioError);
          throw new Error(audioError);
          
        case 'CALLBACK_EXCEPTION':
          const callbackError = status.errorMessage || '回调过程中出错';
          console.error('错误信息:', callbackError);
          throw new Error(callbackError);
          
        case 'SENSITIVE_WORD_ERROR':
          const sensitiveError = status.errorMessage || '内容因敏感词被过滤';
          console.error('错误信息:', sensitiveError);
          throw new Error(sensitiveError);
          
        default:
          console.log(`未知状态: ${status.status}`);
          if (status.errorMessage) {
            console.error('错误信息:', status.errorMessage);
          }
          break;
      }
      
      // 等待10秒后再次检查
      await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    throw new Error('生成超时');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/generate/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`查询状态失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data;
  }
}

// 使用示例
async function main() {
  const api = new SunoAPI('YOUR_API_KEY');
  
  try {
    // 生成带歌词的音乐
    console.log('开始生成音乐...');
    const taskId = await api.generateMusic(
      '一首关于童年回忆的怀旧民谣',
      { 
        customMode: true,
        instrumental: false,
        model: 'V4_5',
        style: '民谣, 原声吉他, 怀旧',
        title: '童年梦想'
      }
    );
    
    // 等待完成
    console.log(`任务ID: ${taskId}。等待完成...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('音乐生成成功!');
    console.log('生成的曲目:');
    result.sunoData.forEach((track, index) => {
      console.log(`曲目 ${index + 1}:`);
      console.log(`  标题: ${track.title}`);
      console.log(`  音频URL: ${track.audioUrl}`);
      console.log(`  时长: ${track.duration}秒`);
      console.log(`  标签: ${track.tags}`);
    });
    
    // 延长第一个曲目
    const firstTrack = result.sunoData[0];
    console.log('\n延长第一个曲目...');
    const extendTaskId = await api.extendMusic(firstTrack.id, {
      defaultParamFlag: true,
      prompt: '继续一个充满希望的副歌',
      style: '民谣, 振奋',
      title: '童年梦想延长版',
      continueAt: 60,
      model: 'V4_5'
    });
    
    const extendResult = await api.waitForCompletion(extendTaskId);
    console.log('音乐延长成功!');
    console.log('延长曲目URL:', extendResult.sunoData[0].audioUrl);
    
  } catch (error) {
    console.error('错误:', error.message);
  }
}

main();

状态码和任务状态

PENDING
处理中
任务正在等待处理或正在生成中
TEXT_SUCCESS
部分完成
歌词/文本生成成功完成
FIRST_SUCCESS
部分完成
第一个曲目生成完成
SUCCESS
完成
所有曲目生成成功
CREATE_TASK_FAILED
错误
创建任务失败
GENERATE_AUDIO_FAILED
错误
生成音频失败
CALLBACK_EXCEPTION
错误
回调过程中出错
SENSITIVE_WORD_ERROR
错误
内容因敏感词被过滤

最佳实践

错误处理

支持

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

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