開發者
API 文件
用 MeloLab API 建構所需的一切：認證、點數、生成、任務、webhook 與曲庫搜尋。
快速開始
每個請求都需用 API 金鑰透過 Authorization: Bearer 標頭進行認證。基礎網址為 https://melolab.ai。讀取類端點不消耗點數；建立生成會使用你現有的 MeloLab 點數，費用與退款規則與網頁版一致。建立生成時請帶上 Idempotency-Key 標頭，以便安全重試。成功回應包裹在 data 物件中；錯誤會回傳 code、message 與 request_id。
帳戶
讀取你的 API 資料、點數餘額與近期用量。
回傳已認證的 API 資料，包括帳戶等級與 API 可用狀態。
curl -X GET https://melolab.ai/api/v1/me \
-H "Authorization: Bearer $MELOLAB_API_KEY"回傳你現有的 MeloLab 點數餘額。不消耗點數。
curl -X GET https://melolab.ai/api/v1/credits \
-H "Authorization: Bearer $MELOLAB_API_KEY"回傳用量摘要以及近期已去識別化的請求事件。
curl -X GET https://melolab.ai/api/v1/usage \
-H "Authorization: Bearer $MELOLAB_API_KEY"模型
列出可用的 MeloLab 模型及其點數成本。
列出可用的 MeloLab 模型及其點數成本。
curl -X GET https://melolab.ai/api/v1/models \
-H "Authorization: Bearer $MELOLAB_API_KEY"依 id 回傳單一模型。
curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
-H "Authorization: Bearer $MELOLAB_API_KEY"生成
建立音樂生成、列出近期生成，並輪詢任務直到完成。
建立非同步音樂生成。使用你現有的 MeloLab 點數；需要 Idempotency-Key 標頭。
curl -X POST https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model_id":"suno/v5-5","prompt":"warm lofi beat for a focus playlist"}'列出你近期的生成任務。
curl -X GET https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY"輪詢某次生成，完成後回傳其曲目。
curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"輪詢非同步任務（音樂、分軌或去人聲），在服務商完成後回傳輸出。
curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"曲庫
搜尋可播放的曲目與播放清單，並讀取個別曲目或播放清單的詳情。
搜尋可播放的曲目與播放清單，包括你自己的私有內容。
curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
-H "Authorization: Bearer $MELOLAB_API_KEY"回傳某個曲目的可播放中繼資料。
curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"列出你可存取的播放清單。
curl -X GET https://melolab.ai/api/v1/playlists \
-H "Authorization: Bearer $MELOLAB_API_KEY"回傳某個播放清單及其曲目。
curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Webhook
註冊 HTTPS 端點，在非同步任務完成時收到通知，無需輪詢。完整的簽章金鑰僅在建立端點時顯示一次。
列出你的有效 webhook 端點。
curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY"註冊一個公開的 HTTPS webhook 端點。簽章金鑰僅回傳一次。
curl -X POST https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/melolab/webhook"}'更新 webhook 端點的 URL 或狀態。
curl -X PATCH https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"disabled"}'刪除一個 webhook 端點。
curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"日誌
查看最近 30 天的 API 請求日誌。
列出最近 30 天的 API 請求日誌。
curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
-H "Authorization: Bearer $MELOLAB_API_KEY"速率限制
讀取類端點每分鐘 600 次（每天 50,000 次）。音樂生成每分鐘 12 次（每天 500 次）。認證依 IP 每分鐘 120 次。超出限制回傳 429 rate_limited。
錯誤
錯誤會回傳 HTTP 狀態碼，以及 { error: { code, message, request_id } } 的 JSON 主體。聯絡支援時請附上 request_id。
| 狀態碼 | 錯誤碼 | 含義 |
|---|---|---|
| 401 | authentication_required | Authorization 標頭中未提供 API 金鑰。 |
| 401 | invalid_api_key | API 金鑰無效或已被撤銷。 |
| 403 | insufficient_scope | API 金鑰缺少所需的權限範圍。 |
| 400 | invalid_request | 請求主體或參數無效。 |
| 400 | invalid_model | 請求的模型 id 不存在。 |
| 402 | insufficient_credits | MeloLab 點數不足，無法建立此次生成。 |
| 409 | idempotency_conflict | Idempotency-Key 被用於不同的請求主體。 |
| 404 | not_found | 請求的資源不存在或不屬於你。 |
| 429 | rate_limited | 請求過多；請放慢速度稍後重試。 |
| 502 | provider_unavailable | 上游服務商暫時無法使用。 |
