Sviluppatori

Documentazione dell’API

Tutto ciò che serve per sviluppare con l’API MeloLab: autenticazione, crediti, generazione, job, webhook e ricerca nella libreria.

Per iniziare

Autentica ogni richiesta con la tua chiave API tramite l’header Authorization: Bearer. L’URL di base è https://melolab.ai. Gli endpoint di lettura non consumano crediti; creare una generazione usa i tuoi crediti MeloLab esistenti, con le stesse regole di costo e rimborso dell’app web. Invia un header Idempotency-Key quando crei una generazione, così i tentativi ripetuti sono sicuri. Le risposte riuscite sono racchiuse in un oggetto data; gli errori restituiscono code, message e request_id.

Account

Leggi il tuo profilo API, il saldo dei crediti e l’utilizzo recente.

GET/api/v1/meprofile:read

Restituisce il profilo API autenticato, incluso il livello dell’account e la disponibilità dell’API.

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

GET/api/v1/creditscredits:read

Restituisce il tuo saldo di crediti MeloLab esistente. Non consuma crediti.

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

GET/api/v1/usageprofile:read

Restituisce un riepilogo dell’utilizzo ed eventi di richiesta recenti e anonimizzati.

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

Modelli

Elenca i modelli MeloLab disponibili e il loro costo in crediti.

GET/api/v1/modelsmodels:read

Elenca i modelli MeloLab disponibili con il loro costo in crediti.

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

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

Restituisce un modello tramite id.

curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Generazioni

Crea una generazione musicale, elenca le generazioni recenti e interroga un job fino al completamento.

POST/api/v1/generationsgenerations:create

Crea una generazione musicale asincrona. Usa i tuoi crediti MeloLab esistenti; richiede un header 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

Elenca i tuoi job di generazione recenti.

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

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

Interroga una generazione e ne restituisce le tracce una volta completata.

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

GET/api/v1/jobs/{job_id}

Interroga un job asincrono (musica, separazione stem o rimozione voce) e restituisce gli output al termine del provider.

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

Libreria

Cerca tracce e playlist riproducibili e leggi i dettagli di singole tracce o playlist.

GET/api/v1/library/searchlibrary:read

Cerca tracce e playlist riproducibili, inclusi i tuoi contenuti privati.

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

Restituisce i metadati riproducibili di una traccia.

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

GET/api/v1/playlistslibrary:read

Elenca le playlist a cui hai accesso.

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

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

Restituisce una playlist e le sue tracce.

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

Webhook

Registra endpoint HTTPS per essere avvisato quando i job asincroni terminano, senza dover interrogare. Il segreto di firma completo viene mostrato una sola volta, alla creazione dell’endpoint.

GET/api/v1/webhook-endpoints

Elenca i tuoi endpoint webhook attivi.

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

POST/api/v1/webhook-endpoints

Registra un endpoint webhook HTTPS pubblico. Il segreto di firma viene restituito una sola volta.

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}

Aggiorna l’URL o lo stato di un endpoint 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 webhook.

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

Log

Consulta i log delle richieste API degli ultimi 30 giorni.

GET/api/v1/logs

Elenca i log delle richieste API degli ultimi 30 giorni.

curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Limiti di frequenza

Gli endpoint di lettura consentono 600 richieste al minuto (50.000 al giorno). La generazione musicale consente 12 richieste al minuto (500 al giorno). L’autenticazione è limitata a 120 richieste al minuto per IP. Il superamento di un limite restituisce 429 rate_limited.

Errori

Gli errori restituiscono uno stato HTTP e un corpo JSON { error: { code, message, request_id } }. Includi request_id quando contatti il supporto.

Stato	Codice	Significato
401	authentication_required	Nessuna chiave API fornita nell’header Authorization.
401	invalid_api_key	La chiave API non è valida o è stata revocata.
401	revoked_api_key	La chiave API è stata revocata e non può più essere utilizzata.
403	api_terms_not_accepted	L’account API non è pronto perché i termini API non sono stati accettati.
403	insufficient_scope	Alla chiave API manca un ambito richiesto.
400	invalid_request	Il corpo o i parametri della richiesta non sono validi.
400	invalid_model	L’id del modello richiesto non esiste.
402	insufficient_credits	Crediti MeloLab insufficienti per creare questa generazione.
400	idempotency_key_required	Questa richiesta richiede un header Idempotency-Key.
409	idempotency_key_conflict	La Idempotency-Key è stata riutilizzata con una forma di richiesta diversa.
409	idempotency_conflict	La Idempotency-Key è stata riutilizzata con un corpo di richiesta diverso.
409	generation_concurrency_exceeded	Ci sono già troppi job di generazione in esecuzione per questo account.
404	job_not_found	Il job richiesto non esiste o non appartiene a questo account.
404	track_not_found	La traccia richiesta non esiste o non è accessibile a questo account.
404	playlist_not_found	La playlist richiesta non esiste o non è accessibile a questo account.
404	webhook_endpoint_not_found	L’endpoint webhook richiesto non esiste o non è tuo.
400	webhook_url_invalid	L’URL del webhook non è valido.
400	webhook_https_required	Gli endpoint webhook devono usare HTTPS.
400	webhook_credentials_forbidden	Gli URL webhook non possono includere credenziali incorporate.
400	webhook_host_blocked	Gli URL webhook non possono puntare a localhost, host privati o bloccati.
429	rate_limited	Troppe richieste; rallenta e riprova più tardi.
502	provider_unavailable	Il provider a monte è temporaneamente non disponibile.
502	provider_timeout	Il provider a monte è andato in timeout.
500	generation_failed	La generazione è fallita dopo essere stata accettata.
500	internal_error	Errore imprevisto della piattaforma API.

Documentazione dell’API

Per iniziare

Account

Modelli

Generazioni

Libreria

Webhook

Log

Limiti di frequenza

Errori

Inizia gratis

Crea

Transform

Analyze

Azienda