API de geração de fala (Speech)

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

Descrição do endpoint

Speech transforma um roteiro de discurso ou uma descrição de uma linha em áudio de "fala/discurso", com música de fundo opcional. Serve para discursos, brindes, narração, roteiros de locução, conteúdo em áudio e cenários parecidos.

Atenção: este endpoint gera áudio falado, não uma música cantada (sem melodia e sem voz cantada). Se precisar de canto, use a API de geração no modo simples ou a API de geração no modo personalizado.

Endpoint: POST /api/music/speech

Cobrança: Pago, atualmente ¥0,6 por chamada por padrão. Cada chamada costuma devolver 2 áudios; o valor realmente cobrado segue a configuração de preços 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 segundos (1-10 s); mas, como nos demais endpoints de geração síncronos, em casos extremos pode demorar mais. 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.

Conformidade de conteúdo: a plataforma verifica o roteiro quanto a direitos autorais e políticas de conteúdo. Se for considerado material protegido (por exemplo citar a letra de outra pessoa ou o texto literal de uma obra conhecida), esta chamada falha e o valor é devolvido integralmente de forma automática. Troque pela sua própria redação, ou transforme a citação em paráfrase, e tente de novo.

Parâmetros da requisição

Headers

Parâmetros do body

Este endpoint não aceita duration: enviá-lo devolve HTTP 400, e não é ignorado em silêncio. A duração do discurso é determinada pelo comprimento do conteúdo de script.

Exemplos de requisição

Requisição mínima (só o roteiro)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Bom dia a todos! Hoje minha fala é sobre aproveitar bem o nosso tempo e seguir em frente."
  }'

Requisição completa (com tom, gênero e música de fundo desligada)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Exemplo em Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Boa tarde, colegas. Vou relatar o andamento desta semana.',
        'tone': 'sereno e claro, relatório de reunião',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # normalmente 2 itens
for item in items:
    print(item['song_id'], item['status'])

Notas sobre os parâmetros

script (o discurso, obrigatório)

• Cole o conteúdo que você quer falar; também é possível escrever uma única descrição e deixar o modelo redigir o discurso (por exemplo "uma preleção de intervalo para um time vinte pontos atrás, de um sussurro baixo a um rugido em plenos pulmões").
• Quebras de linha, parágrafos e marcações de cena como [pausa] podem ser escritas direto e o modelo as seguirá na medida do possível.
• O limite é de 3000 caracteres (contados em caracteres Unicode; um ideograma chinês conta como 1); passar disso devolve 400 e não cobra.

tone (tom e cenário, opcional)

Descreve como falar, e não o que dizer. Vale incluir quatro tipos de informação: tom, velocidade/ritmo, emoção e cenário.

Enérgico e potente, acelerando de um ritmo lento, pausas claras; auditório, diante de todos os alunos e professores
Caloroso e suave, ritmo pausado; recepção de casamento
Sereno e contido, ritmo constante e claro; relatório ao conselho

O limite é de 1000 caracteres. Se não enviar, o modelo deduz do conteúdo de script.

gender / vocal_gender (gênero de quem fala, opcional)

• Para voz masculina envie m ou male, para feminina f ou female; o servidor normaliza para m / f.
• Os dois nomes de campo funcionam; use apenas um: gender é a forma recomendada neste endpoint; se você já usa o modo personalizado, pode continuar usando vocal_gender.
• Omitir significa "qualquer", e o modelo decide.

backing_music (música de fundo, opcional)

• O padrão é true (com música de fundo), igual ao padrão da versão web do Suno.
• false gera um discurso só com voz, útil se depois você quiser adicionar sua própria trilha ou locução.
• Deve ser um booleano JSON true / false; as strings "true" e "1" também são aceitas, mas recomendamos booleanos.

model (modelo, opcional)

Os três modelos de cara ao cliente estão disponíveis pelo mesmo preço (¥0,6 por chamada). O discurso é gerado pela família Suno v6; se for omitido, é tratado como suno-v6. A menos que você tenha uma preferência clara, normalmente não é preciso enviar este campo.

Validação de parâmetros e limites de texto

Os casos abaixo devolvem HTTP 400 e todos são bloqueados antes da cobrança, portanto não geram nenhum custo:

Limites dos campos de texto

Passar do limite também devolve HTTP 400 e não inicia a geração nem faz pré-cobrança. A contagem é por caracteres Unicode (um ideograma chinês conta como 1) e inclui os espaços no início e no fim:

O erro tem a forma script must not exceed 3000 characters; received 4120: a primeira palavra é o campo que passou do limite e o final é a contagem real, então diante de um 400 você pode cortar direto com esses dois números.

Resposta

A resposta é um array de músicas exatamente igual ao dos outros endpoints de geração (normalmente 2 itens); guarde o song_id e use a API de consulta e histórico de músicas para ver o status final e o endereço do áudio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Aproveitar bem o tempo",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Falha de geração e reembolsos

Quando a geração falha, o valor da chamada é devolvido integralmente de forma automática; não é preciso falar com o suporte. O motivo aparece na resposta ou no error_message da API de consulta e histórico de músicas.

A falha mais comum é a plataforma considerar que o conteúdo envolve material protegido, por exemplo:

Your lyrics contain copyrighted material. Please change it and try again.

Nesse caso, troque o roteiro pela sua própria redação (ou transforme a citação em paráfrase) e envie de novo.

Perguntas frequentes

P: Por que o resultado é "fala" e não canto? R: Este é o endpoint de discursos e a saída é áudio falado. Para cantar, use os endpoints de geração ou do modo personalizado.

P: Por que vêm 2 itens de cada vez? R: Como nos demais endpoints de geração da plataforma, uma geração produz 2 candidatos; consulte cada um por song_id e fique com o que preferir.

P: Como controlo a duração? R: Ela é determinada pelo comprimento de script; este endpoint não aceita o parâmetro duration.

P: Posso indicar uma voz (por exemplo a minha voz clonada)? R: A versão atual não permite. O discurso usa um conjunto fixo de vozes e gender escolhe masculina ou feminina; se precisar da sua própria voz, use o recurso correspondente da API de criação de perfil de voz (recomendado).

P: O que acontece se eu não enviar tone? R: O modelo deduz tom e ritmo do conteúdo de script. Para reproduzir um estilo de forma estável, escreva tom, velocidade e cenário em tone.

Campos compatíveis

Em integrações novas, use snake_case de forma consistente. Os outros campos (script, tone, song_title, backing_music) não têm alias em camelCase.

Próximos passos

Depois de obter o song_id:

1. Use a API de consulta e histórico de músicas para ver o status de geração e o endereço do áudio;
2. Ao concluir, use a API de download e pré-visualização de mídia de músicas para baixar ou ouvir;
3. Para downloads em lote ou copiar para o seu próprio armazenamento, veja os endpoints do centro de downloads.