fish.audio TTS
Requiere FISH_AUDIO_API_KEY en .env (crea una en https://fish.audio/go-api/api-keys/).
Crea modelos de voz en el playground de fish.audio y pasa su id como reference_id para reutilizar una voz clonada.
API actual
Llamada síncrona única que devuelve bytes de audio sin procesar:
POST https://api.fish.audio/v1/tts
Authorization: Bearer ${FISH_AUDIO_API_KEY}
Content-Type: application/json
model: <modelo backend> # Cabecera HTTP que selecciona el backend, p. ej. s1
El modelo backend se elige mediante la cabecera HTTP model, no un campo del cuerpo. En OpenMontage esto se asigna al parámetro model de la herramienta.
Modelos backend
model es obligatorio — no hay valor predeterminado. Usa uno de:
s2.1-pro— última generación. Mejor calidad: etiquetas de emoción en línea, 80+ idiomas, varios hablantes. Narración principal.s2.1-pro-free— acceso promocional gratuito a s2.1-pro. Borradores, muestras y ejecuciones de validación a $0 solo durante la ventana promocional. Según el anuncio de fish.audio: gratis hasta el 31 de agosto de 2026, sujeto a Uso Justo, sin garantía de SLA/latencia, las solicitudes pueden retenerse y el uso comercial está restringido. Nunca enrutes narraciones de producción o de clientes a través de él.s2-pro— primera generación S2. Alta calidad estable con soporte de etiquetas de emoción.s1— buque insignia anterior. Mantenido por compatibilidad con integraciones existentes.
La facturación es por byte UTF-8 del texto de entrada (no por carácter). El texto CJK y los emojis cuestan 3-4 veces más que un carácter ASCII de la misma longitud visible. Precios de lista actuales: s1 / s2-pro / s2.1-pro = $15 por 1M de bytes, s2.1-pro-free = $0 solo durante la ventana promocional (el estimate_cost() de la herramienta cambia a la tarifa paga de s2.1-pro después del 31 de agosto de 2026). Verifica los precios actuales en https://docs.fish.audio/developer-guide/models-pricing/pricing-and-rate-limits antes de lotes grandes.
Etiquetas de emoción en línea (solo modelos S2)
s2-pro / s2.1-pro / s2.1-pro-free interpretan etiquetas de emoción en línea incrustadas en el texto:
- Etiquetas como
[laugh],[whispers]cambian la entrega en medio de la oración. - Ejemplo:
"That's hilarious [laugh] but let me explain seriously." s1no interpreta etiquetas de emoción; pueden leerse como texto plano, así que elimínalas al apuntar a s1.
Selección de voz (reference_id)
- Crea o elige una voz en el playground de fish.audio, luego copia su id de modelo.
- Pásalo como
reference_id. Elvoice_idgenérico del selector se acepta como alias cuandoreference_idestá ausente. - Sin un
reference_id, fish.audio usa su voz predeterminada para el modelo elegido.
La clonación instantánea en línea (subir audio de referencia + texto por solicitud) no es compatible con esta herramienta: crea primero un modelo de voz en el playground.
Uso en OpenMontage
Genera con el selector TTS:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "fish_audio",
"text": "Here's why compound interest quietly beats every get-rich-quick scheme.",
"model": "s1",
"reference_id": "<id del modelo de voz del playground>",
"output_path": "projects/my-video/assets/audio/narration.mp3",
})
O llama al proveedor directamente:
from tools.audio.fish_audio_tts import FishAudioTTS
result = FishAudioTTS().execute({
"text": "Short sample line for approval.",
"model": "s1",
"reference_id": "<id del modelo de voz del playground>",
"output_path": "projects/my-video/assets/audio/fish_sample.mp3",
})
El proveedor escribe el audio en output_path y devuelve data.output junto con los valores model y reference_id resueltos.
Ajuste de calidad y latencia
latency:normal(predeterminado, mejor calidad),balanced(un poco más rápido) olow(más rápido, ligera pérdida de calidad).normalize: predeterminadotrue; mantenlo activado para que números, fechas y monedas se lean de forma natural.prosody: opcional{ "speed": 1.0, "volume": 0 }para ajustar ritmo/volumen.mp3_bitrate:128es un buen valor predeterminado; súbelo a192para mezclas con mucha música de fondo.temperature: predeterminado0.7. Aumenta hacia0.9para lecturas más expresivas (recomendado al usar etiquetas de emoción); reduce para una entrega más estable y predecible.top_p/repetition_penalty: normalmente déjalos en los valores predeterminados (0.7/1.2).
Flujo de trabajo recomendado
- Genera una muestra de 10 a 15 segundos con el
model+reference_idelegidos antes de una narración paga completa. - Solicita la aprobación del usuario sobre naturalidad, emoción y ritmo de la voz.
- Genera la narración completa solo después de la aprobación.
- Para variantes por lotes/localización donde el costo importa, prototipa con
s2.1-pro-free(ventana promocional $0; solo borradores no comerciales) y actualiza la final as2.1-pro.
Solución de problemas
401 Unauthorized:FISH_AUDIO_API_KEYincorrecta o faltante.402/ errores de pago: crédito de la cuenta agotado.404/ voz incorrecta: elreference_ides incorrecto o no pertenece a esta cuenta.- Audio vacío/corto: verifica que
textno esté vacío y quenormalizeno esté eliminando toda la entrada.
Seguridad
Nunca imprimas ni escribas la clave de API en registros, metadatos, parches o artefactos del proyecto. .env.example debe contener solo nombres de variables vacíos.