API de upload reforçado

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

Descrição do endpoint

O upload reforçado envia um arquivo de áudio local; o sistema faz o realce em segundo plano e produz uma música completa e reproduzível. A chamada de envio devolve as informações da tarefa imediatamente e o cliente consulta o progresso pelo endpoint de consulta.

Endpoint de envio: POST /api/music/enhanced-upload

Consulta de uma tarefa: GET /api/music/enhanced-upload/:id

Cancelar uma tarefa: POST /api/music/enhanced-upload/:id/cancel

Consulta da lista: GET /api/music/enhanced-upload

Cobrança: ¥10 por chamada, com cobrança prévia pelo preço fixo de suno-enhanced-upload. Se a tarefa falhar, ou for cancelada dentro da etapa permitida, o valor cobrado antecipadamente é devolvido automaticamente. O valor realmente cobrado segue a configuração de preços atual do back-office.

Fluxo de chamada

1. Chame POST /api/music/enhanced-upload para enviar o arquivo de áudio.
2. Guarde o task_id devolvido.
3. Chame GET /api/music/enhanced-upload/:id para consultar progresso e resultado.
4. Quando o Suno termina a renderização final, o serviço usa a conta Suno vinculada a essa tarefa para chamar o endpoint de download autorizado do Studio e grava o MP3 no serviço de mídia CN2.
5. A tarefa só passa a completed quando o ativo CN2 está pronto; nesse momento leia o endereço de áudio da CDN em audio_url da resposta.

/api/forbidden é um endereço de preenchimento que pode aparecer nos metadados do Suno Studio; não é um recurso reproduzível nem baixável. Nunca é devolvido ao cliente e não é usado como prova de conclusão. Se a renderização já terminou mas o CN2 ainda está se preparando, o endpoint continua devolvendo processing e não devolve audio_url; o cliente deve continuar consultando e não tratar o endereço vazio como falha.

Enviar um upload reforçado

Headers

Parâmetros de formulário

Exemplo de requisição

O exemplo abaixo usa a mesma forma de chamada da validação em produção, mas a chave de API foi substituída por um preenchimento.

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"

Resposta

{
  "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 uma tarefa

Exemplo de requisição

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

Exemplo de resposta em processamento

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

Exemplo de resposta concluída

{
  "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 uma tarefa

Só é possível cancelar enquanto a tarefa e o fluxo do backend ainda estão na etapa queued. Depois que a tarefa entra em leasing, running, processing ou já foi concluída, não é possível cancelar.

Exemplo de requisição

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"

Resposta

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

Se a tarefa já começou a ser processada, o endpoint devolve:

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

Consultar a lista de tarefas

O endpoint de lista devolve apenas as tarefas de upload reforçado do usuário ao qual a chave de API atual pertence; tarefas de geração normal, cover ou extend não se misturam.

Parâmetros de query

Exemplo de requisição

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"

Resposta

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

Referência dos campos da resposta

Observações

• Atualmente o endpoint só aceita upload de arquivo multipart; não aceita file_url nem file_base64 em JSON.
• O arquivo enviado pode ter no máximo 80 MB.
• O endpoint de envio é assíncrono: uma resposta queued significa que a tarefa entrou na fila, não que o áudio esteja pronto.
• O cancelamento só vale para tarefas que ainda não começaram a ser processadas; depois que o processamento começa, o fluxo da conta da plataforma não é interrompido.
• Não exponha chaves de API reais no código do cliente.

Iniciar um cover ao concluir o upload reforçado

Quando o upload reforçado terminar, você pode usar o resultado como clip de origem e chamar POST /api/music/generate-from-source para iniciar um cover.

Atenção: o cover é um endpoint síncrono — o pedido só é aceito quando a resposta chega, e em casos medidos pode levar até cerca de 230 segundos. Defina o timeout do cliente em 300 segundos ou mais e não repita logo após um timeout. Veja "Tempos de espera e configuração de timeout" na Visão geral da nova API.

Primeiro consulte GET /api/music/enhanced-upload/:id até task.status ser completed. Nesse momento:

• task.song_id é o ID real da música e é o sourceClipId de que o endpoint de cover precisa;
• recomenda-se passar task.audio_url como sourceAudioUrl, para o servidor tratar o caso em que o clip de origem e a conta de execução não coincidem;
• task.task_id é apenas o ID da tarefa de upload reforçado e não pode ser usado como sourceClipId;
• pending:enhanced-upload:* é um ID de preenchimento da etapa de processamento e não pode ser usado para cover.

Ao iniciar o cover, use a mesma chave de API do upload reforçado e monte a requisição conforme a correspondência abaixo:

Preencha os demais parâmetros (letra, estilo, título, modelo) conforme a API de cover a partir de um clip de origem. Quando o endpoint de cover devolver o novo clips[].song_id, use POST /api/music/query para consultar o status de geração e o áudio final.