媒體指南
音樂生成
創作歌曲或歌詞,並等待音訊生成完成
音樂生成是非同步的。POST /v1/music/generations 會回傳一個任務 ID、狀態,以及通常會包含 poll_url。請使用該 ID 輪詢 GET /v1/tasks/{id},直到任務狀態變為 completed(已完成)或 failed(失敗)。
選擇創作內容
| 創作內容 | 關鍵欄位 | 備註 |
|---|---|---|
| 完整歌曲或純音樂 | model, mv, prompt, 選填 title, tags, action: "MUSIC" | 當使用者預期獲得最終音訊時使用 |
| 僅歌詞 | model, prompt, action: "LYRICS" | 僅適用於支援歌詞生成的模型 |
| 續寫現有片段 | model, mv, prompt, continue_clip_id, 選填 continue_at | 請保留先前的片段 ID |
| 翻唱或延伸您自己的音訊 | model, mv, prompt, audio_url, 選填 audio_operation | audio_url 必須為公開網址。audio_operation 預設為 upload-cover;upload-extend 亦需提供 continue_at |
| 加入伴奏、替換段落或分離音軌 | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, 或 advanced-split | 每種操作皆有其必要欄位;請參閱 建立音樂 |
從以下位置取得目前的音樂模型列表:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"下方的範例使用 suno-music 並搭配 mv: "chirp-v6"。其他音樂模型(例如 stable-audio-3)會使用不同的欄位,如 duration 和 output_format;請先閱讀該模型的詳細說明。若僅需歌詞,請選擇有記錄歌詞生成功能的模型,發送 action: "LYRICS",並省略 mv。
建立音樂任務
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-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'提示詞 (Prompts)、標題和標籤可能會出現在您的產品歷史記錄中。請勿在其中放置 API 金鑰、私人網址或診斷資料。
取得完成的音訊
使用回傳的 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://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}在 status 變為 completed 之前,不會出現最終媒體欄位。失敗的任務會回傳 status: "failed" 並附帶 error。
狀態包括 pending(待處理)、processing(處理中)、completed(已完成)和 failed(失敗)。已完成的任務可能包含 audio_url、video_url、title、lyrics 以及其他元資料。這些媒體網址為 TokenLab 網址,有效期為 30 天;若需長期保存,請下載或儲存結果。
顯示正確狀態
- 在任務建立後立即顯示待處理狀態。
- 長時間任務請每
5-10s輪詢一次,直到狀態變為completed或failed為止。 - 在任務變為
completed且存在audio_url之前,請勿顯示最終播放器。 - 對於僅歌詞的任務,請將文字輸出與音訊任務分開呈現,以便使用者了解他們所購買的內容。
- 重新整理頁面時,請從儲存的
task_id恢復,而非建立新任務。
帳務記錄
音樂任務在建立時可能會預留預估金額。最終金額會在完成或失敗後記錄。請在出現時儲存 request_id、task_id、模型、端點以及 billing_transaction_id;最終扣款請使用 Management API 的使用記錄。
常見錯誤
| 徵狀 | 可能原因 | 解決方法 |
|---|---|---|
| 任務已建立但無播放器 | 任務仍在處理中,或完成但無 audio_url | 持續輪詢直到終止狀態,若最終仍無輸出則視為使用者作業失敗處理 |
| 重新整理後出現重複歌曲 | UI 重新建立了任務而非恢復 | 持續並重複使用 task_id |
| 歌詞任務未回傳音訊 | action: "LYRICS" 僅限文字 | 分開歌詞與音樂的 UI 路徑 |
| 不支援的參數 | 所選模型不接受該欄位 | 移除該欄位或選擇有記錄該欄位的模型 |