TokenLab

音樂

建立音樂

建立音樂、歌詞或音效生成任務

POST
/v1/music/generations

使用 GET /v1/models?recommended_for=music 取得目前的音樂模型。

透過 AI 生成音樂、歌詞與音效。此為非同步 API。建立請求的回應會返回任務識別碼。請使用該識別碼輪詢 GET /v1/tasks/{id} 以獲取狀態。

各模型接受的欄位有所不同。傳送選填欄位前請先查詢 GET /v1/models/{model};若傳送模型未列出的欄位可能會返回 400 unsupported_parameter。Suno 欄位(mv、title、tags、negative_tags、audio_operation 及其關聯欄位)適用於 Suno 模型。不支援 user 欄位,傳入將返回 400。

請求主體

modelstring預設值: suno-music

音樂模型 ID,例如 suno-music 或 stable-audio-3。請明確傳送此參數。若僅需歌詞,請選擇目前公開操作包含 lyrics 的模型。

promptstring

音樂描述或替換文字。適用於音樂、歌詞、upload-cover、upload-extend 和 replace-section 時為必填;適用於 add-instrumental 和分軌(stem separation)時為選填。

titlestring

生成歌曲的標題。

tagsstring

風格標籤(例如 "pop, upbeat, electronic")。

negative_tagsstring

欲排除的風格。當 audio_operation 為 add-instrumental 時為必填。

actionstring

選填值,可為 MUSIC 或 LYRICS。請選擇支援對應公開操作的模型;此欄位不會為僅支援音樂的模型增添歌詞功能。

mvstring

Suno 版本選擇器。在進行生成、upload-cover、upload-extend、add-instrumental 以及從 audio_url 替換時為必填。若為歌詞、從 task_id + audio_id 替換以及分軌,則請略過。可接受的值:chirp-v6、chirp-v6-mini、chirp-v6-wild。

make_instrumentalboolean

設為 true 可生成無人聲的純音樂。

audio_urlstring

可公開存取的參考音訊或上傳音訊的 URL。在未提供 audio_operation 的情況下傳入時,TokenLab 將使用 upload-cover 流程。

audio_operationstring

音訊操作:upload-cover、upload-extend、add-instrumental、replace-section、vocal-separate、multi-stem-separation、advanced-split。

vocal-separate、multi-stem-separation 和 advanced-split 需要 task_id + audio_id;advanced-split 還需要 stem_name。upload-extend 需要大於 0 的 continue_at。add-instrumental 需要 audio_url、title、tags 和 negative_tags。

若使用 replace-section,請傳送 prompt、tags、title、infill_start_s、infill_end_s 和 full_lyrics。必須二擇一選擇來源:task_id + audio_id,或 audio_url + mv。替換區間必須介於 6 到 60 秒之間。

task_idstring

屬於您組織的來源任務 ID,用於生成音訊替換或分軌。

audio_idstring

來源任務結果中返回的來源音訊 ID。與 task_id 一同用於生成音訊替換和分軌時為必填。

infill_start_snumber

替換起始時間(秒),至少為 0。使用 replace-section 時為必填。

infill_end_snumber

替換結束時間(秒)。使用 replace-section 時為必填;必須在 infill_start_s 之後的 6 到 60 秒。

full_lyricsstring

生成歌曲的完整歌詞。使用 replace-section 時為必填。

stem_namestring

音軌名稱(Stem name)。使用 advanced-split 時為必填。

continue_clip_idstring

欲接續延伸的前一段音訊片段 ID。

continue_atnumber

接續延伸的時間點(秒)。使用 upload-extend 時為必填且必須大於 0。

durationinteger

生成音訊的長度(秒),範圍為 1 到 380。僅適用於有列出此欄位的模型(例如 stable-audio-3);具體限制請參閱該模型的詳細資訊。

output_formatstring

模型所列出的音訊檔案格式,例如 mp3、wav 或 flac。僅適用於有列出此項的模型。

seedinteger

用於可重現輸出的隨機種子,範圍為 0 到 4294967294。僅適用於有列出此欄位的模型。

stepsinteger

生成步驟的數量。範圍取決於模型(例如 stable-audio-3 為 4 到 8)。僅適用於有列出此參數的模型。

部分模型會列出更多欄位,例如 negative_prompt、n、seconds 和 guidance_scale。請僅在模型詳細資訊中列出這些欄位時才發送;若傳送了所選模型不支援的欄位,將會回傳 400 錯誤。

cfg_scalenumber

提示詞引導強度,範圍為 1 到 25。僅適用於有列出此欄位的模型。

prompt 最多可接受 5000 個字元;tags 和 negative_tags 各自最多可接受 1000 個字元。支援的操作與參數取決於所選模型目前的詳細設定。

回應

idstring

用於輪詢狀態的任務 ID。

task_idstring

返回時作為同一個非同步任務 ID 的別名。

poll_urlstring

此任務的狀態查詢 URL。請使用 id 輪詢 GET /v1/tasks/{id}。

statusstring

任務狀態:pending、processing、completed 或 failed。

createdinteger

任務建立時間(Unix 時間戳記),於返回時提供。

請求

curl -X POST "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 electronic dance track with heavy bass",
    "title": "Night Drive",
    "tags": "electronic, EDM, energetic"
  }'

適用於接受 duration 和 output_format 而非 Suno 欄位之模型的音效生成範例:

{
  "model": "stable-audio-3",
  "prompt": "Warm lo-fi beat with soft vinyl crackle",
  "duration": 30,
  "output_format": "mp3"
}

回應

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。

長度1 <= length <= 255

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json

application/json