API de consulta e histórico de músicas

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

Esta página cobre três endpoints de consulta gratuitos:

Se você usou o modo de recibo de aceite (accept_mode=async) em um endpoint de geração, o que você tem é um número de recibo, não um ID de música. Acompanhe o progresso com GET /api/music/requests/{request_id} e volte aos endpoints desta página quando tiver o song_id real. Veja "Modo de recibo de aceite" na API de geração no modo simples.

Autenticação e escopo dos dados

Os três endpoints autenticam com a mesma chave de API:

Authorization: Bearer YOUR_API_KEY

O histórico de músicas é isolado pelo user_id ao qual a chave de API pertence. Várias chaves criadas sob a mesma conta principal podem ler o histórico dessa conta, mas não o de outro usuário nem o de outra conta de subsite.

Os endpoints de histórico retornam apenas músicas realmente geradas. Ficam de fora:

• registros de reserva de geração que começam com pending:;
• uploads de áudio de origem e registros de upload aprimorado;
• subresultados, como separação de voz/acompanhamento e stems;
• músicas de outros usuários ou de contas de subsite.

1. Consultar o status de geração

Consulta o status atual e o resultado final de um ou vários IDs de música.

Endpoint: POST /api/music/query

Cobrança: Grátis.

Headers

Parâmetros do body

Exemplo de requisição

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

Exemplo de resposta

[
  {
    "song_id": "clip_id_1",
    "song_title": "Título da música",
    "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 da letra",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Notas de compatibilidade

A documentação antiga pode mostrar song_ids como array. Hoje recomenda-se uma string separada por vírgulas, que é como o endpoint é realmente chamado.

song_ids deve conter IDs de música reais. Um ID de reserva que começa com pending: não é um song_id final e não pode ser usado aqui; consultar apenas IDs de reserva pode devolver um array vazio [].

O model, o model_version ou o model_name de plataforma na resposta podem manter valores históricos. Tarefas novas devem usar suno-v6, suno-v6-wild ou suno-v6-mini; de suno-v2 a suno-v5-5 estão aposentados, e ver esses nomes no histórico não significa que o modelo ainda aceite envios.

Enquanto uma tarefa está em pending, submitted ou processing, audio_url, video_url e cover_url podem estar vazios — isso é normal em uma tarefa não concluída. Não conclua falha apenas porque o endereço está vazio; use o status e consulte de novo quando o status estiver completo. Só quando o status estiver completo e os endereços continuarem vazios vale contatar o suporte informando o song_id.

⚠️ Os endereços de áudio duram 7 dias — transfira seus arquivos a tempo

O audio_url, o video_url (e outros endereços de mídia, como o WAV) retornados aqui são servidos pelo armazenamento de objetos da plataforma e expiram em 7 dias por padrão: os arquivos são reciclados e o endereço antigo passa a devolver 404.

• Mova os arquivos para o seu próprio armazenamento dentro desses 7 dias; não trate o endereço como um link de longa duração.
• Um endereço expirado não exige regerar a música e não é cobrado de novo: chame este endpoint (POST /api/music/query) outra vez para obter um endereço novo e válido daquela música.

2. Consultar o histórico de músicas da conta

Lista as músicas geradas pela conta principal à qual a chave de API atual pertence. Útil para montar sua própria lista de músicas, um seletor ou uma página de histórico.

Endpoint: GET /api/music/songs

Cobrança: Grátis.

Parâmetros de query

Os resultados são ordenados por created_at e pelo ID de registro interno em ordem decrescente, então a ordem de paginação é estável.

Recuperar um envio que deu timeout: endpoints de geração não dão resposta intermediária antes da aceitação. Se o seu cliente estourou o tempo ou a conexão caiu ao enviar, esse pedido pode já estar aceito e sendo gerado. Olhe este endpoint (mais recentes primeiro): músicas aceitas aparecem normalmente na lista. Só reenvie depois de confirmar que ela realmente não está lá, para não pagar duas vezes. Veja "Tempos de espera e configuração de timeout" na Visão geral da nova API.

Exemplo de requisição

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

Exemplo de resposta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "A cidade à noite",
        "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 da resposta

O endpoint de listagem não retorna prompts, campos de cobrança, informações da conta nem respostas brutas. Para prompts e parâmetros de geração, chame o endpoint de detalhe da música.

3. Consultar os parâmetros de geração

Consulta o prompt, o estilo, o modelo e a música de origem que a plataforma guardou quando a música foi gerada.

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

Cobrança: Grátis.

Só podem ser lidas músicas da conta principal à qual a chave de API atual pertence. Músicas de outros usuários ou de contas de subsite são sempre tratadas como "música não encontrada".

Parâmetro de rota

Exemplo de requisição

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

Exemplo de resposta

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "A cidade à noite",
    "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": "ruas da cidade depois da chuva, letra sobre um reencontro",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "A cidade à noite",
      "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"
      ]
    }
  }
}

