fish.audio TTS
Requer FISH_AUDIO_API_KEY no .env (crie uma em https://fish.audio/go-api/api-keys/).
Crie modelos de voz no playground fish.audio e passe o ID deles como reference_id para reutilizar uma voz clonada.
API Atual
Chamada síncrona única que retorna bytes de áudio bruto:
POST https://api.fish.audio/v1/tts
Authorization: Bearer ${FISH_AUDIO_API_KEY}
Content-Type: application/json
model: <modelo do backend> # Cabeçalho HTTP seleciona o backend, ex: s1
O modelo do backend é escolhido com o cabeçalho HTTP model, não um campo no corpo. No OpenMontage, isso mapeia para a entrada model da ferramenta.
Modelos de backend
model é obrigatório — não há padrão. Passe um dos seguintes:
s2.1-pro— última geração. Melhor qualidade: tags de emoção inline, 80+ idiomas, multi-locutor. Narração heróica.s2.1-pro-free— acesso gratuito promocional ao s2.1-pro. Rascunhos, amostras e execuções de validação a $0 durante a janela promocional apenas. De acordo com o anúncio da fish.audio: gratuito até 31 de agosto de 2026, sujeito a Uso Justo, sem garantia de SLA/latência, as solicitações podem ser retidas e o uso comercial é restrito. Nunca roteie narração de produção ou de cliente por ele.s2-pro— primeira geração S2. Alta qualidade estável com suporte a tags de emoção.s1— carro-chefe anterior. Mantido para compatibilidade com integrações existentes.
O faturamento é por byte UTF-8 do texto de entrada (não por caractere). Texto CJK e emoji custam 3-4x mais que um caractere ASCII do mesmo comprimento visível. Preço atual da lista: s1 / s2-pro / s2.1-pro = $15 por 1M bytes, s2.1-pro-free = $0 apenas durante a janela promocional (a ferramenta estimate_cost() muda para a taxa paga s2.1-pro após 31 de agosto de 2026). Verifique os preços atuais em https://docs.fish.audio/developer-guide/models-pricing/pricing-and-rate-limits antes de grandes lotes.
Tags de emoção inline (apenas modelos S2)
s2-pro / s2.1-pro / s2.1-pro-free interpretam tags de emoção inline incorporadas no texto:
- Tags como
[laugh],[whispers]alteram a entrega no meio da frase. - Exemplo:
"Isso é hilário [laugh] mas deixe-me explicar seriamente." s1não interpreta tags de emoção — elas podem ser lidas como texto simples, então remova-as ao usar s1.
Seleção de voz (reference_id)
- Crie ou escolha uma voz no playground fish.audio e copie o ID do modelo.
- Passe-o como
reference_id. Ovoice_idgenérico do seletor é aceito como alias quandoreference_idestá ausente. - Sem um
reference_id, fish.audio usa sua voz padrão para o modelo escolhido.
Clonagem inline instantânea (enviar áudio de referência + texto por solicitação) não é suportada por esta ferramenta — crie um modelo de voz no playground primeiro.
Uso no OpenMontage
Gere com o seletor TTS:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "fish_audio",
"text": "Veja por que os juros compostos superam silenciosamente todo esquema de enriquecimento rápido.",
"model": "s1",
"reference_id": "<ID do modelo de voz do playground>",
"output_path": "projects/my-video/assets/audio/narration.mp3",
})
Ou chame o provedor diretamente:
from tools.audio.fish_audio_tts import FishAudioTTS
result = FishAudioTTS().execute({
"text": "Linha de amostra curta para aprovação.",
"model": "s1",
"reference_id": "<ID do modelo de voz do playground>",
"output_path": "projects/my-video/assets/audio/fish_sample.mp3",
})
O provedor escreve o áudio em output_path e retorna data.output mais os valores resolvidos de model e reference_id.
Ajuste de qualidade e latência
latency:normal(padrão, melhor qualidade),balanced(um pouco mais rápido) oulow(mais rápido, leve perda de qualidade).normalize: padrãotrue; mantenha ativado para que números, datas e moedas sejam lidos naturalmente.prosody: opcional{ "speed": 1.0, "volume": 0 }para ajustar velocidade/volume.mp3_bitrate:128é um bom padrão; aumente para192em mixes com muita base musical.temperature: padrão0.7. Aumente para0.9para leituras mais expressivas (recomendado ao usar tags de emoção); diminua para uma entrega mais estável e previsível.top_p/repetition_penalty: geralmente mantenha os padrões (0.7/1.2).
Fluxo de Trabalho Recomendado
- Gere uma amostra de 10 a 15 segundos com o
model+reference_idescolhidos antes de uma narração paga completa. - Peça ao usuário para aprovar a naturalidade da voz, emoção e ritmo.
- Gere a narração completa somente após a aprovação.
- Para variantes em lote/localização onde o custo importa, prototipe no
s2.1-pro-free(janela promocional $0; apenas rascunhos não comerciais) e atualize o final paras2.1-pro.
Solução de Problemas
401 Unauthorized: chaveFISH_AUDIO_API_KEYincorreta ou faltando.402/ erros de pagamento: crédito da conta esgotado.404/ voz inválida: oreference_idestá errado ou não pertence a esta conta.- Áudio vazio/curto: verifique se
textnão está vazio enormalizenão está removendo toda a entrada.
Segurança
Nunca imprima ou escreva a chave da API em logs, metadados, patches ou artefatos do projeto. O .env.example deve conter apenas nomes de variáveis vazios.