欢迎使用 Suno API

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

身份验证

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

API 基础 URL

https://api.api.box

身份验证请求头

Authorization: Bearer YOUR_API_KEY

快速开始指南

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

从一个简单的音乐生成请求开始:
curl -X POST "https://api.api.box/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检查生成状态:
curl -X GET "https://api.api.box/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等多种高质量音频格式输出
  • 音乐视频:将音频转换为视觉化的音乐视频
  • 风格增强:提升和优化现有音乐的风格特色

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.api.box/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 (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 (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 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
服务器错误
服务器内部错误

最佳实践

错误处理

支持

需要帮助吗?我们的技术支持团队随时为您提供帮助。
  • 邮箱: support@api.box
  • 文档: 查看详细的API文档和示例
  • API状态: 查看我们的状态页面了解实时API健康状况

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