---
title: "透過 RunAPI 在 OpenClaw 中使用 Suno — 音樂 API 指南"
url: "https://runapi.ai/zh-HK/openclaw-suno.md"
canonical: "https://runapi.ai/zh-HK/openclaw-suno"
locale: "zh-HK"
model: "suno"
---

# 在 OpenClaw 中使用 Suno。

Suno 從文字提示詞或精確歌詞生成完整歌曲 — 包含人聲、樂器和混音。v4 到 v5.5 版本皆可透過 RunAPI 使用，由於 Suno 沒有官方公開 API，RunAPI 提供了程式化存取方式。OpenClaw agent 使用與聊天相同的 RUNAPI_API_KEY 來呼叫。

## API example

```bash
curl -X POST https://runapi.ai/api/v1/suno/text_to_music \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "vocal_mode": "auto_lyrics",
    "prompt": "An upbeat indie pop track about coding late at night, warm synths and acoustic guitar",
    "vocal_gender": "female"
  }'

```

### Response

```json
{
  "task_id": "tsk_abc123",
  "status": "pending",
  "model": "suno-v5.5"
}

```

## How it works

1. **設定 RunAPI** — 在環境中設定 RUNAPI_API_KEY。如果你已在 OpenClaw 中設定 RunAPI 用於聊天，同一組 key 即可用於 Suno 音樂生成，無需額外的 provider 設定。
2. **呼叫 text_to_music** — 向 text_to_music 端點發送 POST 請求，帶上 model 和 vocal_mode。使用 auto_lyrics 搭配 prompt 讓 AI 撰寫歌詞，使用 exact_lyrics 搭配 lyrics/style/title 提供你自己的歌詞，或使用 instrumental 搭配 style/title 生成純演奏曲目。
3. **輪詢結果** — 端點會立即回傳 task_id。歌曲生成需要 30 秒到數分鐘不等，取決於版本。輪詢任務狀態端點，直到 status 為 completed，然後讀取輸出音訊 URL。

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | `string` | 必填。suno-v4、suno-v4.5、suno-v4.5-all、suno-v4.5-plus、suno-v5 或 suno-v5.5。 |
| `vocal_mode` | `string` | 必填。auto_lyrics（AI 根據 prompt 撰寫歌詞）、exact_lyrics（你提供 lyrics/style/title）或 instrumental（無人聲，需提供 style/title）。 |
| `prompt` | `string` | auto_lyrics 模式的歌曲描述。描述曲風、氛圍、節奏和主題。在 exact_lyrics 和 instrumental 模式中禁止使用。 |
| `lyrics` | `string` | 要演唱的精確歌詞。exact_lyrics 模式必填。在 auto_lyrics 和 instrumental 模式中禁止使用。 |
| `style` | `string` | 音樂風格描述，例如 lo-fi hip hop、80s synthwave。exact_lyrics 和 instrumental 模式必填。 |
| `title` | `string` | 歌曲標題。exact_lyrics 和 instrumental 模式必填。 |
| `vocal_gender` | `string` | 選填。male 或 female。 |
| `negative_tags` | `string` | 選填。要避免的風格，例如 heavy metal、screaming。 |
| `duration_seconds` | `integer` | 選填。目標時長（秒）。 |
| `persona_id` | `string` | 選填。自訂聲音或風格設定檔的 Persona ID。 |
| `persona_type` | `string` | 選填。style 或 voice。選擇 persona 類別。 |
| `callback_url` | `string` | 選填。任務完成時接收 POST 通知的 Webhook URL。 |

## FAQ

### auto_lyrics、exact_lyrics 和 instrumental 有什麼差別？

auto_lyrics 根據你的 prompt 生成歌詞 — 你描述歌曲，Suno 撰寫歌詞。exact_lyrics 逐字使用你提供的歌詞，並需要 style 和 title 欄位。instrumental 生成無人聲的曲目，僅使用 style 和 title。

### 我應該使用哪個 Suno 版本？

suno-v5.5 是最新版本，產出最高品質的結果，擁有更好的人聲清晰度和混音效果。suno-v4 和 suno-v4.5 更便宜且更快，適合草稿迭代。所有版本使用相同的 text_to_music 端點和參數。

### Suno 生成需要多長時間？

生成時間因版本和歌曲長度而異。一般為 30 秒到 2 分鐘。API 會立即回傳 task_id — 輪詢狀態端點或設定 callback_url 以避免阻塞你的 agent。

### RunAPI 提供的是官方 Suno API 嗎？

Suno 沒有提供公開 API。RunAPI 透過與所有其他 RunAPI 模型相同的 API key 和任務生命週期，提供對 Suno v4 到 v5.5 的程式化存取。不需要 Suno 帳號或獨立的憑證。

### 我可以控制人聲性別和風格權重嗎？

可以。將 vocal_gender 設為 male 或 female。使用 negative_tags 排除不想要的風格。如需更精細的控制，透過 generate_persona 端點建立 persona，並將回傳的 persona_id 與 persona_type 設為 voice 或 style 一起傳入。


## Links

- [OpenClaw 設定指南 →](https://runapi.ai/zh-HK/openclaw)
- [Suno on RunAPI →](https://runapi.ai/zh-HK/models/suno)
- [Model catalog](https://runapi.ai/zh-HK/models)
- [API docs](https://runapi.ai/zh-HK/docs)