API de subida reforzada

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

Descripción del endpoint

La subida reforzada envía un archivo de audio local; el sistema realiza el realce en segundo plano y produce una canción completa y reproducible. La llamada de envío devuelve la información de la tarea de inmediato y el cliente consulta el progreso con el endpoint de consulta.

Endpoint de envío: POST /api/music/enhanced-upload

Consulta de una tarea: GET /api/music/enhanced-upload/:id

Cancelar una tarea: POST /api/music/enhanced-upload/:id/cancel

Consulta de la lista: GET /api/music/enhanced-upload

Facturación: 10 ¥ por llamada, con cobro previo al precio fijo de suno-enhanced-upload. Si la tarea falla, o se cancela dentro de la etapa permitida, el importe cobrado por adelantado se devuelve automáticamente. El importe realmente cobrado sigue la configuración de precios actual del back-office.

Flujo de llamada

1. Llama a POST /api/music/enhanced-upload para subir el archivo de audio.
2. Guarda el task_id devuelto.
3. Llama a GET /api/music/enhanced-upload/:id para consultar progreso y resultado.
4. Cuando Suno termina el renderizado final, el servicio usa la cuenta de Suno vinculada a esa tarea para llamar al endpoint de descarga autorizada de Studio y escribe el MP3 en el servicio de medios CN2.
5. La tarea pasa a completed solo cuando el recurso CN2 está listo; en ese momento se lee la dirección de audio de la CDN desde audio_url en la respuesta.

/api/forbidden es una dirección de relleno que puede aparecer en los metadatos de Suno Studio; no es un recurso reproducible ni descargable. Nunca se devuelve al cliente ni se usa como prueba de finalización. Si el renderizado ya terminó pero CN2 sigue preparándose, el endpoint sigue devolviendo processing y no devuelve audio_url; el cliente debe seguir consultando y no tratar la dirección vacía como un fallo.

Enviar una subida reforzada

Headers

Parámetros de formulario

Ejemplo de petición

El ejemplo siguiente usa la misma forma de llamada que en la validación en producción, pero la clave de API se ha sustituido por un relleno.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Respuesta

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Consultar una tarea

Ejemplo de petición

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Ejemplo de respuesta en proceso

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Ejemplo de respuesta completada

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Cancelar una tarea

Solo se puede cancelar mientras la tarea y el flujo del backend siguen en la etapa queued. Una vez que la tarea entra en leasing, running, processing o ya ha finalizado, no se puede cancelar.

Ejemplo de petición

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Respuesta

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Si la tarea ya ha empezado a procesarse, el endpoint devuelve:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Consultar la lista de tareas

El endpoint de lista devuelve solo las tareas de subida reforzada del usuario al que pertenece la clave de API actual; no mezcla tareas de generación normal, cover ni extend.

Parámetros de query

Ejemplo de petición

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Respuesta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Referencia de campos de la respuesta

Notas

• Actualmente el endpoint solo admite subida de archivos multipart; no admite file_url ni file_base64 en JSON.
• El archivo subido puede pesar como máximo 80 MB.
• El endpoint de envío es asíncrono: una respuesta queued significa que la tarea se ha encolado, no que el audio esté terminado.
• La cancelación solo se aplica a tareas que aún no han empezado a procesarse; una vez empieza el procesamiento no se interrumpe el flujo de la cuenta de la plataforma.
• No expongas claves de API reales en el código del cliente.

Iniciar un cover cuando la subida reforzada termine

Cuando la subida reforzada haya terminado, puedes usar el resultado como clip de origen y llamar a POST /api/music/generate-from-source para iniciar un cover.

Nota: el cover es un endpoint síncrono — el pedido solo se acepta cuando llega la respuesta, y en casos medidos puede tardar hasta unos 230 segundos. Configura el timeout del cliente en 300 segundos o más y no reintentes justo después de un timeout. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Primero consulta GET /api/music/enhanced-upload/:id hasta que task.status sea completed. En ese punto:

• task.song_id es el ID real de la canción y es el sourceClipId que necesita el endpoint de cover;
• conviene pasar task.audio_url como sourceAudioUrl, para que el servidor pueda resolver el caso en que el clip de origen y la cuenta de ejecución no coincidan;
• task.task_id es solo el ID de la tarea de subida reforzada y no puede usarse como sourceClipId;
• pending:enhanced-upload:* es un ID de relleno de la etapa de procesamiento y no puede usarse para un cover.

Al iniciar el cover, usa la misma clave de API que en la subida reforzada y monta la petición según esta correspondencia de campos:

Rellena el resto de parámetros (letra, estilo, título, modelo) según la API de cover desde un clip de origen. Cuando el endpoint de cover devuelva el nuevo clips[].song_id, usa POST /api/music/query para consultar el estado de generación y el audio final.