开发者
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 | 上游服务商暂时不可用。 |
