API 參考

音樂

POST/v1/music/generations

GET/v1/music/tasks/{task_id}

GET/v1/music/tasks/{task_id}/content

面向歌曲與純音樂流程的非同步音樂生成。提交後立即回傳 task_id；隨後輪詢任務或接收 webhook 回呼，再從 /content 讀取成品音訊。

#請求參數

modelstring必填
音樂模型 ID，見模型頁，例如 suno。
promptstring必填
描述歌曲內容、情緒、編制或歌詞方向。
titlestring選填
可選曲目標題；會轉發給支援該欄位的模型家族。
tagsstring | array選填
可選風格或流派提示，如 cinematic、pop、ambient。
versionstring選填
當供應商提供多個代際版本時，用於切換模型版本。
mvstring選填
供應商特定的音樂模式選擇器；除非使用者真的需要顯式控制，否則建議留在伺服器端。
instrumentalboolean選填
在模型支援時，生成不含人聲的純音樂輸出。
make_instrumentalboolean選填
另一種供應商用於純音樂輸出的開關；部分供應商使用它而不是 instrumental。
continue_clip_idstring選填
基於已有片段續寫或延長，而不是新開一首。
continue_atnumber選填
續寫流程中的起始秒數位置。
webhook_urlstring選填
任務進入終態後回呼的 HTTPS 網址。
webhook_secretstring選填
設定後，回呼帶 X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret))。

先從簡單版開始

對大多數產品來說，首版接入只用 prompt 就夠了。title、tags、version 以及續寫相關欄位都屬於進階控制項，只有業務明確需要時再補。

與其他媒體任務一致的非同步契約

音樂和圖片、影片任務遵循同一套提交 → 輪詢或 webhook → /content 模式，因此後端通常用同一套任務執行器就能統一承接。

#相關錯誤碼

404 not_found路徑不存在、模型名稱不存在，或 task_id 已過期 / 不屬於目前帳號。
422 unprocessable_entity上游拒絕了閘道轉發的參數值（如不支援的尺寸或時長）。
401Bearer 權杖無效或缺失。這條路徑不帶 error.code，請依狀態碼判斷。
402 insufficient_user_quota錢包餘額不足以覆蓋預扣估算。
429金鑰級限流。回應主體為空，按 Retry-After 等待。若 429 帶有 insufficient_user_quota，那是每日消費上限，不是限流。
503 model_not_found模型名稱不存在，或目前沒有健康的通道可以提供服務。

完整錯誤碼表 →

#請求範例

# submit
curl https://www.aisplice.store/v1/music/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "a warm cinematic piano theme",
    "instrumental": true
  }'

# poll every 5s
curl https://www.aisplice.store/v1/music/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# fetch the finished track
curl -L https://www.aisplice.store/v1/music/tasks/$TASK_ID/content \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -o song.mp3

#回應

response.json

// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/music/tasks/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",
  "progress": "42%"
}

// GET /v1/music/tasks/{task_id}/content
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {
    "audio_url": "https://…",
    "lyric": "…"
  }
}

還是沒解決？

把請求 ID 或錯誤訊息傳給我們，我們來查。