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

# 音樂生成

> 創建音樂或歌詞任務，輪詢最終音頻，並安全地存儲面向用戶的音樂輸出。

音樂生成是異步的。 `POST /v1/music/generations` 創建一個公共的 TokenLab 任務並返回 `id` / `task_id`、`status`，通常還有 `poll_url`。您的應用程序應該存儲該任務身份，顯示進度，並輪詢直到達到終端狀態。

## 選擇工作流程

| 工作流程    | 關鍵字段                                                  | 備註                    |
| ------- | ----------------------------------------------------- | --------------------- |
| 完整歌曲或器樂 | `model`、`prompt`、可選的 `title`、`tags`、`action: "MUSIC"` | 當用戶期望最終音頻時使用          |
| 僅歌詞     | `model`、`prompt`、`action: "LYRICS"`                   | 僅與公開歌詞生成的模型一起使用       |
| 繼續現有片段  | `continue_clip_id`、可選的 `continue_at`                  | 在提供續集之前存儲之前的公共片段/任務身份 |

在發佈硬編碼模型列表之前查詢當前模型目錄：

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

當前的公共示例使用 `suno_music` 進行音樂生成。對於僅歌詞的流程，發送 `action: "LYRICS"` 與公開合同文件中包含歌詞生成的模型。將模型 ID 視為公共 TokenLab ID，而不是保證供應商特定字段是公共合同字段。

## 創建音樂任務

```bash theme={null}
curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "一首充滿活力的合成流行曲，帶有溫暖的聲音和清晰的合唱",
    "title": "晨間靜電",
    "tags": "合成流行、充滿活力",
    "action": "MUSIC"
  }'
```

保持提示、標題和標籤對用戶可見並安全存儲。不要在任何提示字段中放置 API 密鑰、私有 URL 或內部路由信息。

## 輪詢完成情況

首先使用 `poll_url`。如果您的客戶端需要固定路由，則使用返回的 `id` 或 `task_id` 調用 `GET /v1/tasks/{id}`。

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

預期的公共狀態為 `pending`、`processing`、`completed` 和 `failed`。完成的音樂任務可以包括 `audio_url`、`video_url`、`title`、`lyrics` 和標準化的元數據。將最終的 URL 存儲在您自己的數據庫中，以便用戶可以在不重新啟動生成的情況下重新打開結果。

## UI 和狀態處理

* 在任務創建後立即顯示待處理狀態。
* 對於長任務每 `5-10s` 輪詢一次，然後在 `completed` 或 `failed` 時停止。
* 在任務 `completed` 並且存在 `audio_url` 之前，不要顯示最終播放器。
* 對於僅歌詞的任務，將文本輸出與音頻任務分開渲染，以便用戶理解他們所購買的內容。
* 在刷新時，從存儲的 `task_id` 繼續，而不是創建新任務。

## 計費和對賬

音樂任務可以在創建時保留預估金額，並在知道終端狀態後結算。當 `request_id`、`task_id`、模型、端點和 `billing_transaction_id` 出現時進行存儲。使用管理 API 使用記錄進行對賬，而不是供應商任務 ID。

## 常見錯誤

| 症狀         | 可能原因                      | 修復                          |
| ---------- | ------------------------- | --------------------------- |
| 任務創建但沒有播放器 | 任務仍在待處理或完成但沒有 `audio_url` | 繼續輪詢直到終端，然後將缺失的輸出處理為失敗的用戶任務 |
| 刷新後重複歌曲    | UI 重新創建了任務而不是恢復           | 持久化並重用 `task_id`            |
| 歌詞任務返回無音頻  | `action: "LYRICS"` 僅為文本   | 將歌詞和音樂 UI 路徑分開              |
| 不支持的參數     | 字段不在模型公共合同中               | 刪除供應商特定字段或選擇一個記錄它們的模型       |

## API 參考

| 主題     | 參考                                                      |
| ------ | ------------------------------------------------------- |
| 創建音樂   | [創建音樂](/zh-Hant/api-reference/music/create-music)       |
| 獲取音樂狀態 | [獲取音樂狀態](/zh-Hant/api-reference/music/get-music-status) |
| 獲取任務狀態 | [獲取任務狀態](/zh-Hant/api-reference/tasks/get-task-status)  |
| 列出模型   | [列出模型](/zh-Hant/api-reference/models/list-models)       |
| 計費與定價  | [計費與定價](/zh-Hant/guides/billing)                        |