API del certificato di licenza commerciale musicale

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

Descrizione dell'endpoint

Gli endpoint del certificato di licenza commerciale musicale permettono di elencare i brani che l'utente della chiave API corrente può licenziare, generare un certificato PDF, consultare la cronologia dei certificati e scaricare i file emessi.

Tutti gli endpoint usano uniformemente la New API Key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Indirizzo di base:

https://www.suno-api.io

Prerequisiti

• La chiave API deve essere valida e appartenere all'utente che necessita del certificato.
• L'utente deve prima completare il collegamento dell'identità di licenza (vedi «0. Idoneità e identità di licenza»); una volta confermata, l'identità viene bloccata secondo le regole del prodotto.
• L'utente deve soddisfare il requisito di ricarica cumulata per persona fisica o azienda.
• Gli endpoint ordinari restituiscono solo informazioni di identità mascherate; non restituiscono mai in chiaro numeri di documento, telefoni o codici di credito sociale unificato.
• Ogni brano può emettere un solo certificato riuscito; un certificato la cui generazione fallisce non consuma l'idoneità del brano.
• Attualmente sono supportati i tipi di generazione designati che sono completati, hanno audio e hanno un Suno Song ID reale. Se un brano è selezionabile lo determina authorization.selectable nell'elenco dei brani.

0. Idoneità e identità di licenza

Prima di emettere un certificato bisogna verificare l'idoneità e collegare l'identità. Entrambi gli endpoint sono gratuiti.

0.1 Verificare idoneità e identità

Endpoint: GET /api/music/authorization/context

{
  "code": 200,
  "message": "success",
  "data": {
    "identity": {
      "exists": false
    },
    "eligibility": {
      "current_amount": 216.3,
      "personal_required_amount": 200,
      "company_required_amount": 500,
      "personal_eligible": true,
      "company_eligible": false
    },
    "stats": {
      "authorized_song_count": 0,
      "certificate_count": 0
    }
  }
}

0.2 Collegare l'identità di licenza

Endpoint: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "Mario Rossi",
  "id_number": "110101199001010000",
  "contact_name": "Mario Rossi",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "Via Roma 12, Milano",
  "confirm_locked": true
}

La risposta restituisce le informazioni di identità mascherate: {"identity": {...}}. Dopo un collegamento riuscito, verifica con l'endpoint context che identity.exists sia diventato true, poi chiama gli endpoint di elenco brani ed emissione. Se le informazioni di identità devono essere modificate, contatta l'assistenza.

1. Elencare i brani licenziabili

Endpoint: GET /api/music/authorization/songs

Parametri di query

Esempio di richiesta

curl "https://www.suno-api.io/api/music/authorization/songs?p=1&page_size=20&status=selectable" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "Brano di esempio",
        "generation_type": "generate",
        "completed_at": 1784000000,
        "created_at": 1783999000,
        "audio_url": "https://example.com/audio.mp3",
        "model_name": "suno-v6",
        "authorization": {
          "selectable": true
        }
      }
    ]
  }
}

Quando authorization.selectable=false, la risposta spiega il motivo tramite reason_code e reason. I brani che hanno già un certificato restituiscono anche certificate_id e certificate_no.

2. Generare un certificato

Endpoint: POST /api/music/authorization/certificates

Parametri del body

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/authorization/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["suno-song-id-1", "suno-song-id-2"],
    "confirm_risk_terms": true
  }'

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "certificate": {
      "id": 101,
      "certificate_no": "CERTIFICATE-NO",
      "verification_code": "VERIFY-CODE",
      "status": "issued",
      "song_count": 2,
      "identity_type_snapshot": "personal",
      "licensee_name_masked": "M*",
      "document_no_masked_snapshot": "11**************34",
      "phone_masked_snapshot": "138****0000",
      "pdf_sha256": "PDF_SHA256",
      "issued_at": 1784000100,
      "created_at": 1784000000,
      "updated_at": 1784000100,
      "download_url": "/api/music/authorization/certificates/101/download",
      "songs": []
    }
  }
}

In una risposta riuscita status è issued. Se il rendering del PDF fallisce, il certificato viene contrassegnato come failed e i brani correlati possono essere reinviati una volta risolto il problema.

3. Consultare la cronologia dei certificati

Endpoint: GET /api/music/authorization/certificates

Parametri di query

Esempio di richiesta

curl "https://www.suno-api.io/api/music/authorization/certificates?p=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Struttura della risposta

Il data della risposta è un oggetto paginato con page, page_size, total e items. Ogni voce di items è un riepilogo del certificato e include l'istantanea dei brani di quel certificato.

4. Consultare i dettagli del certificato

Endpoint: GET /api/music/authorization/certificates/:id

Il parametro di percorso id è l'ID numerico del certificato. L'endpoint consente l'accesso solo ai certificati dell'utente della chiave API corrente.

Esempio di richiesta

curl https://www.suno-api.io/api/music/authorization/certificates/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

Struttura della risposta

In caso di successo restituisce data.certificate, i cui campi includono numero del certificato, stato, informazioni mascherate del licenziatario, ora di emissione, checksum del PDF, indirizzo di download e istantanea dei brani licenziati.

5. Scaricare il PDF del certificato

Endpoint: GET /api/music/authorization/certificates/:id/download

Si possono scaricare solo i certificati con stato issued. La richiesta di download richiede comunque una chiave API valida e puoi scaricare solo i tuoi certificati.

Esempio di richiesta

curl https://www.suno-api.io/api/music/authorization/certificates/101/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output authorization-certificate.pdf

Una risposta riuscita è uno stream di file application/pdf; il nome del file segue il Content-Disposition del backend.

Cause di errore frequenti

Note

• Usa il suno_song_id restituito dall'elenco dei brani; non usare ID segnaposto pending:* né ID della tabella dei task.
• L'indirizzo di download non è un link pubblico; non rimuovere l'autenticazione tramite chiave API.
• I record dei certificati appartengono all'utente corrispondente alla chiave API e non possono essere consultati o scaricati tra utenti diversi.
• L'ambito della licenza, i termini di restrizione e il contenuto finale del PDF sono regolati dal certificato effettivamente emesso.