> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crun Suno API 快速开始指南

> Crun Suno API 支持 Suno 最新 V5 模型，可实现简单或自定义模式的音乐生成、音效生成、歌曲翻唱以及音频续写。

## 欢迎使用 Crun Suno APIs

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

## Suno AI 音乐模型

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

<CardGroup cols={2}>
  <Card title="V3.5" icon="bolt"> 快速创意输出，适合灵感快速生成。 </Card>
  <Card title="V4" icon="balance-scale"> 平衡型生成核心，整体输出更加稳定。 </Card>
  <Card title="V4.5" icon="stream"> 更好的结构与流畅度，提升歌曲整体衔接。 </Card>
  <Card title="V4.5all" icon="shapes"> 多风格支持，可处理多种音乐流派。 </Card>
  <Card title="V4.5plus" icon="microphone-alt"> 增强人声控制，人声表现更加稳定。 </Card>
  <Card title="V5" icon="music"> 录音室级音质，更干净的混音与专业音效。 </Card>
  <Card title="V5.5" icon="sliders-h"> 可定制模型，打造专属于你的独特风格。 </Card>
</CardGroup>

## 音乐生成 APIs

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

<CardGroup cols={2}>
  <Card title="生成音乐" icon="music" href="/zh/suno-api/generate-music"> 通过文本提示生成多种风格的歌曲。 </Card>
  <Card title="扩展音乐" icon="forward" href="/zh/suno-api/extend-music"> 无缝续写并扩展已有音乐。 </Card>
  <Card title="上传音频扩展" icon="upload" href="/zh/suno-api/extend-music-upload"> 上传音频并对作品进行扩展与优化。 </Card>
  <Card title="翻唱音乐" icon="retweet" href="/zh/suno-api/cover-music"> 使用新的风格或声音重新演绎歌曲。 </Card>
  <Card title="生成音乐播放器视频" icon="video"> 生成与音乐同步的视频画面。 </Card>
  <Card title="音频人声分离" icon="headphones"> 精准分离人声与伴奏轨道。 </Card>
  <Card title="音效生成" icon="waveform-lines" href="/zh/suno-api/sounds-generate"> 通过文本提示生成音效、环境音与循环音频。 </Card>
</CardGroup>

## 开始使用

<Steps>
  <Step title="选择适合的音乐 API">
    从上方分类中选择最适合你业务场景的音乐 API。
  </Step>

  <Step title="获取 API Key">
    访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API 凭证。
  </Step>

  <Step title="完成集成">
    按照对应音乐 API 的文档说明，将 API 集成到你的应用程序中。
  </Step>

  <Step title="开始创作">
    通过简单的 API 调用，开始生成你的内容。
  </Step>
</Steps>

## 最佳实践

### 身份认证

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

```bash theme={null} theme={null}
X-API-KEY: YOUR_API_KEY
```

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

### 创建任务

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

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

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  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 风格歌曲，灵魂感十足的女声，情感丰富且音色柔和。"
      }
    }'
  ```

  ```python Python theme={null} theme={null}
  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)}")
  ```

  ```javascript Node.js theme={null} theme={null}
  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();
  ```
</CodeGroup>

#### 响应示例

<CodeGroup>
  ```json 200 theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "xxxx-xxxx"
    }
  }
  ```

  ```json 4xx theme={null} theme={null}
  {
    "code": 422,
    "message": "缺少参数或参数类型错误"
  }
  ```

  ```json 5xx theme={null} theme={null}
  {
    "code": 500,
    "message": "内部服务错误"
  }
  ```
</CodeGroup>

### 轮询任务状态

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

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  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"
  ```

  ```python Python theme={null} theme={null}
  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)
  ```

  ```javascript Node.js theme={null} theme={null}
  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();
  ```
</CodeGroup>

#### 响应示例

<CodeGroup>
  ```json task processing theme={null} theme={null}
  {
    "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
    }
  }
  ```

  ```json task success theme={null} theme={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"
    }
  }
  ```

  ```json task failed theme={null} theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

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

### 回调通知

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

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

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

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

## Credits 与计费

不同的音乐 API 会根据其计算资源需求消耗不同数量的 Credits。

访问 [pricing](https://crun.ai/zh/pricing) 页面查看各音乐 API 的详细计费说明。

查看剩余 Credits：

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X POST "https://api.crun.ai/api/v1/client/account/balance" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  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())
  ```

  ```javascript Node.js theme={null} theme={null}
  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);
    });
  ```
</CodeGroup>

## 支持与帮助

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

* 邮箱：[support@crun.ai](mailto:support@crun.ai)
* 文档：请在导航中查看各模型的专属接入指南