Sintetizar Fala
Use esta ação quando tiver um texto e quiser um arquivo de áudio com ele falado, salvo no storage da sua empresa.
Melhor para
- Falar uma confirmação de pedido, um lembrete de agendamento ou um prompt de URA
- Produzir um áudio para enviar de volta por um canal
- Transformar o texto que um passo anterior produziu em um arquivo de áudio que você pode anexar ou guardar
Use outra coisa quando
| Você quer | Use |
|---|---|
| Uma transcrição da fala, e não fala a partir de texto | Transcrever Áudio — ela vai no sentido oposto |
| Reconverter um áudio que você já tem | Transformar Mídia — esta ação só cria áudio novo a partir de texto |
| Falar um texto vindo de um LLM ou de um campo de texto formatado | Preparar Texto Falado primeiro, depois esta ação |
Campos principais
| Campo | O que faz |
|---|---|
| Texto | O texto a falar, com no máximo 4096 caracteres. Normalmente step(N).text de um passo anterior |
| Perfil de voz | Qual voz usar. Deixe vazio para usar o padrão da sua empresa |
| Formatar | mp3 (o padrão) ou opus |
| Finalidade | Rótulo opcional para o que este passo faz, exibido nos registros |
Apenas Texto aceita uma expressão. Perfil de voz, Formatar e Finalidade são lidos exatamente como você os define, então uma expressão CEL escrita em um desses campos não é avaliada — ela é descartada, e você recebe silenciosamente a voz ou o formato padrão. Escolha esses valores nos próprios campos.
O áudio já está pronto quando o passo termina
Diferente de Transcrever Áudio e Transformar Mídia, esta ação não enfileira um trabalho. Ela sintetiza o áudio na hora, então não há nada para acompanhar nem esperar.
Quando o passo seguinte roda, step(N).file já aponta para um objeto de áudio que realmente existe. Você pode anexá-lo, guardá-lo ou passá-lo direto para outro passo de mídia na mesma execução.
O que passos posteriores podem usar
| Valor | O que é |
|---|---|
step(N).file | A referência {bucket, fullPath} que toda ação de mídia produz. Envie-a para anexos de Enviar Mensagem ao Contato, para um campo de arquivo ou para Inspecionar Mídia |
step(N).bucket | O bucket de storage onde o áudio foi gravado |
step(N).fullPath | O caminho completo do objeto de áudio |
step(N).size | O tamanho do áudio em bytes |
step(N).contentType | audio/mpeg para mp3, audio/ogg para opus |
step(N).format | O formato que foi realmente usado |
step(N).cache | hit quando uma requisição idêntica recente foi reaproveitada, caso contrário miss |
step(N).billedMeter | tts_ms quando a síntese foi cobrada, audio_ms_byok quando ela rodou na sua própria chave de provedor e não foi cobrada, ou vazio em um hit de cache |
step(N).billedMs | Os milissegundos registrados em billedMeter, e 0 em um hit de cache |
Leia o resultado com step(N).billedMs, não com step(N).status — status é reservado para códigos de status HTTP, e esta ação deliberadamente nunca o escreve. Use step_ok(N) para testar se o passo deu certo.
Vozes
Um perfil de voz guarda a voz, o provedor e as configurações usadas para falar o seu texto. Você gerencia os perfis nas configurações da sua empresa, e um deles pode ser marcado como padrão.
Esta ação escolhe a voz nesta ordem:
- O Perfil de voz que você indicou no passo
- O perfil padrão da sua empresa
- A voz da plataforma já embutida, para que a síntese funcione antes de você configurar qualquer coisa
Uma voz fixada em um canal não é usada aqui. Essa fixação vale apenas dentro do aplicativo, onde uma conversa identifica o seu canal. Um workflow não tem conversa para resolver, então, se você quiser uma voz específica, indique o perfil no passo.
Limites
| Limite | Valor |
|---|---|
| Tamanho do texto | 4096 caracteres, cerca de 700 palavras ou cinco minutos de fala |
| Requisições de fala | 60 por minuto, por empresa |
Textos maiores são rejeitados, não divididos. Não existe divisão automática no servidor nem junção de áudios, então um texto acima do limite falha em vez de produzir um arquivo parcial. Se precisar de mais, divida o texto em vários passos e aceite um arquivo de áudio por passo.
O teto de 60 por minuto é compartilhado com o modo de voz do aplicativo e com Preparar Texto Falado, então um par preparar-e-falar custa duas dessas requisições por execução. Um laço apertado de síntese pode consumir a franquia e interromper quem estiver usando voz no aplicativo ao mesmo tempo — controle o ritmo do workflow se ele sintetizar em massa.
Custo
A síntese é descontada do uso de áudio do seu plano, com base no tamanho do texto e não na duração do áudio final. As vozes variam bastante de preço: algumas custam várias vezes mais por minuto do que outras, então o perfil de voz que você escolhe altera a conta.
Perfis que usam a sua própria chave de provedor são registrados, mas não cobrados pelo AutoTalk — o seu provedor cobra você diretamente. Confira step(N).billedMeter antes de ler step(N).billedMs: na sua própria chave, esse número é uma estimativa para o seu controle, não uma cobrança.
Falar o mesmo texto de novo pouco tempo depois costuma ser gratuito. Repetir um texto idêntico com a mesma voz e formato dentro de cerca de dez minutos reaproveita o áudio anterior, não faz chamada ao provedor e reporta cache: hit com billedMs: 0. Isso é um reaproveitamento de melhor esforço, não uma garantia — um período de pico ou uma reinicialização podem transformá-lo de volta em uma chamada normal e cobrada. Áudio produzido na sua própria chave de provedor nunca é reaproveitado assim.
Um hit de cache ainda grava um arquivo novo. Toda chamada guarda o seu próprio objeto de áudio, então um workflow que fala o mesmo texto em um laço continua aumentando o seu uso de storage mesmo quando a síntese em si não custa nada.
Quando falha
| Código | O que aconteceu |
|---|---|
speech_missing_text | A expressão de Texto não resolveu para nada |
speech_text_too_long | O texto passa de 4096 caracteres. Divida-o em vários passos |
speech_format_invalid | Formatar está com algo diferente de mp3 ou opus |
voice_profile_not_found | O perfil indicado no passo não existe |
voice_profile_id_invalid | Perfil de voz não contém uma referência de perfil válida — muitas vezes uma expressão que não foi avaliada |
limits_reached | A franquia de áudio do seu plano acabou neste mês |
rate_limit_error | Mais de 60 requisições de fala no mesmo minuto. Vale tentar de novo em instantes |
storage_quota_exceeded | O áudio foi produzido, mas o seu storage está cheio e ele não pôde ser salvo |
speech_synthesis_failed | O provedor de voz não pôde ser alcançado ou recusou a requisição. Vale tentar de novo |
storage_quota_exceeded é o que merece atenção: o áudio foi sintetizado e contabilizado antes da tentativa de gravação, então o uso foi gasto mesmo sem nenhum arquivo ter chegado. Libere espaço no storage antes de tentar de novo.
Em outros lugares
A mesma capacidade está disponível fora dos workflows como a ferramenta MCP synthesize_speech e como POST /v1/speech na API. As três produzem o mesmo áudio e os mesmos campos; muda apenas onde o arquivo é guardado.