音樂
建立音樂
建立音樂、歌詞或音效生成任務
使用 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。
請求主體
suno-music音樂模型 ID,例如 suno-music 或 stable-audio-3。請明確傳送此參數。若僅需歌詞,請選擇目前公開操作包含 lyrics 的模型。
音樂描述或替換文字。適用於音樂、歌詞、upload-cover、upload-extend 和 replace-section 時為必填;適用於 add-instrumental 和分軌(stem separation)時為選填。
生成歌曲的標題。
風格標籤(例如 "pop, upbeat, electronic")。
欲排除的風格。當 audio_operation 為 add-instrumental 時為必填。
選填值,可為 MUSIC 或 LYRICS。請選擇支援對應公開操作的模型;此欄位不會為僅支援音樂的模型增添歌詞功能。
Suno 版本選擇器。在進行生成、upload-cover、upload-extend、add-instrumental 以及從 audio_url 替換時為必填。若為歌詞、從 task_id + audio_id 替換以及分軌,則請略過。可接受的值:chirp-v6、chirp-v6-mini、chirp-v6-wild。
設為 true 可生成無人聲的純音樂。
可公開存取的參考音訊或上傳音訊的 URL。在未提供 audio_operation 的情況下傳入時,TokenLab 將使用 upload-cover 流程。
音訊操作: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 秒之間。
屬於您組織的來源任務 ID,用於生成音訊替換或分軌。
來源任務結果中返回的來源音訊 ID。與 task_id 一同用於生成音訊替換和分軌時為必填。
替換起始時間(秒),至少為 0。使用 replace-section 時為必填。
替換結束時間(秒)。使用 replace-section 時為必填;必須在 infill_start_s 之後的 6 到 60 秒。
生成歌曲的完整歌詞。使用 replace-section 時為必填。
音軌名稱(Stem name)。使用 advanced-split 時為必填。
欲接續延伸的前一段音訊片段 ID。
接續延伸的時間點(秒)。使用 upload-extend 時為必填且必須大於 0。
生成音訊的長度(秒),範圍為 1 到 380。僅適用於有列出此欄位的模型(例如 stable-audio-3);具體限制請參閱該模型的詳細資訊。
模型所列出的音訊檔案格式,例如 mp3、wav 或 flac。僅適用於有列出此項的模型。
用於可重現輸出的隨機種子,範圍為 0 到 4294967294。僅適用於有列出此欄位的模型。
生成步驟的數量。範圍取決於模型(例如 stable-audio-3 為 4 到 8)。僅適用於有列出此參數的模型。
部分模型會列出更多欄位,例如 negative_prompt、n、seconds 和 guidance_scale。請僅在模型詳細資訊中列出這些欄位時才發送;若傳送了所選模型不支援的欄位,將會回傳 400 錯誤。
提示詞引導強度,範圍為 1 到 25。僅適用於有列出此欄位的模型。
prompt 最多可接受 5000 個字元;tags 和 negative_tags 各自最多可接受 1000 個字元。支援的操作與參數取決於所選模型目前的詳細設定。
回應
用於輪詢狀態的任務 ID。
返回時作為同一個非同步任務 ID 的別名。
此任務的狀態查詢 URL。請使用 id 輪詢 GET /v1/tasks/{id}。
任務狀態:pending、processing、completed 或 failed。
任務建立時間(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"
}回應
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "suno-music"
}授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json