Autenticazione

Aggiornato il 2026-09-18 · team Suno-API

Tutte le richieste a Suno-API sono autenticate con una chiave API. Questa pagina spiega come creare la chiave, come inviarla, cosa significano gli errori e come mantenerla al sicuro.

Che cos'è una chiave API

La chiave è un token bearer legato al tuo account. Porta con sé il saldo, quindi chi ottiene la chiave può spenderlo. La chiave viene mostrata una sola volta al momento della creazione: copiala e conservala in un luogo sicuro.

Creare una chiave

1. Registrati su https://www.suno-api.io — basta un'email, nessun numero di telefono.
2. Apri la gestione dei token nella console.
3. Crea una nuova chiave e copiala.

Le chiavi hanno il formato sk-…. Una chiave persa non può essere recuperata: creane un'altra ed elimina quella vecchia.

Usare la chiave

Invia la chiave nell'intestazione Authorization in ogni richiesta:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Esempio

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "un brano di pianoforte calmo per un caffè"}'

Errori di autenticazione

401 Unauthorized

L'intestazione è assente, malformata oppure la chiave non esiste.

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Verifica che l'intestazione sia esattamente Bearer <chiave> (con uno spazio dopo Bearer) e che non sia finito un carattere di nuova riga in fondo alla chiave.

403 Forbidden

La chiave è valida ma non può eseguire la richiesta — quasi sempre per saldo insufficiente. Ricarica il conto e ripeti la stessa richiesta.

Buone pratiche di sicurezza

Non inserire mai la chiave nel codice lato client

Non incorporare la chiave in pagine web, app mobili o binari desktop. Chi riesce ad aprire l'ispettore del browser può leggerla e spendere il tuo saldo. Chiama l'API dal tuo server ed esponi ai tuoi utenti il tuo endpoint.

Usa variabili d'ambiente

# ~/.bashrc o ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

# file .env — inseriscilo nel .gitignore
SUNO_API_KEY=sk-your-key-here

Ruota la chiave quando serve

Se sospetti una fuga di dati, creane una sostitutiva ed elimina quella vecchia. Ruotare costa poco; una chiave esposta costa molto.

Limite di richieste

Le richieste sono limitate per chiave. Superato il limite l'API risponde 429 Too Many Requests.

Rinvia con backoff esponenziale invece di fare un ciclo serrato:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

Domande frequenti

Qual è il formato della chiave?

Inizia con sk- seguito da una sequenza casuale. Tratta l'intero valore come un unico token.

Posso chiamare l'API direttamente dal browser?

In teoria sì, ma non farlo in produzione: la chiave sarebbe visibile a tutti i visitatori. Passa dal tuo backend come proxy.

Come capisco se la chiave è ancora valida?

Invia una qualsiasi richiesta autenticata. 200 significa che funziona; 401 indica una chiave non valida o eliminata.

Ho perso la chiave. E adesso?

Le chiavi non sono recuperabili. Creane una nuova nella console ed elimina quella vecchia.

Quante chiavi può avere un account?

Più di una. Usane una per applicazione o ambiente, così puoi revocarle in modo indipendente.

Le chiavi scadono?

Restano valide finché non le elimini o chiudi l'account. Ruotarle periodicamente è buona pratica.

Come monitoro l'utilizzo?

Saldo e cronologia sono nella console. Ogni generazione costa 0,6 ¥ e restituisce due brani; i fallimenti vengono rimborsati automaticamente.

Pagine correlate

• Guida rapida
• Modelli supportati