Suno 音乐生成 API

本文档旨在指导开发者如何使用 RAINBOXS 平台提供的 Suno API 来生成歌词和完整的音乐。Suno API 的工作流程是异步的：您首先提交一个生成任务，系统会返回一个任务ID，然后您需要通过这个ID来轮询查询任务状态，直到任务完成并获取最终的音频文件。

---

1. 提交生成任务 (歌词或歌曲)

此接口用于提交一个生成任务，可以是生成歌词，也可以是生成完整的歌曲。这是一个异步任务。

• 路径：/suno/submit/:action
• 方法：POST
• 认证：Bearer Token

路径参数

参数	类型	是否必需	描述
:action	string	是	指定要执行的操作。例如 lyrics (生成歌词) 或 music (生成歌曲)。

请求 Body (application/json)

根据 :action 的不同，请求体也不同。

当 action 为 lyrics 时:

参数	类型	是否必需	描述
prompt	string	是	歌词的主题或灵感描述。例如：“一首关于夏夜星空的歌曲”。

当 action 为 music 时:

参数	类型	是否必需	描述
prompt	string	是	完整的歌词内容。
tags	string	是	定义歌曲的音乐风格和流派，例如 "流行, 摇滚, 电子"。
title	string	是	歌曲的标题。
mv	string	是	指定使用的模型版本。例如 chirp-v3.5。

请求示例 (生成歌曲)

{
  "prompt": "[Verse]\n寂静的公路 无尽延伸...",
  "tags": "伤感流行, 男声, 80年代复古",
  "title": "时光列车",
  "mv": "chirp-v3.5"
}

响应说明

成功提交任务后，系统将返回一个包含任务 ID 的数组。您需要保存这些 ID 用于后续查询。

---

2. 查询任务状态

使用任务 ID 查询音乐生成任务的当前状态和结果。

• 路径：/suno/fetch/{task_id}
• 方法：GET
• 认证：Bearer Token

路径参数

参数	类型	是否必需	描述
task_id	string	是	从“提交生成任务”接口返回的任务 ID。

响应说明

响应会包含任务的详细信息。您需要关注 status 字段。

• status 字段可能的值:
  • queued: 任务正在排队等待处理。
  • streaming: 任务正在生成中。
  • complete: 任务成功完成。此时响应中会包含音频文件的 URL。
  • error: 任务失败。

成功响应示例 (status: "complete")

{
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "complete",
    "audio_url": "https://cdn.example.com/audio/a1b2c3d4.mp3",
    "video_url": "https://cdn.example.com/video/a1b2c3d4.mp4",
    "metadata": {
        ...
    }
}

---

代码示例

Python (使用 requests)

import requests
import json
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.rainboxs.com/" # 注意基础URL不包含 /v1

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def submit_music_task():
    """提交音乐生成任务"""
    action = "music"
    payload = {
      "prompt": "[Verse]\n寂静的公路 无尽延伸...",
      "tags": "伤感流行, 男声, 80年代复古",
      "title": "时光列车",
      "mv": "chirp-v3.5"
    }
    response = requests.post(f"{BASE_URL}/suno/submit/{action}", headers=headers, data=json.dumps(payload))
    if response.status_code == 200:
        tasks = response.json()
        print("任务提交成功:", tasks)
        # 假设返回的JSON直接就是任务对象或列表
        if isinstance(tasks, list):
            return [task.get('id') for task in tasks if task.get('id')]
        elif isinstance(tasks, dict):
            return [tasks.get('id')] if tasks.get('id') else []
    else:
        print(f"任务提交失败: {response.status_code} - {response.text}")
    return []

def fetch_task_status(task_ids):
    """查询任务状态"""
    if not task_ids:
        return

    print(f"\n开始查询任务状态: {task_ids}")
    for task_id in task_ids:
        if not task_id:
            continue
        while True:
            response = requests.get(f"{BASE_URL}/suno/fetch/{task_id}", headers=headers)
            if response.status_code == 200:
                result = response.json()
                print(f"任务 {task_id} 的状态: {result.get('status', 'unknown')}")
                if result.get('status') == 'complete':
                    print("  音频URL:", result.get('audio_url'))
                    break
                elif result.get('status') == 'error':
                    print("  任务失败!")
                    break
                # 如果任务仍在处理中，等待一段时间再查询
                time.sleep(10) 
            else:
                print(f"查询任务 {task_id} 失败: {response.status_code} - {response.text}")
                break

if __name__ == "__main__":
    submitted_task_ids = submit_music_task()
    fetch_task_status(submitted_task_ids)