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

# 在 Hermes Agent 中使用 Suno。

Suno 從文字提示詞或精確歌詞生成完整歌曲 — 包含人聲、樂器和混音。v4 到 v5.5 版本皆可透過 RunAPI 使用，由於 Suno 沒有官方公開 API，RunAPI 提供了程式化存取方式。Hermes Agent 透過 custom:runapi provider 以相同的 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** — 在 Hermes Agent 執行環境中設定 RUNAPI_API_KEY。如果你已將 RunAPI 新增為 custom:runapi provider，同一組 key 和 base_url 即可處理 Suno 音樂請求。
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。

### 如何在 Hermes Agent 中設定 RunAPI 作為 custom provider 來使用 Suno？

在 Hermes Agent 設定中新增 custom:runapi provider，將 base_url 設為 https://runapi.ai/v1，api_key 從 RUNAPI_API_KEY 讀取。同一個 provider 可處理聊天、圖片、影片和音樂端點 — 不需要為 Suno 做獨立設定。

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

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

### 我可以生成不含人聲的純演奏曲目嗎？

可以。將 vocal_mode 設為 instrumental 並提供 style 和 title 欄位。prompt 和 lyrics 欄位在 instrumental 模式下必須省略。API 會強制這些跨欄位規則，如果傳送了衝突的欄位會回傳驗證錯誤。

### 除了 text_to_music 之外還有哪些 Suno 端點可用？

RunAPI 提供 cover_audio（重新編排現有曲目）、extend_music（從時間戳記延伸歌曲）、create_mashup（組合多首曲目的元素）、text_to_sound（音效），以及輔助端點如 generate_lyrics、generate_persona 和 separate_audio_stems。全部共用相同的 API key 和任務生命週期。


## Links

- [Hermes Agent 設定指南 →](https://runapi.ai/zh-HK/hermes-agent)
- [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)