API de certificado de licencia comercial de música

Actualizado el 2026-09-18 · equipo de Suno-API

Descripción del endpoint

Los endpoints de certificado de licencia comercial de música permiten listar las canciones que el usuario de la clave de API actual puede licenciar, generar un certificado PDF, consultar el historial de certificados y descargar los archivos emitidos.

Todos los endpoints usan la New API Key de forma uniforme:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Dirección base:

https://www.suno-api.io

Requisitos previos

• La clave de API debe ser válida y pertenecer al usuario que necesita el certificado.
• El usuario debe completar antes el enlace de identidad de licencia (véase «0. Elegibilidad e identidad de licencia»); una vez confirmada, la identidad queda bloqueada según las reglas del producto.
• El usuario debe cumplir el requisito de recarga acumulada para persona física o empresa.
• Los endpoints ordinarios devuelven solo información de identidad enmascarada; nunca devuelven números de documento, teléfonos ni códigos de crédito social unificado en texto claro.
• Cada canción puede emitir un solo certificado correcto; un certificado que falla al generarse no consume la elegibilidad de la canción.
• Actualmente se admiten tipos de generación designados que estén completados, tengan audio y tengan un Suno Song ID real. Si una canción se puede seleccionar lo determina authorization.selectable en la lista de canciones.

0. Elegibilidad e identidad de licencia

Antes de emitir un certificado hay que consultar la elegibilidad y enlazar la identidad. Ambos endpoints son gratuitos.

0.1 Consultar elegibilidad e identidad

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 Enlazar la identidad de licencia

Endpoint: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "Juan Pérez",
  "id_number": "110101199001010000",
  "contact_name": "Juan Pérez",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "Calle Mayor 123, Madrid",
  "confirm_locked": true
}

La respuesta devuelve la información de identidad enmascarada: {"identity": {...}}. Tras un enlace correcto, confirma con el endpoint context que identity.exists ya es true y después llama a los endpoints de lista de canciones y de emisión. Si hay que cambiar la información de identidad, contacta con atención al cliente.

1. Listar canciones licenciables

Endpoint: GET /api/music/authorization/songs

Parámetros de query

Ejemplo de petición

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

Ejemplo de respuesta

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

Cuando authorization.selectable=false, la respuesta explica el motivo mediante reason_code y reason. Las canciones que ya tienen certificado también devuelven certificate_id y certificate_no.

2. Generar un certificado

Endpoint: POST /api/music/authorization/certificates

Parámetros del body

Ejemplo de petición

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

Ejemplo de respuesta

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

En una respuesta correcta status es issued. Si el renderizado del PDF falla, el certificado se marca como failed y las canciones relacionadas aún pueden volver a enviarse una vez resuelto el problema.

3. Consultar el historial de certificados

Endpoint: GET /api/music/authorization/certificates

Parámetros de query

Ejemplo de petición

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

Estructura de la respuesta

El data de la respuesta es un objeto paginado con page, page_size, total e items. Cada entrada de items es un resumen de certificado e incluye la instantánea de canciones de ese certificado.

4. Consultar el detalle de un certificado

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

El parámetro de ruta id es el ID numérico del certificado. El endpoint solo permite acceder a los certificados del usuario de la clave de API actual.

Ejemplo de petición

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

Estructura de la respuesta

En caso correcto devuelve data.certificate, cuyos campos incluyen el número de certificado, el estado, la información enmascarada del licenciatario, la hora de emisión, la suma de verificación del PDF, la dirección de descarga y la instantánea de canciones licenciadas.

5. Descargar el PDF del certificado

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

Solo se pueden descargar los certificados cuyo estado sea issued. La descarga sigue necesitando una clave de API válida y solo puedes descargar tus propios certificados.

Ejemplo de petición

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

Una respuesta correcta es un flujo de archivo application/pdf; el nombre del archivo sigue el Content-Disposition del backend.

Causas de fallo frecuentes

Notas

• Usa el suno_song_id que devuelve la lista de canciones; no uses ID de relleno pending:* ni ID de la tabla de tareas.
• La dirección de descarga no es un enlace público; no elimines la autenticación por clave de API.
• Los registros de certificado pertenecen al usuario al que corresponde la clave de API y no pueden consultarse ni descargarse entre usuarios.
• El alcance de la licencia, los términos de restricción y el contenido final del PDF se rigen por el certificado realmente emitido.