Developers
API documentation
Everything you need to build with the MeloLab API: authentication, credits, generation, jobs, webhooks, and library search.
Getting started
Authenticate every request with your API key using the Authorization: Bearer header. The base URL is https://melolab.ai. Read endpoints do not use credits; creating a generation uses your existing MeloLab credits with the same cost and refund rules as the web app. Send an Idempotency-Key header when creating a generation so retries are safe. Successful responses are wrapped in a data object; errors return a code, message, and request_id.
Account
Read your API profile, credit balance, and recent usage.
Return the authenticated API profile, including account tier and API availability.
curl -X GET https://melolab.ai/api/v1/me \
-H "Authorization: Bearer $MELOLAB_API_KEY"Return your existing MeloLab credit balance. Does not use credits.
curl -X GET https://melolab.ai/api/v1/credits \
-H "Authorization: Bearer $MELOLAB_API_KEY"Return a usage summary and recent, redacted request events.
curl -X GET https://melolab.ai/api/v1/usage \
-H "Authorization: Bearer $MELOLAB_API_KEY"Models
List available MeloLab models and their credit cost.
List available MeloLab models with their credit cost.
curl -X GET https://melolab.ai/api/v1/models \
-H "Authorization: Bearer $MELOLAB_API_KEY"Return one model by id.
curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Generations
Create a music generation, list recent generations, and poll a job until it finishes.
Create an async music generation. Uses your existing MeloLab credits; requires an Idempotency-Key header.
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"}'List your recent generation jobs.
curl -X GET https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY"Poll a generation and return its tracks once completed.
curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Poll an async job (music, stem split, or vocal removal) and return outputs when the provider finishes.
curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Library
Search playable tracks and playlists, and read individual track or playlist details.
Search playable tracks and playlists, including your own private items.
curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
-H "Authorization: Bearer $MELOLAB_API_KEY"Return playable metadata for a track.
curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"List playlists available to you.
curl -X GET https://melolab.ai/api/v1/playlists \
-H "Authorization: Bearer $MELOLAB_API_KEY"Return a playlist and its tracks.
curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Webhooks
Register HTTPS endpoints to be notified when async jobs finish, so you do not have to poll. The full signing secret is shown only once when you create an endpoint.
List your active webhook endpoints.
curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY"Register a public HTTPS webhook endpoint. The signing secret is returned only once.
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"}'Update a webhook endpoint URL or status.
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"}'Delete a webhook endpoint.
curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Logs
Review recent API request logs from the last 30 days.
List recent API request logs from the last 30 days.
curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Rate limits
Read endpoints allow 600 requests per minute (50,000 per day). Music generation allows 12 requests per minute (500 per day). Authentication is limited to 120 requests per minute per IP. Exceeding a limit returns 429 rate_limited.
Errors
Errors return an HTTP status plus a JSON body of { error: { code, message, request_id } }. Include request_id when contacting support.
| Status | Code | Meaning |
|---|---|---|
| 401 | authentication_required | No API key was provided in the Authorization header. |
| 401 | invalid_api_key | The API key is invalid or revoked. |
| 403 | insufficient_scope | The API key lacks a required scope. |
| 400 | invalid_request | The request body or parameters are invalid. |
| 400 | invalid_model | The requested model id does not exist. |
| 402 | insufficient_credits | Not enough MeloLab credits to create this generation. |
| 409 | idempotency_conflict | The Idempotency-Key was reused with a different request body. |
| 404 | not_found | The requested resource was not found or is not yours. |
| 429 | rate_limited | Too many requests; slow down and retry later. |
| 502 | provider_unavailable | The upstream provider is temporarily unavailable. |
