Suno API: clave y primera canción

Actualizado el 2026-11-10 · equipo de Suno-API

Cree una clave, envíe la primera generación, consulte el progreso y descargue MP3 o WAV. Los ejemplos se pueden copiar y ejecutar tal cual.

Empiece en 30 segundos: cree la clave en Tokens de la consola. Una generación cuesta 0,6 CNY, devuelve dos canciones y las consultas o descargas no tienen coste extra.

El modelo predeterminado actual es suno-v6. Los modelos de generación de suno-v2 a suno-v5-5 están retirados: pueden aparecer en tareas antiguas, pero no aceptan solicitudes nuevas.

Descarga, instala y configura suno-api agent kit desde esta dirección  https://www.suno-api.io/suno-agent-kit.zip

Recomendado: deja que la IA complete la integración

La IA lee 00_START_HERE.md y ayuda con el registro, el API Key, la comprobación del saldo, la presentación de funciones y la primera generación. Las acciones de pago requieren confirmación y los timeouts no se reintentan automáticamente.

Paso 1: obtener una clave de API

1. Abra https://www.suno-api.io.
2. Pulse Obtener clave de API y regístrese. Basta un correo electrónico, sin teléfono.
3. En la consola, abra la gestión de tokens y cree una clave.
4. Cópiela de inmediato: solo se muestra una vez. Recargue el saldo con un código de canje antes de la primera llamada de pago.

Paso 2: configurar la solicitud

Todas las llamadas comparten la misma URL base y las mismas cabeceras:

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

Paso 3: enviar la primera solicitud

Ejemplo 1 — generar desde una frase

Describa la canción y la API escribe la letra, la melodía y el arreglo:

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 canción folk animada sobre el primer día de primavera",
    "model": "suno-v6"
  }'

Respuesta:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Historia de primavera",
    "description": "una canción folk animada sobre el primer día de primavera",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Pasos de primavera",
    "description": "una canción folk animada sobre el primer día de primavera",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Cada ejecución devuelve dos tomas distintas para que elija. Una generación cuesta 0,6 ¥.

Ejemplo 2 — consultar el progreso

Pase los song_id devueltos al endpoint de consulta:

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

Mientras se procesa:

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

Al terminar:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Historia de 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
  }
]

El status pasa por pending, submitted, processing y llega a completed. Las direcciones pueden estar vacías mientras la tarea se ejecuta: guíese por el status, no por si audio_url tiene valor.

Paso 4: descargar el archivo

Cuando el status sea completed, basta con pedir el audio_url. Las descargas en MP3 y WAV son ilimitadas y no tienen coste adicional. Si necesita audio sin pérdidas para seguir editando, use el endpoint de WAV.

Casos de uso habituales

Música de fondo para vídeo

{
  "description": "música lo-fi tranquila para un vídeo de producto, sin voces, dinámica estable",
  "instrumental": true,
  "model": "suno-v6"
}

Con instrumental en true la salida no incluye voces.

Letra y estilo propios

{
  "lyrics": "[Verse 1]\nLas luces de la ciudad se apagan\n\n[Chorus]\nSeguimos caminando",
  "style": "acoustic pop, voz femenina cálida, 92 BPM",
  "model": "suno-v6"
}

Consultar hasta terminar

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 canción folk sobre la 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

Gestión de errores

Códigos principales

Formato del error

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

Tiempos de espera y timeouts (importante): los endpoints de generación son síncronos — el pedido solo se acepta y se entrega a generación cuando llega la respuesta. Según lo medido, la mayoría de las peticiones responden en 1-3 segundos, alrededor del 10% tarda más de 30 segundos y la más lenta ronda los 230 segundos. Configura el timeout del cliente en 300 segundos o más (el --max-time 300 del ejemplo); no recibir respuesta no significa que no se haya generado nada, y no reintentes justo después de un timeout (eso duplica el pedido y vuelve a cobrar). Si la conexión se cayó, confírmalo más tarde con GET /api/music/songs. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Buenas prácticas

• Mantenga la clave en el servidor, nunca en el navegador ni en apps distribuidas.
• Consulte cada 10–15 segundos en lugar de en un bucle ajustado.
• Guarde los song_id: son el único identificador para recuperar el audio más adelante.
• Reintente en 429 y 500; corrija la causa antes de repetir 400 y 401.
• Los fallos se reembolsan automáticamente: una tarea fallida no cuesta nada.
• Timeout del cliente: un endpoint de generación solo cuenta como aceptado cuando responde; configura el timeout en 300 segundos o más.
• Reintentos: reintenta solo ante fallos explícitos (4xx/5xx). Tras un timeout o corte de conexión, confirma primero con GET /api/music/songs si el pedido ya se aceptó, para no duplicarlo ni pagar dos veces.

Siguientes pasos

• Autenticación — claves, errores y límites
• Modelos compatibles — nombres de modelo, pistas y modelos retirados