媒體指南
音樂生成
創建音樂或歌詞任務，輪詢最終音頻，並安全地存儲面向用戶的音樂輸出。
音樂生成是異步的。 POST /v1/music/generations 創建一個公共的 TokenLab 任務並返回 id / task_id、status，通常還有 poll_url。您的應用程序應該存儲該任務身份，顯示任務狀態，並輪詢直到達到終端狀態。
選擇工作流程
| 工作流程 | 關鍵字段 | 備註 |
|---|---|---|
| 完整歌曲或器樂 | model、mv、prompt、可選的 title、tags、action: "MUSIC" | 當用戶期望最終音頻時使用 |
| 僅歌詞 | model、prompt、action: "LYRICS" | 僅與公開歌詞生成的模型一起使用 |
| 繼續現有片段 | continue_clip_id、可選的 continue_at | 在提供續集之前存儲之前的公共片段/任務身份 |
在發佈硬編碼模型列表之前查詢當前模型目錄：
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"當前的公共示例使用 suno_music 進行音樂生成，並在 mv 中傳入 chirp-v4 等官方 Suno 模型版本。對於僅歌詞的流程，發送 action: "LYRICS" 與模型詳情文件中包含歌詞生成的模型，並省略 mv。將模型 ID 視為公共 TokenLab ID，而不是保證供應商特定字段是支持说明字段。
創建音樂任務
curl https://api.tokenlab.sh/v1/music/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "suno_music",
"mv": "chirp-v4",
"prompt": "一首充滿活力的合成流行曲，帶有溫暖的聲音和清晰的合唱",
"title": "晨間靜電",
"tags": "合成流行、充滿活力",
"action": "MUSIC"
}'保持提示、標題和標籤對用戶可見並安全存儲。不要在任何提示字段中放置 API 密鑰、私有 URL 或私有調試信息。
輪詢完成情況
首先使用 poll_url。如果您的客戶端需要固定路由，則使用返回的 id 或 task_id 調用 GET /v1/tasks/{id}。
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"回應結構
建立接口返回的是可輪詢的任務記錄，不是最終音訊：
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno_music"
}輪詢到完成後，回應可以包含最終媒體欄位：
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://cdn.example.com/music/abc123.mp3",
"video_url": "https://cdn.example.com/music/abc123.mp4",
"stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
"image_url": "https://cdn.example.com/music/cover.jpg",
"title": "晨間靜電",
"lyrics": "[Verse 1]\n..."
}最終媒體欄位只會在 status 為 completed 後出現。失敗任務會返回 status: "failed"，並帶有 error。
預期的公共狀態為 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 路徑分開 |
| 不支持的參數 | 字段不在模型支持说明中 | 刪除供應商特定字段或選擇一個記錄它們的模型 |