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

Formato dell'intestazione

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 esiste ma non è autorizzata per questa richiesta — quasi sempre perché è stata disattivata o l'account è sospeso. Controlla lo stato dell'account nella console e contatta il supporto se il motivo non è evidente.

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

Linux / macOS

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

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

.env

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

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

Ruota la chiave quando serve

Ruota le chiavi ogni 3-6 mesi e subito se sospetti una fuga. Elimina le chiavi che non usi più: una chiave inutilizzata è solo un rischio inutilizzato.

Limite di richieste

Le richieste sono limitate per chiave:

429 Too Many Requests

Superato un limite l'API risponde 429 e la risposta può contenere un valore retry_after in secondi. Attendi quel tempo prima del tentativo successivo; rallenta il ritmo, metti il lavoro in coda o ripeti con backoff esponenziale invece che in un ciclo serrato.

Politica di ritentativo

Ritenta solo su errori espliciti. Non ritentare dopo un timeout di lettura o di connessione: gli endpoint di generazione sono sincroni, quindi un timeout può significare che l'ordine è già stato accettato ed è in generazione — ritentare crea un ordine duplicato e addebita due volte. Imposta il timeout del client a 300 secondi o più e, dopo una connessione caduta, verifica l'ordine con GET /api/music/songs prima di reinviarlo. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

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 lettere e cifre, circa 50-60 caratteri in tutto.

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?

Non c'è un limite fisso. Usa una chiave per applicazione o ambiente per poterle revocare separatamente ed elimina quelle che non usi più.

Le chiavi scadono?

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

Come monitoro l'utilizzo?

Accedi alla console: lì è elencato l'uso per chiave, con numero di richieste, spesa e attività recenti.

Pagine correlate

• Guida rapida
• Modelli supportati