Desenvolvedores
Documentação da API
Tudo o que você precisa para construir com a API do MeloLab: autenticação, créditos, geração, jobs, webhooks e busca na biblioteca.
Primeiros passos
Autentique cada requisição com sua chave de API usando o cabeçalho Authorization: Bearer. A URL base é https://melolab.ai. Endpoints de leitura não consomem créditos; criar uma geração usa seus créditos MeloLab existentes, com as mesmas regras de custo e reembolso do app web. Envie um cabeçalho Idempotency-Key ao criar uma geração para que novas tentativas sejam seguras. Respostas bem-sucedidas são encapsuladas em um objeto data; erros retornam code, message e request_id.
Conta
Leia seu perfil de API, saldo de créditos e uso recente.
Retorna o perfil de API autenticado, incluindo o nível da conta e a disponibilidade da API.
curl -X GET https://melolab.ai/api/v1/me \
-H "Authorization: Bearer $MELOLAB_API_KEY"Retorna seu saldo de créditos MeloLab existente. Não consome créditos.
curl -X GET https://melolab.ai/api/v1/credits \
-H "Authorization: Bearer $MELOLAB_API_KEY"Retorna um resumo de uso e eventos de requisição recentes e anonimizados.
curl -X GET https://melolab.ai/api/v1/usage \
-H "Authorization: Bearer $MELOLAB_API_KEY"Modelos
Liste os modelos MeloLab disponíveis e seu custo em créditos.
Lista os modelos MeloLab disponíveis com seu custo em créditos.
curl -X GET https://melolab.ai/api/v1/models \
-H "Authorization: Bearer $MELOLAB_API_KEY"Retorna um modelo pelo id.
curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Gerações
Crie uma geração de música, liste as gerações recentes e consulte um job até ele terminar.
Cria uma geração de música assíncrona. Usa seus créditos MeloLab existentes; requer um cabeçalho 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"}'Lista seus jobs de geração recentes.
curl -X GET https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY"Consulta uma geração e retorna suas faixas quando concluída.
curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Consulta um job assíncrono (música, separação de stems ou remoção de vocal) e retorna as saídas quando o provedor termina.
curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Biblioteca
Pesquise faixas e playlists reproduzíveis e leia os detalhes de faixas ou playlists individuais.
Pesquisa faixas e playlists reproduzíveis, incluindo seus itens privados.
curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
-H "Authorization: Bearer $MELOLAB_API_KEY"Retorna os metadados reproduzíveis de uma faixa.
curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Lista as playlists disponíveis para você.
curl -X GET https://melolab.ai/api/v1/playlists \
-H "Authorization: Bearer $MELOLAB_API_KEY"Retorna uma playlist e suas faixas.
curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Webhooks
Registre endpoints HTTPS para ser notificado quando os jobs assíncronos terminarem, sem precisar consultar. O segredo de assinatura completo é mostrado apenas uma vez ao criar um endpoint.
Lista seus endpoints de webhook ativos.
curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY"Registra um endpoint de webhook HTTPS público. O segredo de assinatura é retornado apenas uma vez.
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"}'Atualiza a URL ou o status de um endpoint de webhook.
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"}'Exclui um endpoint de webhook.
curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Logs
Revise os logs de requisições da API dos últimos 30 dias.
Lista os logs de requisições da API dos últimos 30 dias.
curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Limites de taxa
Endpoints de leitura permitem 600 requisições por minuto (50.000 por dia). A geração de música permite 12 requisições por minuto (500 por dia). A autenticação é limitada a 120 requisições por minuto por IP. Exceder um limite retorna 429 rate_limited.
Erros
Os erros retornam um status HTTP mais um corpo JSON { error: { code, message, request_id } }. Inclua request_id ao contatar o suporte.
| Status | Código | Significado |
|---|---|---|
| 401 | authentication_required | Nenhuma chave de API foi fornecida no cabeçalho Authorization. |
| 401 | invalid_api_key | A chave de API é inválida ou foi revogada. |
| 403 | insufficient_scope | A chave de API não tem um escopo obrigatório. |
| 400 | invalid_request | O corpo ou os parâmetros da requisição são inválidos. |
| 400 | invalid_model | O id de modelo solicitado não existe. |
| 402 | insufficient_credits | Créditos MeloLab insuficientes para criar esta geração. |
| 409 | idempotency_conflict | A Idempotency-Key foi reutilizada com um corpo de requisição diferente. |
| 404 | not_found | O recurso solicitado não foi encontrado ou não é seu. |
| 429 | rate_limited | Muitas requisições; reduza o ritmo e tente novamente mais tarde. |
| 502 | provider_unavailable | O provedor upstream está temporariamente indisponível. |
