TokenLab

媒體指南

音樂生成

創作歌曲或歌詞,並等待音訊生成完成

音樂生成是非同步的。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_operationaudio_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 路徑
不支援的參數所選模型不接受該欄位移除該欄位或選擇有記錄該欄位的模型

API 參考

主題參考
建立音樂建立音樂
取得音樂狀態取得音樂狀態
取得任務狀態取得任務狀態
列出模型列出模型
帳務與定價帳務與定價

本頁內容