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.

GET/api/v1/meprofile:read

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"

GET/api/v1/creditscredits:read

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"

GET/api/v1/usageprofile:read

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.

GET/api/v1/modelsmodels:read

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"

GET/api/v1/models/{model_id}models:read

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.

POST/api/v1/generationsgenerations:create

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"}'

GET/api/v1/generationsgenerations:read

Lista tus trabajos de generación recientes.

curl -X GET https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/generations/{id}generations:read

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"

GET/api/v1/jobs/{job_id}

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.

GET/api/v1/library/searchlibrary:read

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"

GET/api/v1/tracks/{id}library:read

Devuelve los metadatos reproducibles de una pista.

curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlistslibrary:read

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"

GET/api/v1/playlists/{id}library:read

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.

GET/api/v1/webhook-endpoints

Lista tus endpoints de webhook activos.

curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

POST/api/v1/webhook-endpoints

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"}'

PATCH/api/v1/webhook-endpoints/{id}

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"}'

DELETE/api/v1/webhook-endpoints/{id}

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.

GET/api/v1/logs

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.
401	revoked_api_key	La clave API fue revocada y ya no se puede usar.
403	api_terms_not_accepted	La cuenta API aún no está lista porque no se aceptaron los términos de la API.
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.
400	idempotency_key_required	Esta solicitud requiere un encabezado Idempotency-Key.
409	idempotency_key_conflict	La Idempotency-Key se reutilizó con una forma de solicitud diferente.
409	idempotency_conflict	La Idempotency-Key se reutilizó con un cuerpo de solicitud diferente.
409	generation_concurrency_exceeded	Ya hay demasiados trabajos de generación en ejecución para esta cuenta.
404	job_not_found	El trabajo solicitado no existe o no pertenece a esta cuenta.
404	track_not_found	La pista solicitada no existe o no es accesible para esta cuenta.
404	playlist_not_found	La lista solicitada no existe o no es accesible para esta cuenta.
404	webhook_endpoint_not_found	El endpoint webhook solicitado no existe o no es tuyo.
400	webhook_url_invalid	La URL del webhook no es válida.
400	webhook_https_required	Los endpoints webhook deben usar HTTPS.
400	webhook_credentials_forbidden	Las URL de webhook no pueden incluir credenciales incrustadas.
400	webhook_host_blocked	Las URL de webhook no pueden apuntar a localhost, hosts privados o bloqueados.
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.
502	provider_timeout	El proveedor de origen agotó el tiempo de espera.
500	generation_failed	La generación falló después de ser aceptada.
500	internal_error	Error inesperado de la plataforma API.

Documentación de la API

Primeros pasos

Cuenta

Modelos

Generaciones

Biblioteca

Webhooks

Registros

Límites de tasa

Errores

Empezar gratis

Crear

Transform

Analyze

Empresa