Guida rapida

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

Questa guida porta dalla creazione della chiave API alla prima canzone generata, al controllo del progresso e al download dell'audio in circa cinque minuti. Gli esempi si possono copiare ed eseguire così come sono.

Il modello predefinito attuale è suno-v6. I modelli di generazione da suno-v2 a suno-v5-5 sono stati disattivati: possono comparire in vecchie attività, ma non accettano più nuove richieste.

Scarica, installa e configura suno-api agent kit da questo indirizzo  https://www.suno-api.io/suno-agent-kit.zip

Consigliato: lascia che l’AI completi l’integrazione

L’AI legge 00_START_HERE.md e assiste con registrazione, salvataggio dell’API Key, controllo del saldo, presentazione delle funzioni e prima generazione. Le azioni a pagamento richiedono conferma e i timeout non vengono ritentati automaticamente.

Passo 1: ottenere una chiave API

1. Apri https://www.suno-api.io.
2. Clicca su Ottieni chiave API e registrati. Serve solo un'email, nessun numero di telefono.
3. Nella console apri la gestione dei token e crea una chiave.
4. Copiala subito: viene mostrata una sola volta. Prima della prima chiamata a pagamento ricarica il saldo con un codice di riscatto.

Passo 2: impostare la richiesta

Tutte le chiamate usano lo stesso URL di base e le stesse intestazioni:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Passo 3: inviare la prima richiesta

Esempio 1 — generare da una descrizione

Descrivi la musica e l'API scrive testo, melodia e arrangiamento:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "una vivace canzone folk sul primo giorno di primavera",
    "model": "suno-v6"
  }'

Risposta:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Storia di primavera",
    "description": "una vivace canzone folk sul primo giorno di primavera",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Passi di primavera",
    "description": "una vivace canzone folk sul primo giorno di primavera",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Ogni esecuzione restituisce due versioni diverse tra cui scegliere. Una generazione costa 0,6 ¥.

Esempio 2 — controllare il progresso

Invia gli song_id ricevuti all'endpoint di interrogazione:

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Mentre l'attività è in corso:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Storia di primavera",
    "progress": "60%"
  }
]

Al termine:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Storia di primavera",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

Lo status passa da pending a submitted, poi processing e infine completed. Gli indirizzi possono restare vuoti durante l'esecuzione: valuta in base allo status, non in base alla presenza di audio_url.

Passo 4: scaricare il file

Quando lo status è completed, richiedi semplicemente l'audio_url. I download in MP3 e WAV sono illimitati e non costano nulla in più. Se ti serve audio senza perdite per il montaggio, usa l'endpoint WAV.

Scenari comuni

Base musicale per video

{
  "description": "base lo-fi calma per video di prodotto, senza voce, dinamica stabile",
  "instrumental": true,
  "model": "suno-v6"
}

Con instrumental impostato su true l'uscita non contiene voce.

Testo e stile propri

{
  "lyrics": "[Verse 1]\nLe luci della città si spengono piano\n\n[Chorus]\nContinuiamo a camminare",
  "style": "acoustic pop, voce femminile calda, 92 BPM",
  "model": "suno-v6"
}

Interrogare fino al completamento

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "una canzone folk vivace sulla primavera", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Gestione degli errori

Codici principali

Formato dell'errore

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

Tempi di attesa e timeout (importante): gli endpoint di generazione sono sincroni — l'ordine viene accettato e passato alla generazione solo quando arriva la risposta. Dai dati misurati, la maggior parte delle richieste risponde in 1-3 secondi, circa il 10% supera i 30 secondi e la più lunga arriva a circa 230 secondi. Imposta il timeout del client a 300 secondi o più (il --max-time 300 dell'esempio); nessuna risposta non significa che non sia stato generato nulla, e non ritentare subito dopo un timeout (duplica l'ordine e riaddebita). Se la connessione è caduta, verifica più tardi con GET /api/music/songs. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

Buone pratiche

• Tieni la chiave sul server, mai nel browser o in applicazioni distribuite.
• Interroga ogni 10–15 secondi invece di fare polling serrato.
• Conserva gli song_id: sono l'unico identificatore per recuperare l'audio in seguito.
• Rinvia su 429 e 500; correggi la causa prima di rinviare su 400 e 401.
• I fallimenti vengono rimborsati automaticamente, quindi un'attività non riuscita non costa nulla.
• Timeout del client: un endpoint di generazione è accettato solo quando risponde; imposta il timeout a 300 secondi o più.
• Ritentativi: ritenta solo su errori espliciti (4xx/5xx). Dopo un timeout o una caduta di connessione, verifica prima con GET /api/music/songs se l'ordine è già stato accettato, per evitare duplicati e doppio addebito.

Passi successivi

• Autenticazione — chiavi, errori e limiti
• Modelli supportati — nomi dei modelli, stem e modelli disattivati