跳转到主要内容

​
欢迎使用 Suno API

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

生成音乐

创建带或不带歌词的原创音乐曲目

延长音乐

无缝延长现有音乐曲目

生成歌词

从文本提示创建创意歌词

音乐视频

将音频轨道转换为可视化音乐视频

上传翻唱

将上传的音频转换为新风格

上传扩展

上传音频文件并无缝扩展

人声分离

从音乐中分离人声和伴奏

WAV转换

将音频转换为高质量WAV格式

获取歌词

获取带时间戳的同步歌词

添加伴奏

为现有音频轨道添加伴奏元素

添加人声

为器乐音乐生成人声轨道

增强音乐风格

使用V4_5对话式提示词增强风格描述

​
身份验证

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

​
API 基础 URL

https://apibox.erweima.ai

​
身份验证请求头

Authorization: Bearer YOUR_API_KEY

​
快速开始指南

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

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

​
第二步：检查任务状态

使用返回的任务ID检查生成状态： 
curl -X GET "https://apibox.erweima.ai/api/v1/generate/record-info?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
响应格式

成功响应： 
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
任务状态响应： 
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "status": "SUCCESS",
    "response": {
      "data": [
        {
          "id": "8551****662c",
          "audio_url": "https://example.cn/****.mp3",
          "stream_audio_url": "https://example.cn/****",
          "image_url": "https://example.cn/****.jpeg",
          "prompt": "一首平静舒缓的钢琴曲",
          "title": "宁静钢琴",
          "tags": "平静, 舒缓, 钢琴",
          "duration": 198.44,
          "createTime": "2025-01-01 00:00:00"
        }
      ]
    }
  }
}

​
核心功能

  • 文本转音乐：输入文字描述，生成相应的音乐作品
  • 延长音乐：基于现有音频，无缝创建更长版本
  • 生成歌词：从创意提示生成结构化歌词内容
  • 上传翻唱：上传音频文件，转换为不同的音乐风格
  • 上传扩展：上传音频文件并在保持风格的同时无缝扩展
  • 人声分离：将音乐分离为人声、伴奏等独立轨道，支持高级干声分离
  • 格式转换：支持WAV等多种高质量音频格式输出
  • 音乐视频：将音频转换为视觉化的音乐视频
  • 添加人声：为现有的器乐音乐生成人声轨道
  • 添加伴奏：为人声轨道创建器乐伴奏
  • 风格增强：使用V4_5+对话式提示词提升和优化现有音乐的风格特色
  • 带时间戳歌词：获取同步歌词用于卡拉OK式应用

​
AI 模型

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

V4_5ALL

扩展功能支持更长的歌词（5000字符）和风格描述（1000字符）

V4

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

V4_5

更好的歌曲结构最长1分钟，改进的歌曲组织

V4_5PLUS

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

V5

最新模型增强的质量和功能

​
生成模式

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

​
关键参数

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

​
完整工作流程示例

以下是一个生成带歌词音乐并等待完成的完整示例： 
class SunoAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://apibox.erweima.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 || 'V4_5ALL',
        style: options.style,
        title: options.title,
        negativeTags: options.negativeTags,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (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 || 'V4_5ALL',
        prompt: options.prompt,
        style: options.style,
        title: options.title,
        continueAt: options.continueAt,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (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 (result.code !== 200) {
      throw new Error(`歌词生成失败: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async addVocals(uploadUrl, prompt, style, title, negativeTags, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate/add-vocals`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        uploadUrl,
        prompt,
        style,
        title,
        negativeTags,
        model: options.model || 'V4_5PLUS',
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`添加人声失败: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async addInstrumental(uploadUrl, title, tags, negativeTags, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate/add-instrumental`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        uploadUrl,
        title,
        tags,
        negativeTags,
        model: options.model || 'V4_5PLUS',
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (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);
      
      if (status.status === 'SUCCESS') {
        return status.response;
      } else if (status.status.includes('FAILED') || status.status === 'SENSITIVE_WORD_ERROR') {
        throw new Error(`生成失败: ${status.errorMessage || status.status}`);
      }
      
      // 等待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}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    return result.data;
  }
  
  async getRemainingCredits() {
    const response = await fetch(`${this.baseUrl}/generate/credit`, {
      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 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.data.forEach((track, index) => {
      console.log(`曲目 ${index + 1}:`);
      console.log(`  标题: ${track.title}`);
      console.log(`  音频URL: ${track.audio_url}`);
      console.log(`  时长: ${track.duration}秒`);
      console.log(`  标签: ${track.tags}`);
    });
    
    // 延长第一个曲目
    const firstTrack = result.data[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.data[0].audio_url);
    
  } catch (error) {
    console.error('错误:', error.message);
  }
}

main();

​
状态码和任务状态

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

​
HTTP 状态码

​
200
成功
请求成功
​
400
参数错误
请求参数错误或缺失
​
401
未授权
没有访问权限，检查API密钥
​
404
未找到
请求方式或路径错误
​
405
调用限制
调用超过限制
​
413
内容过长
提示词或主题过长
​
429
积分不足
账户积分不足
​
455
维护中
网站维护中
​
500
服务器错误
服务器内部错误

​
最佳实践

  • 具体说明流派、情绪和乐器
  • 使用描述性形容词获得更好的风格控制
  • 包含节拍和能量水平描述
  • 参考音乐时代或特定艺术家进行风格指导
  • V4_5ALL：最适合需要更长歌词和风格描述的项目
  • V4：当人声质量最重要时选择
  • V4_5：用于更好的歌曲结构，最长1分钟
  • V4_5PLUS：选择最高质量和最长的曲目
  • 使用回调而不是频繁轮询
  • 从非自定义模式开始满足简单需求
  • 实施适当的错误处理以应对生成失败
  • 缓存生成内容，因为文件14-15天后到期
  • 避免在提示中使用受版权保护的材料
  • 使用原创歌词和音乐描述
  • 注意歌词内容的内容政策
  • 测试提示变化以避免敏感词过滤器

​
错误处理

try {
  const taskId = await api.generateMusic('受版权保护的歌词');
} catch (error) {
  if (error.data.code === 400) {
    console.log('请仅使用原创内容');
  }
}

try {
  const taskId = await api.generateMusic('原创作品');
} catch (error) {
  if (error.data.code === 429) {
    console.log('请为您的账户添加更多积分');
  }
}

const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function generateWithRetry(prompt, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await api.generateMusic(prompt, options);
    } catch (error) {
      if (error.data.code === 405 && i < maxRetries - 1) {
        await delay(Math.pow(2, i) * 1000); // 指数退避
        continue;
      }
      throw error;
    }
  }
}

​
支持

需要帮助吗？我们的技术支持团队随时为您提供帮助。
  • 邮箱: [email protected]
  • 文档: 查看详细的API文档和示例
  • API状态: 查看我们的状态页面了解实时API健康状况
准备开始创作令人惊叹的AI音乐了吗？获取您的API密钥，立即开始创作！