API de geração no modo personalizado

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

Descrição do endpoint

O modo personalizado serve para quando você já tem letra, estilo e título prontos e quer controlar a voz que canta, a força com que o estilo é seguido e o grau de aleatoriedade da geração.

Endpoint: POST /api/music/create/custom

Cobrança: Pago, atualmente ¥0,6 por chamada por padrão. Cada chamada costuma devolver 2 músicas; o valor realmente cobrado segue a configuração de preços atual do back-office.

Max Mode / Variety: este endpoint aceita os parâmetros opcionais max_mode e variety (0-4). Com max_mode ligado, esta chamada é cobrada em 2× o preço (0,6 → 1,2 ¥ por chamada); variety não custa nada a mais. O que significam e como enviá-los está na seção "Parâmetros avançados" da Visão geral da nova API.

Tempos de espera e timeouts (importante): este é um endpoint síncrono — o pedido só é aceito e entregue à geração quando a resposta chega. Pelo medido, a maioria das requisições responde em 1-3 segundos, cerca de 10% leva mais de 30 segundos e a mais longa fica em torno de 230 segundos. Defina o timeout do cliente em 300 segundos ou mais; não receber resposta não significa que nada foi gerado, e não repita logo após um timeout (isso duplica o pedido e cobra de novo). Se a conexão caiu, confirme depois com GET /api/music/songs. Veja "Tempos de espera e configuração de timeout" na Visão geral da nova API.

Parâmetros da requisição

Headers

Parâmetros do body

Notas sobre os parâmetros avançados

Gênero vocal vocal_gender

• Envie m ou male para voz masculina, f ou female para voz feminina.
• O serviço normaliza male e female para m e f, respectivamente.
• Com instrumental=true, nenhum parâmetro de gênero vocal é enviado ao serviço de geração.

Influência do estilo style_weight

Controla com que força o resultado segue style_tags. Quanto maior o valor, mais o resultado tende a seguir as tags que você enviou.

Aleatoriedade weirdness_constraint

Controla quanto o resultado varia e experimenta. Valores altos costumam dar mais variação; valores baixos costumam dar um resultado mais seguro.

Ambos os parâmetros numéricos vão de 0.0 a 1.0, e 0 é um valor explícito válido. Só omitir o campo por completo significa "não especificado".

Ao preencher, lembre-se de que são frações decimais, não inteiros de porcentagem. Referência sugerida: de 0.0 a 0.3 é conservador, de 0.4 a 0.6 é equilibrado, de 0.7 a 1.0 é mais experimental; sem preferência clara use 0.5 ou simplesmente omita. Exemplo: weirdness_constraint: 0.5, nunca 50 ou 50%.

Com instrumental=true o resultado é instrumental, então a letra e o gênero vocal não atuam como numa música cantada; se precisar de voz, envie false ou omita o campo. Campos booleanos devem usar true/false do JSON, não strings.

Exemplo de requisição em Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nA noite cai sobre o mar\numa brisa passa pela janela',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Brisa da tarde à beira-mar',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Modo de recibo de aceite (opcional)

Este endpoint também aceita o modo de recibo de aceite da API de geração no modo simples: com "accept_mode": "async" no body (ou a cabeçalho X-Accept-Mode: async), o endpoint devolve 202 e um número de recibo na hora, a geração continua em segundo plano, e você acompanha com GET /api/music/requests/{request_id}.

Serve para clientes que não devem manter conexões longas, ou que não querem que um timeout seja lido como "nada foi gerado". Sem esse parâmetro, o comportamento é exatamente o de antes.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Brisa da tarde à beira-mar",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

A forma da resposta e o método de polling estão na seção "Modo de recibo de aceite" da API de geração no modo simples.

Validação de parâmetros

Estes casos devolvem HTTP 400, e o message do erro nomeia o campo inválido:

• style_weight ou weirdness_constraint não é um número.
• Um valor numérico está abaixo de 0.0 ou acima de 1.0.
• vocal_gender não é um de m, f, male, female.

Limites dos campos de texto

Estes campos também devolvem HTTP 400 quando longos demais, e nunca entram na geração nem são pré-cobrados. A contagem é por caractere Unicode (um caractere han conta como 1) e inclui espaços no início e no fim:

A mensagem de erro tem a forma style_tags must not exceed 1000 characters; received 2772: a primeira palavra é o campo que estourou e o final é a contagem medida, então em um 400 você corta por esses dois números em vez de testar campo a campo. As convenções gerais estão em "Limites de campos de texto" da Visão geral da nova API.

Resposta

O endpoint costuma devolver um array com 2 músicas. Uma requisição assíncrona começa normalmente em pending; salve o song_id e leia o estado final e o endereço de áudio pela API de consulta de músicas. Os campos de música são os mesmos da API de geração no modo simples.

Campos compatíveis

Integrações novas devem usar snake_case em tudo. Se uma mesma requisição levar snake_case e camelCase, prevalece o valor em snake_case.