API de certificado de licença comercial de música

Atualizado em 2026-09-18 · equipe Suno-API

Descrição do endpoint

Os endpoints de certificado de licença comercial de música permitem listar as músicas que o usuário da chave de API atual pode licenciar, gerar um certificado em PDF, consultar o histórico de certificados e baixar os arquivos emitidos.

Todos os endpoints usam a New API Key de forma uniforme:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Endereço base:

https://www.suno-api.io

Pré-requisitos

• A chave de API precisa ser válida e pertencer ao usuário que precisa do certificado.
• O usuário precisa concluir antes a vinculação da identidade de licenciamento (veja "0. Elegibilidade e identidade de licenciamento"); uma vez confirmada, a identidade é bloqueada conforme as regras do produto.
• O usuário precisa atender ao requisito de recarga acumulada para pessoa física ou empresa.
• Os endpoints comuns devolvem apenas informações de identidade mascaradas; nunca devolvem número de documento, telefone ou código de crédito social unificado em texto claro.
• Cada música pode emitir apenas um certificado bem-sucedido; um certificado que falha ao ser gerado não consome a elegibilidade da música.
• Atualmente são suportados tipos de geração designados que estejam concluídos, tenham áudio e tenham um Suno Song ID real. Se a música pode ser selecionada é determinado por authorization.selectable na lista de músicas.

0. Elegibilidade e identidade de licenciamento

Antes de emitir um certificado é preciso consultar a elegibilidade e vincular a identidade. Os dois endpoints são gratuitos.

0.1 Consultar elegibilidade e identidade

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 Vincular a identidade de licenciamento

Endpoint: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "João Silva",
  "id_number": "110101199001010000",
  "contact_name": "João Silva",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "Rua Augusta 123, São Paulo",
  "confirm_locked": true
}

A resposta devolve a informação de identidade mascarada: {"identity": {...}}. Após uma vinculação bem-sucedida, confirme com o endpoint context que identity.exists passou a true e só então chame os endpoints de lista de músicas e de emissão. Se precisar alterar a informação de identidade, fale com o atendimento.

1. Listar músicas licenciáveis

Endpoint: GET /api/music/authorization/songs

Parâmetros de query

Exemplo de requisição

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

Exemplo de resposta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "Música de exemplo",
        "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, a resposta explica o motivo por meio de reason_code e reason. Músicas que já têm certificado também devolvem certificate_id e certificate_no.

2. Gerar um certificado

Endpoint: POST /api/music/authorization/certificates

Parâmetros do body

Exemplo de requisição

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
  }'

Exemplo de resposta

{
  "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": "J*",
      "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": []
    }
  }
}

Em uma resposta bem-sucedida status é issued. Se a renderização do PDF falhar, o certificado é marcado como failed e as músicas relacionadas ainda podem ser reenviadas depois que o problema for corrigido.

3. Consultar o histórico de certificados

Endpoint: GET /api/music/authorization/certificates

Parâmetros de query

Exemplo de requisição

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

Estrutura da resposta

O data da resposta é um objeto paginado com page, page_size, total e items. Cada item de items é um resumo de certificado e inclui o snapshot de músicas daquele certificado.

4. Consultar detalhes do certificado

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

O parâmetro de caminho id é o ID numérico do certificado. O endpoint permite acesso apenas aos certificados do usuário da chave de API atual.

Exemplo de requisição

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

Estrutura da resposta

Em caso de sucesso devolve data.certificate, cujos campos incluem número do certificado, status, informação mascarada do licenciado, hora de emissão, checksum do PDF, endereço de download e o snapshot das músicas licenciadas.

5. Baixar o PDF do certificado

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

Só certificados com status issued podem ser baixados. A requisição de download ainda exige uma chave de API válida, e você só pode baixar os seus próprios certificados.

Exemplo de requisição

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

Uma resposta bem-sucedida é um fluxo de arquivo application/pdf; o nome do arquivo segue o Content-Disposition do backend.

Causas comuns de falha

Observações

• Use o suno_song_id devolvido pela lista de músicas; não use ID de preenchimento pending:* nem ID da tabela de tarefas.
• O endereço de download não é um link público; não remova a autenticação por chave de API.
• Os registros de certificado pertencem ao usuário correspondente à chave de API e não podem ser consultados ou baixados entre usuários.
• O escopo da licença, os termos de restrição e o conteúdo final do PDF seguem o certificado realmente emitido.