Os campos de parameters

O campo prompt_view (ver prompt, adicionado em 2026-09-28)

prompt_view é uma estrutura normalizada dedicada a "ver o prompt": organiza os dados em seções fixas por tipo de geração, para que o cliente não precise mais decidir qual campo exibir. É um campo puramente aditivo — os campos antigos (parameters, parameter_retention) mantêm nome e sentido, e clientes que não analisam o campo novo não são afetados em nada.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Modo personalizado",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Quatro da manhã#701f37", "title_base": "Quatro da manhã", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "eletrônica guochao, sub bass profundo, sintetizador retrô",
    "style_tags": "eletrônica guochao, sub bass profundo, sintetizador retrô",
    "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 podem aparecer em extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, além do grupo de efeitos sonoros sound_type / sound_bpm / sound_key / sound_loop. Valores vazios nunca são retornados.

Três regras de exibição (siga-as em vez de deduzir):

1. Distinga de onde veio o estilo: com style_source=suno_derived, exiba como "estilo (deduzido pelo Suno a partir da sua descrição)" e nunca como "seu estilo";
2. Prompts internos nunca aparecem: os tipos de cover com voz retornam apenas os 【requisitos de estilo】/【requisitos de cover】 digitados pelo usuário; a estrutura fixa que montamos para o modelo não aparece em campo algum (os dados históricos passam pela mesma sanitização);
3. Não adivinhe parâmetros ausentes: se extended não contém, não foi registrado na época — use retention para explicar o motivo.

Notas sobre retenção de parâmetros

parameter_retention existe para separar "um valor vazio foi enviado explicitamente" de "o campo nunca foi guardado historicamente":

• core_parameters_available: se o registro principal da tarefa existe; normalmente true em um detalhe válido;
• extended_parameters_available: se um registro de tarefa de música estendida relacionado foi encontrado;
• sources: de quais tabelas de dados esta resposta veio;
• unavailable_fields: campos que não podem ser recuperados de forma confiável do histórico; retornam null dentro de parameters.

Músicas históricas comuns costumam guardar o prompt, o estilo, o título atual, o modelo, o tipo de geração e a música de origem, mas não guardaram todos os parâmetros avançados em separado. A plataforma nunca adivinha valores ausentes a partir do generation_type.

Algumas tarefas de música estendida também guardaram o prompt original, o estilo, o título, o modelo e ainda custom_mode, negative_tags, vocal_gender, style_weight e weirdness_constraint. Mesmo quando existe o registro estendido, instrumental, lyrics_mode e wait_audio podem continuar irrecuperáveis.

Os títulos podem ser renomeados pelo usuário depois. Quando uma tarefa histórica comum não guardou um título original separado, parameters.title pode ser o título atual; quando existe registro de tarefa estendida, prevalece o título de geração original guardado ali.

Não encontrada ou sem permissão

Erros de negócio usam um envelope de resposta uniforme. Quando a música não existe ou não pertence à conta atual:

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

Esse erro de negócio hoje retorna HTTP 200, então julgue o resultado pelo campo success. Uma chave de API ausente, inválida, expirada ou desativada retorna HTTP 401.

Notas de segurança

Os endpoints de histórico e detalhe nunca retornam:

• chaves de API ou IDs de token;
• campos de cota, cobrança ou reembolso;
• informações da conta ou respostas brutas;
• chaves internas do armazenamento de objetos;
• erros de administrador ou erros de recursos internos.