Crun Suno API 快速开始指南

欢迎使用 Crun Suno APIs

由先进 AI 模型驱动，Crun Suno API 提供全面的 AI 音乐生成与音频处理服务。
无论你需要生成音乐、创建音效、扩展音频，还是进行人声分离，我们的 API 都可以满足你的创作需求。

Suno AI 音乐模型

支持多种音乐模型，包括最新的 Suno V5 模型。

V3.5

快速创意输出，适合灵感快速生成。

V4

平衡型生成核心，整体输出更加稳定。

V4.5

更好的结构与流畅度，提升歌曲整体衔接。

V4.5all

多风格支持，可处理多种音乐流派。

V4.5plus

增强人声控制，人声表现更加稳定。

V5

录音室级音质，更干净的混音与专业音效。

V5.5

可定制模型，打造专属于你的独特风格。

音乐生成 APIs

提供全面的 AI 音乐创作与音频处理 API 服务。

生成音乐

通过文本提示生成多种风格的歌曲。

扩展音乐

无缝续写并扩展已有音乐。

上传音频扩展

上传音频并对作品进行扩展与优化。

翻唱音乐

使用新的风格或声音重新演绎歌曲。

生成音乐播放器视频

生成与音乐同步的视频画面。

音频人声分离

精准分离人声与伴奏轨道。

音效生成

通过文本提示生成音效、环境音与循环音频。

开始使用

选择适合的音乐 API

从上方分类中选择最适合你业务场景的音乐 API。

获取 API Key

访问 API Key 管理页面获取你的 API 凭证。

完成集成

按照对应音乐 API 的文档说明，将 API 集成到你的应用程序中。

开始创作

通过简单的 API 调用，开始生成你的内容。

最佳实践

身份认证

所有 API 请求都需要在请求头中携带 API Key。

X-API-KEY: YOUR_API_KEY

请妥善保管你的 API Key。不要在客户端代码或公开仓库中暴露它。

创建任务

所有 Suno API 的任务创建请求都遵循统一的外层结构，仅 input 字段会根据模型不同而变化。

只有 HTTP 状态码与业务状态码同时为 200 时，才表示请求成功。

curl -X POST "https://api.crun.ai/api/v1/client/job/CreateTask" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "suno/music-generate",
    "callback_url": "https://your.domain/api/v1/callback/task",
    "input": {
      "mode": "simple",
      "model": "v5",
      "instrumental": false,
      "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
    }
  }'

import requests

API_KEY = "YOUR_API_KEY"
CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask"

payload = {
    "model": "suno/music-generate",
    "callback_url": "https://your.domain/api/v1/callback/task",  # 使用回调通知
    # "callback_url": "",
    "input": {
       "mode": "simple",
       "model": "v5",
       "instrumental": False,
       "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
    }
}

headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
}

try:
    response = requests.post(CREATE_TASK_URL, json=payload, headers=headers)
    resp_json = response.json()

    # 只有 HTTP 状态码与业务 code 同时为 200 才表示成功
    if response.status_code == 200 and resp_json.get("code") == 200:
        # 成功处理逻辑
        pass
    else:
        # 业务错误处理
        pass

except Exception as e:
    print(f"创建任务时发生异常: {str(e)}")

import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask";

async function createTask() {
    const payload = {
        model: "suno/music-generate",
        callback_url: "https://your.domain/callback/task", // 使用回调通知
        // callback_url: "",
        input: {
             "mode": "simple",
             "model": "v5",
             "instrumental": false,
             "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
        }
    };

    try {
        const response = await axios.post(CREATE_TASK_URL, payload, {
            headers: {
                "X-API-KEY": API_KEY,
                "Content-Type": "application/json"
            }
        });

        const respJson = response.data;

        // 只有 HTTP 状态码与业务 code 同时为 200 才表示成功
        if (response.status === 200 && respJson.code === 200) {
            // 成功处理逻辑
        } else {
            // 业务错误处理
        }
    } catch (error) {
        console.error(
            "创建任务时发生异常:",
            error.response?.data || error.message
        );
    }
}

createTask();

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "xxxx-xxxx"
  }
}

{
  "code": 422,
  "message": "缺少参数或参数类型错误"
}

{
  "code": 500,
  "message": "内部服务错误"
}

轮询任务状态

建议轮询间隔设置为 15 至 30 秒。生产环境推荐使用 Webhook 回调方式。

curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

import time
import requests

API_KEY = "YOUR_API_KEY"
GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

poll_interval = 15

headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
}

params = {
    "task_id": "xxxx-xxxx",
}

while True:
    response = requests.get(GET_TASK_STATUS_URL, headers=headers, params=params)
    resp_json = response.json()

    task_status = resp_json["data"]["status"]
    print(f"任务状态: {task_status}")

    if task_status == "success":
        # 成功处理逻辑
        break
    elif task_status == "failed":
        # 失败处理逻辑
        break
    else:
        # 任务状态为 pending 或 running
        time.sleep(poll_interval)

import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo";

const poll_interval = 15;

const headers = {
  "X-API-KEY": API_KEY,
  "Content-Type": "application/json"
};

const params = {
  task_id: "xxxx-xxxx",
};

