API de consulta e historial de canciones

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

Esta página cubre tres endpoints de consulta gratuitos:

Si usaste el modo de recibo de aceptación (accept_mode=async) en un endpoint de generación, lo que tienes es un número de recibo, no un ID de canción. Sigue el progreso con GET /api/music/requests/{request_id} y vuelve a los endpoints de esta página cuando tengas el song_id real. Consulta «Modo de recibo de aceptación» en la API de generación en modo simple.

Autenticación y alcance de los datos

Los tres endpoints se autentican con la misma clave de API:

Authorization: Bearer YOUR_API_KEY

El historial de canciones está aislado por el user_id al que pertenece la clave de API. Varias claves de API creadas bajo la misma cuenta principal pueden leer el historial de esa cuenta, pero no el de otro usuario ni el de otra cuenta de subsitio.

Los endpoints de historial solo devuelven canciones realmente generadas. Quedan excluidos:

• los registros de reserva de generación que empiezan por pending:;
• las subidas de audio de origen y los registros de subida mejorada;
• los subresultados, como la separación de voz/acompañamiento y los stems;
• las canciones de otros usuarios o de cuentas de subsitio.

1. Consultar el estado de generación

Consulta el estado actual y el resultado final de uno o varios IDs de canción.

Endpoint: POST /api/music/query

Facturación: Gratis.

Headers

Parámetros del body

Ejemplo de petición

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

Ejemplo de respuesta

