Introdução
Envie o texto a ser lido e, opcionalmente, uma das 30 vozes, um sotaque, um estilo, um ritmo, uma cena e uma nota curta sobre a interpretação; para uma conversa, envie dialogue e speakers no lugar de text. A tarefa retorna um arquivo WAV (24 kHz, 16 bits, mono) com o roteiro lido nessa voz, ou em até duas vozes num diálogo. Dentro do roteiro, marcações entre colchetes como [whispering], [sighs] ou [laughing] são interpretadas em vez de lidas, e a pontuação define as pausas. O SpicyAPI não aplica nenhum filtro de conteúdo: os roteiros que o aplicativo oficial bloquearia são lidos como escritos. A cobrança é por segundo de áudio retornado.
| Campo | Valor |
|---|---|
| Entrada | Texto |
| Saída | Áudio |
| Campo obrigatório | text (1 a 5.000 caracteres) ou dialogue (até 20 falas) |
| Campos opcionais |
|
| Resultado | Um arquivo WAV, 24 kHz, 16 bits, mono |
| Clipe mais longo | 16.384 tokens de áudio |
| Quantidade cobrada | Segundos de áudio entregue, medidos a partir do arquivo |
| Retenção | O áudio gerado é mantido por 14 dias |
Parâmetros da requisição
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
text | Não | As palavras a serem faladas, exatamente como escritas. Indicações entre colchetes como [whispering] ou [sighs] são interpretadas, não lidas. pelo menos 1 caracteres · no máximo 5000 caracteres |
dialogue | Não | Uma conversa roteirizada para até duas vozes, usada no lugar de text: até 20 falas, cada uma com speaker (um nome de speakers) e text de até 250 caracteres. pelo menos 1 itens · no máximo 20 itens |
speakers | Não | O elenco de dialogue: uma ou duas entradas, cada uma com um name ao qual as falas se referem, um |
voice_id | Não | Uma das 30 vozes prontas, cada uma com um caráter fixo. O padrão é Kore. |
style | Não | Jeito geral da leitura. Deixe vazio para usar o jeito padrão da voz. |
pace | Não | Ritmo da leitura: natural, |
accent | Não | Sotaque do inglês usado na leitura. Se você não definir, vale o sotaque próprio da voz. |
instructions | Não | Instrução livre sobre como ler: ritmo, clima, distância do microfone, ouvinte. Molda a interpretação e não é falada. no máximo 1000 caracteres |
scene | Não | Onde e para quem as palavras são ditas, por exemplo “um quarto de hotel silencioso depois da meia-noite”. Molda a interpretação e não é lido em voz alta. no máximo 500 caracteres |
temperature | Não | Variação entre as tomadas, de 0 a 2: valores mais altos deixam a interpretação menos previsível. Se você não definir, vale o padrão do modelo. |
Preços
$0.00032 / segundo
Cobrado por segundo de áudio entregue. Um valor equivalente a 660 segundos fica retido enquanto a tarefa está em execução, e a parte não usada é liberada quando o áudio é medido.
Casos de uso
Audiobooks e narrações longas
Capítulos, histórias para dormir e ficção seriada lidos por um narrador constante. Escolha uma voz uma vez e mantenha-a: a mesma voz soa consistente de um capítulo para outro.
Vozes de personagens e companheiros
Dê a um personagem de chat uma voz própria. Uma indicação [whispering] e frases curtas com estilo falado transformam texto simples em falas que soam feitas para um único ouvinte.
Histórias em áudio sem censura
Os roteiros sem filtro são lidos como escritos. Em nossos testes, o modelo falou cada palavra dos monólogos e das narrações enviados, e interpretou as indicações entre colchetes, como suspiros e arfadas, em vez de ler as tags.
Trilhas de voz para vídeo
Gere a fala aqui e depois passe o WAV para um modelo de avatar falante ou lip-sync para que um rosto a interprete. A duração do áudio define a duração do clipe seguinte.
Guia de prompt e dicas práticas
Envie o roteiro em texto
Escreva-o exatamente como deve ser falado, incluindo a pontuação para as pausas. Até 5.000 caracteres.
Escolha uma voz
voice_idusa Kore por padrão. Cada uma das 30 vozes tem um caráter fixo, então escolha uma vez e mantenha-a para uma série.Escreva a direção no roteiro
Coloque indicações entre colchetes exatamente onde devem acontecer — [whispering], [sighs], [laughing], [gasping]. Elas são interpretadas, não lidas em voz alta.
O que ele retorna
Um arquivo WAV por tarefa: 24 kHz, 16 bits, PCM mono. O arquivo é copiado para o armazenamento da SpicyAPI e mantido por 14 dias. O resultado não tem marcação de tempo por palavra nem legendas.
Escolhendo uma voz
voice_id aceita uma das 30 vozes prontas e usa Kore por padrão. Cada voz tem um caráter fixo — por exemplo, Kore firme, Charon informativa, Puck animada, Enceladus sussurrada, Achernar suave, Algenib rouca, Sulafat calorosa, Gacrux madura. A voz não muda com o idioma do roteiro.
Dirigindo a performance
Além de text e voice_id, estas configurações moldam a leitura:
style,accentepacedefinem o jeito, o sotaque do inglês e o ritmo; sem eles, a voz mantém os seus.instructionsrecebe texto livre sobre como ler, escenediz onde e para quem as palavras são ditas. Nenhum dos dois é lido em voz alta.temperature(0–2) define quanto a interpretação varia entre as tomadas.
Dentro do próprio text:
- Indicações entre colchetes como
[whispering],[sighs],[laughing]ou[gasping]são interpretadas em vez de lidas em voz alta. - Vírgulas, reticências e pontos finais definem as pausas.
Neste modelo, a direção enviada para uma única voz pode ser lida em voz alta no início do clipe. Por isso, quando uma solicitação de uma só voz traz style, accent, pace, instructions ou scene, a SpicyAPI a envia no formato de dois falantes do modelo, com um segundo falante em silêncio, o que mantém as notas fora do áudio. A cobrança não muda: você paga pelos segundos retornados.
Duas vozes em um clipe
Para uma conversa, envie dialogue no lugar de text, junto com speakers com o elenco: uma ou duas entradas, cada uma com um name, um voice_id e, opcionalmente, accent, style, pace e profile, uma descrição curta de quem fala que não é lida em voz alta. Cada fala de dialogue é {speaker, text}, em que speaker é um desses nomes; as falas são interpretadas em ordem, até 20 falas de 250 caracteres cada. O que uma entrada não definir vem de accent, style e pace do nível superior. A conversa inteira volta como um único arquivo WAV, cobrado por segundo como qualquer outra solicitação.
Duração e tempo
text aceita até 5.000 caracteres. Em nossos testes, um parágrafo de 270 caracteres resultou em 20 a 24 segundos de áudio. O modelo para em 16.384 tokens de áudio por clipe. A maioria das tarefas termina em menos de um minuto.
Cobrança
Cobrado por segundo de áudio entregue, medido a partir do arquivo. Enquanto a tarefa está em execução, um valor equivalente a 660 segundos fica retido no seu saldo, e a parte não usada é liberada quando a tarefa é liquidada. Solicitações que falham não são cobradas.
Conteúdo
A SpicyAPI não adiciona nenhum filtro de conteúdo. Em nossos testes, os roteiros sem filtro foram lidos palavra por palavra, e as indicações entre colchetes, como suspiros e arfadas, foram interpretadas em vez de lidas.
O SpicyAPI não adiciona filtro de conteúdo: os roteiros são lidos como escritos, sem nenhum abrandamento. Você é responsável pelos roteiros que envia e pelo uso que faz do áudio resultante, incluindo não apresentá-lo como as palavras de uma pessoa real.
Início rápido da API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "google/gemini-3.8-flash-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"voice_id": "Kore"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulte a referência da API para autenticação, esquema completo, polling e tratamento de erros.