async function pollTaskStatus() {
  while (true) {
    const response = await axios.get(GET_TASK_STATUS_URL, {
      headers,
      params
    });

    const resp_json = response.data;

    const task_status = resp_json.data.status;
    console.log(`任务状态: ${task_status}`);

    if (task_status === "success") {
      // 成功处理逻辑
      break;
    } else if (task_status === "failed") {
      // 失败处理逻辑
      break;
    } else {
      // 任务状态为 pending 或 running
      await new Promise((resolve) => setTimeout(resolve, poll_interval * 1000));
    }
  }
}

pollTaskStatus();

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "suno_task_12345678",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "running",
    "param": {
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task",
      "input": {
        "mode": "simple",
        "model": "v5",
        "instrumental": false,
        "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
      }
    },
    "create_at": 1773969449,
    "result": null,
    "duration_s": null,
    "complete_at": null
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "suno_task_12345678",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "success",
    "param": {
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task",
      "input": {
        "mode": "simple",
        "model": "v5",
        "instrumental": false,
        "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
      }
    },
    "create_at": 1773969449,
    "result": {
      "code": 200,
      "message": "生成成功",
      "media_urls": [
        "..."
      ],
      "suno_data": [
        {
          "suno_id": "86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6",
          "title": "music title",
          "prompt": "[Verse 1]\nHalf a glass on the table\nLipstick stain where you left off\nScreen ...",
          "tags": "country, Slow-rolling modern R&B ballad with soulful female vocals over soft piano ...",
          "suno_audio_url": "https://cdn1.suno.ai/86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.mp3",
          "suno_image_url": "https://cdn2.suno.ai/image_86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.jpeg",
          "suno_image_large_url": "https://cdn2.suno.ai/image_large_86c7b0a2-08e9-469e-8b90-1c80dbfdcdb6.jpeg",
          "suno_model_name": "chirp-crow",
          "duration": 211.68,
          "created_at": 1773969602219
        }
      ]
    },
    "duration_s": 153,
    "complete_at": 1773969602,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "suno_task_12345678",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "failed",
    "param": {
      "model": "suno/music-generate",
      "callback_url": "https://your.domain/api/v1/callback/task",
      "input": {
        "mode": "simple",
        "model": "v5",
        "instrumental": false,
        "prompt": "一首现代西方 R&B 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
      }
    },
    "create_at": 1773969449,
    "result": {
      "code": 501,
      "message": "错误信息"
    },
    "duration_s": 153,
    "complete_at": 1773969602
  }
}

任务状态由响应 data 对象中的 status 字段决定。
当 status 为 success 时，可从 data.result.media_urls 获取生成后的媒体地址。
data.result.suno_data 中的每个元素都代表一个 Suno 音乐对象，包含歌曲相关信息。
当 status 为 failed 时，请查看 data.result 中的错误码与错误信息。

回调通知

虽然支持轮询方式，但生产环境强烈推荐使用 Webhook 回调。
当你在创建任务请求中提供 callback_url 时，请确保：

回调地址可通过公网 HTTPS 访问。
接口响应速度足够快（建议小于 3 秒），以避免重复重试。
成功接收后返回 HTTP 200 状态码。
接口具备幂等性，因为回调通知可能会重复发送。

回调数据结构与任务状态查询 API 返回的 data 对象保持一致，因此可以共用同一套解析逻辑。

当任务状态发生变化时，我们会通过 POST 请求通知你任务结果。
回调数据结构与任务状态查询接口中的 data 对象一致。
生产环境中，强烈推荐使用回调通知来获取任务结果。

Credits 与计费

不同的音乐 API 会根据其计算资源需求消耗不同数量的 Credits。访问 pricing 页面查看各音乐 API 的详细计费说明。查看剩余 Credits：

curl -X POST "https://api.crun.ai/api/v1/client/account/balance" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance"

headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(GET_BALANCE_URL, headers=headers)

print(response.json())

import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance";

const headers = {
  "X-API-KEY": API_KEY,
  "Content-Type": "application/json"
};

axios
  .post(GET_BALANCE_URL, null, { headers })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

支持与帮助

需要帮助选择合适的模型或集成 API？

邮箱：[email protected]
文档：请在导航中查看各模型的专属接入指南

介绍

API参考

Suno任务

Crun Suno API 快速开始指南

欢迎使用 Crun Suno APIs

Suno AI 音乐模型

V3.5

V4

V4.5

V4.5all

V4.5plus

V5

V5.5

音乐生成 APIs

生成音乐

扩展音乐

上传音频扩展

翻唱音乐

生成音乐播放器视频

音频人声分离

音效生成

开始使用

最佳实践

身份认证

创建任务

响应示例

轮询任务状态

响应示例

回调通知

Credits 与计费

支持与帮助

​欢迎使用 Crun Suno APIs

​Suno AI 音乐模型

V3.5

V4

V4.5

V4.5all

V4.5plus

V5

V5.5

​音乐生成 APIs

生成音乐

扩展音乐

上传音频扩展

翻唱音乐

生成音乐播放器视频

音频人声分离

音效生成

​开始使用

​最佳实践

​身份认证

​创建任务

​响应示例

​轮询任务状态

​响应示例

​回调通知

​Credits 与计费

​支持与帮助

欢迎使用 Crun Suno APIs

Suno AI 音乐模型

音乐生成 APIs

开始使用

最佳实践

身份认证

创建任务

响应示例

轮询任务状态

响应示例

回调通知

Credits 与计费

支持与帮助