API de upload de áudio de origem

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

Descrição do endpoint

O upload de áudio de origem transforma um arquivo de áudio local ou remoto num clip de origem que as capacidades seguintes podem usar: cover, extensão, substituição de trecho, separação e outras.

Endpoint: POST /api/music/upload-source

Cobrança: Grátis. Este endpoint apenas envia o áudio de origem; não inicia nenhuma tarefa de geração.

Uso recomendado: é o passo 1 do «cover em duas etapas». Suba o áudio primeiro com este endpoint (é grátis e você pode tentar de novo sempre que falhar) e guarde o clip_id devolvido; depois de confirmar que o envio foi concluído (status em estado final), chame a API de cover a partir de um clip de origem para iniciar o cover — o corpo dessa requisição tem apenas algumas centenas de bytes, portanto não pode ser truncado em trânsito por o áudio ser grande demais. Em comparação com a API de uma só vez enviar e fazer cover, esta divisão é mais robusta quando o áudio é grande, a rede é instável ou o mesmo material será reutilizado várias vezes (extensão / substituição / separação).

Dicas para envio de arquivos grandes

Quando o envio terminar, confirme sempre que o status da resposta já é um estado final e guarde o clip_id antes de seguir para o passo 2; um envio que falha não é cobrado e não cria tarefa de geração, basta tentar de novo.

Verifique file_url antes do upload

O nosso servidor baixa file_url diretamente por HTTP, não o navegador. Uma URL que abre no navegador não garante que os servidores de produção consigam acessá-la.

Para ficheiros locais, use upload multipart com o campo file. Não use file_url com links ByteDance ou URLs assinadas temporárias, a menos que sejam públicas e ainda válidas no momento do pedido.

Execute isto a partir de um servidor público antes de enviar o pedido de upload:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

O pedido GET deve terminar em HTTP 200, devolver um MIME de áudio e conter dados. Páginas de login, HTML e códigos 401, 403, 404 ou 410 não podem ser usados pelo servidor.

file_url download failed: HTTP 404 normalmente indica assinatura expirada, ficheiro eliminado ou parâmetros da URL em falta.

O upload é gratuito. Se o download de file_url falhar, não é criado clip_id, tarefa de música nem chamada de geração e não há cobrança; não é necessário reembolso.

Parâmetros da requisição

Headers

Para requisições JSON:

Não defina Content-Type manualmente em requisições multipart; o cliente gera automaticamente.

Parâmetros do corpo

Exemplo de requisição JSON

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

Exemplo de requisição multipart

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

Resposta

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}