[
  {
    "song_id": "clip_id_1",
    "song_title": "Título de la canción",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Texto de la letra",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Notas de compatibilidad

La documentación antigua puede mostrar song_ids como un array. Hoy se recomienda una cadena separada por comas, que es como se llama realmente al endpoint.

song_ids debe contener IDs de canción reales. Un ID de reserva que empieza por pending: no es un song_id final y no puede usarse aquí; consultar solo IDs de reserva puede devolver un array vacío [].

El model, model_version o model_name de plataforma de una respuesta puede conservar valores históricos. Los trabajos nuevos deben usar suno-v6, suno-v6-wild o suno-v6-mini; de suno-v2 a suno-v5-5 están retirados, y ver esos nombres en el historial no significa que el modelo siga admitiendo envíos.

Mientras una tarea está en pending, submitted o processing, audio_url, video_url y cover_url pueden estar vacíos: es lo normal en una tarea sin terminar. No deduzcas un fallo solo porque la dirección esté vacía; guíate por status y vuelve a consultar cuando el estado esté completo. Solo si el estado está completo y las direcciones siguen vacías conviene contactar con soporte indicando el song_id.

⚠️ Las direcciones de audio viven 7 días — transfiere tus archivos a tiempo

El audio_url, el video_url (y otras direcciones de medios como el WAV) que devuelve este endpoint se sirven desde el almacenamiento de objetos de la plataforma y caducan a los 7 días por defecto: los archivos se reciclan y la dirección antigua devuelve 404.

• Mueve los archivos a tu propio almacenamiento dentro de esos 7 días; no trates la dirección como un enlace permanente.
• Una dirección caducada no obliga a regenerar la canción ni se cobra de nuevo: vuelve a llamar a este endpoint (POST /api/music/query) para obtener una dirección nueva válida de esa canción.

2. Consultar el historial de canciones de la cuenta

Lista las canciones generadas por la cuenta principal a la que pertenece la clave de API actual. Útil para crear tu propia lista de canciones, un selector o una página de historial.

Endpoint: GET /api/music/songs

Facturación: Gratis.

Parámetros de query

Los resultados se ordenan por created_at y por ID de registro interno de forma descendente, así el orden de paginación es estable.

Recuperar un envío que dio timeout: los endpoints de generación no dan respuesta intermedia antes de la aceptación. Si tu cliente se quedó sin tiempo o se cayó la conexión al enviar, puede que el pedido ya esté aceptado y generándose. Mira este endpoint (lo más nuevo primero): las canciones aceptadas aparecen con normalidad. Reenvía solo cuando hayas confirmado que no está, para no pagar dos veces. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Ejemplo de petición

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

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "La ciudad de noche",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Campos de la respuesta

El endpoint de listado no devuelve prompts, campos de facturación, información de cuenta ni respuestas sin procesar. Para prompts y parámetros de generación, llama al endpoint de detalle de la canción.

3. Consultar los parámetros de generación

Consulta el prompt, el estilo, el modelo y la canción de origen que la plataforma guardó al generar esa canción.

Endpoint: GET /api/music/songs/:song_id

Facturación: Gratis.

Solo pueden leerse canciones de la cuenta principal a la que pertenece la clave de API actual. Las canciones de otros usuarios o de cuentas de subsitio se tratan siempre como «canción no encontrada».

Parámetro de ruta

Ejemplo de petición

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "La ciudad de noche",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "calles de ciudad tras la lluvia, letra sobre un reencuentro",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "La ciudad de noche",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Los campos de parameters

El campo prompt_view (ver prompt, añadido el 2026-09-28)

prompt_view es una estructura normalizada dedicada a «ver el prompt»: organiza los datos en secciones fijas por tipo de generación, de modo que el cliente ya no tiene que decidir qué campo mostrar. Es un campo puramente aditivo: los campos antiguos (parameters, parameter_retention) conservan nombre y significado, y los clientes que no analicen el campo nuevo no se ven afectados en absoluto.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Modo personalizado",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Las cuatro de la mañana#701f37", "title_base": "Las cuatro de la mañana", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "electrónica guochao, sub bass profundo, sintetizador retro",
    "style_tags": "electrónica guochao, sub bass profundo, sintetizador retro",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Campos que pueden aparecer en extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, más el grupo de efectos de sonido sound_type / sound_bpm / sound_key / sound_loop. Los valores vacíos nunca se devuelven.

Tres reglas de presentación (síguelas en lugar de deducir):

1. Distingue de dónde viene el estilo: con style_source=suno_derived, muéstralo como «estilo (deducido por Suno a partir de tu descripción)» y nunca como «tu estilo»;
2. Los prompts internos nunca aparecen: los tipos de cover con voz devuelven solo los 【requisitos de estilo】/【requisitos de cover】 que escribió el usuario; el andamiaje fijo que montamos para el modelo no aparece en ningún campo (los datos históricos están saneados igual);
3. No adivines parámetros ausentes: si extended no lo contiene, no se registró entonces — usa retention para explicar por qué.

Notas sobre la retención de parámetros

parameter_retention existe para separar «se pasó un valor vacío explícitamente» de «el campo nunca se guardó históricamente»:

• core_parameters_available: si existe el registro principal de la tarea; normalmente true en un detalle válido;
• extended_parameters_available: si se encontró un registro de tarea de música extendida relacionado;
• sources: de qué tablas de datos procede esta respuesta;
• unavailable_fields: campos que no pueden recuperarse de forma fiable del historial; devuelven null dentro de parameters.

Las canciones históricas normales suelen conservar el prompt, el estilo, el título actual, el modelo, el tipo de generación y la canción de origen, pero no guardaron por separado todos los parámetros avanzados. La plataforma nunca adivina valores ausentes a partir de generation_type.

Algunas tareas de música extendida también guardaron el prompt original, el estilo, el título, el modelo y además custom_mode, negative_tags, vocal_gender, style_weight y weirdness_constraint. Aunque exista un registro extendido, instrumental, lyrics_mode y wait_audio pueden seguir sin poder recuperarse.

El usuario puede renombrar los títulos después. Cuando una tarea histórica normal no guardó un título original aparte, parameters.title puede ser el título actual; cuando existe un registro de tarea extendida, se prefiere el título de generación original guardado allí.

No encontrada o sin permiso

Los errores de negocio usan un sobre de respuesta uniforme. Cuando la canción no existe o no pertenece a la cuenta actual:

{
  "success": false,
  "message": "song not found"
}

Este error de negocio se devuelve hoy con HTTP 200, así que juzga el resultado por el campo success. Una clave de API ausente, inválida, caducada o deshabilitada devuelve HTTP 401.

Notas de seguridad

Los endpoints de historial y detalle nunca devuelven:

• claves de API ni IDs de token;
• campos de cuota, facturación o reembolso;
• información de la cuenta ni respuestas sin procesar;
• claves internas del almacenamiento de objetos;
• errores de administrador ni errores de recursos internos.