认证

所有 Suno API 请求都需要使用 Bearer Token 进行认证。本指南将说明如何获取和正确使用您的 API 密钥。

获取 API 密钥

访问 API 密钥管理页面
按照指引生成您的唯一 API 密钥
将您的 API 密钥安全地保存起来以备将来使用

使用您的 API 密钥

在所有请求的头部添加您的 API 密钥作为 Bearer token：

Authorization: Bearer YOUR_API_KEY

安全提示

保持 API 密钥的安全，切勿与他人共享
将 API 密钥存储在环境变量中，而非直接写在代码里
如果您怀疑 API 密钥已泄露，请立即重置

实现示例

基本 API 请求（JavaScript）

const SUNO_API_KEY = process.env.SUNO_API_KEY; // 存储在环境变量中
const BASE_URL = "https://api.api.box";

async function callSunoApi(endpoint, data) {
  try {
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${SUNO_API_KEY}`
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    if (result.code !== 200) {
      throw new Error(`API 错误: ${result.msg}`);
    }
    
    return result;
  } catch (error) {
    console.error("API 请求失败:", error);
    throw error;
  }
}

// 示例：生成音频
async function generateAudio() {
  const data = {
    prompt: "一段平静的钢琴曲，带有柔和的旋律",
    customMode: true,
    instrumental: true,
    model: "V3_5",
    callBackUrl: "https://your-callback-url.com/webhook"
  };
  
  return callSunoApi("/api/v1/generate", data);
}

Python 示例

import os
import requests
import json

SUNO_API_KEY = os.environ.get("SUNO_API_KEY")  // 存储在环境变量中
BASE_URL = "https://api.api.box"

def call_suno_api(endpoint, data):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {SUNO_API_KEY}"
    }
    
    response = requests.post(f"{BASE_URL}{endpoint}", headers=headers, json=data)
    result = response.json()
    
    if result.get("code") != 200:
        raise Exception(f"API 错误: {result.get('msg')}")
    
    return result

// 示例：生成歌词
def generate_lyrics():
    data = {
        "prompt": "一首关于城市中宁静夜晚的歌",
        "callBackUrl": "https://your-callback-url.com/webhook"
    }
    
    return call_suno_api("/api/v1/lyrics", data)

安全最佳实践

1. 安全存储密钥

切勿在源代码或客户端应用中硬编码 API 密钥
使用环境变量或安全的密钥管理系统
为开发和生产环境维护不同的 API 密钥

// 使用 dotenv 处理环境变量
require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

if (!apiKey) {
  throw new Error("环境中未配置 API 密钥");
}

2. 实施密钥轮换

定期轮换您的 API 密钥以限制潜在暴露的影响
制定在所有服务中安全更新密钥的流程
记录密钥上次轮换的时间

3. 监控 API 使用情况

定期检查 API 使用情况的异常模式
为 API 请求的意外峰值设置警报
跟踪额度消耗以避免服务中断

错误处理

在应用程序中正确处理认证错误：

async function handleApiRequest(endpoint, data) {
  try {
    const result = await callSunoApi(endpoint, data);
    return result;
  } catch (error) {
    // 处理特定错误代码
    if (error.code === 401) {
      console.error("认证失败：无效或过期的 API 密钥");
      // 实现您的认证错误恢复逻辑
    } else if (error.code === 429) {
      console.error("额度不足，无法完成请求");
      // 处理额度不足场景
    } else {
      console.error("API 请求失败:", error);
    }
    throw error;
  }
}

故障排除

问题	可能的解决方案
"未授权"错误 (401)	检查您的 API 密钥是否有效并在请求头中正确格式化
"额度不足"错误 (429)	检查您的账户余额并在需要时添加更多额度
"速率限制"错误 (405)	减少请求频率或实施请求节流
连接超时	检查您的网络连接并使用指数退避算法重试

最佳实践

在应用程序中实现回调时，请确保您的回调 URL 可公开访问，并能正确处理来自 Suno API 的响应数据。

如果您遇到持续的认证问题，请联系我们的支持团队：support@api.box

获取 API 密钥​

使用您的 API 密钥​

实现示例​

基本 API 请求（JavaScript）​

Python 示例​

安全最佳实践​

1. 安全存储密钥​

2. 实施密钥轮换​

3. 监控 API 使用情况​

错误处理​

故障排除​