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.
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"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"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.
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"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.
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"}'Elenca i tuoi job di generazione recenti.
curl -X GET https://melolab.ai/api/v1/generations \
-H "Authorization: Bearer $MELOLAB_API_KEY"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"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.
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"Restituisce i metadati riproducibili di una traccia.
curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
-H "Authorization: Bearer $MELOLAB_API_KEY"Elenca le playlist a cui hai accesso.
curl -X GET https://melolab.ai/api/v1/playlists \
-H "Authorization: Bearer $MELOLAB_API_KEY"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.
Elenca i tuoi endpoint webhook attivi.
curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
-H "Authorization: Bearer $MELOLAB_API_KEY"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"}'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"}'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.
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. |
| 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. |
| 409 | idempotency_conflict | La Idempotency-Key è stata riutilizzata con un corpo di richiesta diverso. |
| 404 | not_found | La risorsa richiesta non è stata trovata o non è tua. |
| 429 | rate_limited | Troppe richieste; rallenta e riprova più tardi. |
| 502 | provider_unavailable | Il provider a monte è temporaneamente non disponibile. |
