Desarrolladores
Documentación de la API
Todo lo que necesitas para desarrollar con la API de MeloLab: autenticación, créditos, generación, trabajos, webhooks y búsqueda en la biblioteca.
Primeros pasos
Autentica cada solicitud con tu clave API mediante la cabecera Authorization: Bearer. La URL base es https://melolab.ai. Los endpoints de lectura no consumen créditos; crear una generación usa tus créditos de MeloLab existentes, con las mismas reglas de coste y reembolso que la app web. Envía una cabecera Idempotency-Key al crear una generación para que los reintentos sean seguros. Las respuestas correctas se envuelven en un objeto data; los errores devuelven code, message y request_id.
Cuenta
Consulta tu perfil de API, saldo de créditos y uso reciente.
Devuelve el perfil de API autenticado, incluidos el nivel de cuenta y la disponibilidad de la API.
curl -X GET https://melolab.ai/api/v1/me \
-H "Authorization: Bearer $MELOLAB_API_KEY"Devuelve tu saldo de créditos de MeloLab existente. No consume créditos.
curl -X GET https://melolab.ai/api/v1/credits \
-H "Authorization: Bearer $MELOLAB_API_KEY"Devuelve un resumen de uso y eventos de solicitud recientes y anonimizados.
curl -X GET https://melolab.ai/api/v1/usage \
-H "Authorization: Bearer $MELOLAB_API_KEY"Modelos
Lista los modelos de MeloLab disponibles y su coste en créditos.
Lista los modelos de MeloLab disponibles con su coste en créditos.
curl -X GET https://melolab.ai/api/v1/models \
-H "Authorization: Bearer $MELOLAB_API_KEY"Devuelve un modelo por su id.
curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Generaciones
Crea una generación de música, lista las generaciones recientes y consulta un trabajo hasta que termine.
Crea una generación de música asíncrona. Usa tus créditos de MeloLab existentes; requiere una cabecera 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 tus trabajos de generación recientes.
curl -X GET https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY"Consulta una generación y devuelve sus pistas una vez completada.
curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Consulta un trabajo asíncrono (música, separación de stems o eliminación de voz) y devuelve las salidas cuando el proveedor termina.
curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Biblioteca
Busca pistas y listas de reproducción reproducibles, y consulta los detalles de una pista o lista.
Busca pistas y listas de reproducción reproducibles, incluidos tus elementos privados.
curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
-H "Authorization: Bearer $MELOLAB_API_KEY"Devuelve los metadatos reproducibles de una pista.
curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Lista las listas de reproducción a las que tienes acceso.
curl -X GET https://melolab.ai/api/v1/playlists \
-H "Authorization: Bearer $MELOLAB_API_KEY"Devuelve una lista de reproducción y sus pistas.
curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Webhooks
Registra endpoints HTTPS para recibir notificaciones cuando terminen los trabajos asíncronos, sin tener que consultar. El secreto de firma completo se muestra solo una vez al crear un endpoint.
Lista tus endpoints de webhook activos.
curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY"Registra un endpoint de webhook HTTPS público. El secreto de firma se devuelve solo una 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"}'Actualiza la URL o el estado de un 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"}'Elimina un endpoint de webhook.
curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Registros
Revisa los registros de solicitudes API de los últimos 30 días.
Lista los registros de solicitudes API de los últimos 30 días.
curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Límites de tasa
Los endpoints de lectura permiten 600 solicitudes por minuto (50.000 por día). La generación de música permite 12 solicitudes por minuto (500 por día). La autenticación se limita a 120 solicitudes por minuto por IP. Superar un límite devuelve 429 rate_limited.
Errores
Los errores devuelven un estado HTTP más un cuerpo JSON { error: { code, message, request_id } }. Incluye request_id al contactar con soporte.
| Estado | Código | Significado |
|---|---|---|
| 401 | authentication_required | No se proporcionó una clave API en el encabezado Authorization. |
| 401 | invalid_api_key | La clave API es inválida o está revocada. |
| 403 | insufficient_scope | La clave API carece de un alcance requerido. |
| 400 | invalid_request | El cuerpo o los parámetros de la solicitud son inválidos. |
| 400 | invalid_model | El id de modelo solicitado no existe. |
| 402 | insufficient_credits | No hay suficientes créditos de MeloLab para crear esta generación. |
| 409 | idempotency_conflict | La Idempotency-Key se reutilizó con un cuerpo de solicitud diferente. |
| 404 | not_found | El recurso solicitado no se encontró o no es tuyo. |
| 429 | rate_limited | Demasiadas solicitudes; reduce el ritmo y reinténtalo más tarde. |
| 502 | provider_unavailable | El proveedor de origen no está disponible temporalmente. |
