Cómo hacer que Claude Code (y otros agentes) hablen con Fish Audio

Todos los días usamos modelos de IA para escribir texto o generar código. Pero casi siempre el resultado se queda en la pantalla: hay que leerlo. ¿Y si tu agente pudiera avisarte con voz cuando termina una tarea, o leerte el resumen de lo que acaba de hacer?

En esta guía vamos a conectar Fish Audio con Claude Code, aunque el mismo procedimiento sirve para Codex, Cursor, OpenCode o cualquier agente que soporte el estándar de Agent Skills. Al final también vamos a construir una pequeña aplicación web de texto a voz con la misma API.

Este artículo cuenta con el patrocinio de Fish Audio. Los datos técnicos, precios y limitaciones que aparecen aquí están verificados contra su documentación oficial.

Qué es Fish Audio y para qué sirve

Fish Audio es una plataforma de texto a voz (TTS) que convierte texto escrito en audio con entonación natural. Su modelo actual, s2.1-pro, es multilingüe y está pensado para generación expresiva con baja latencia y streaming en tiempo real.

Además de TTS, la aplicación web incluye clonación de voz, transcripción (speech-to-text), cambiador de voz, generación de efectos de sonido, generación de música y separación de pistas.

Casos de uso típicos:

• Notificaciones habladas de agentes de código que corren en paralelo.
• Atención al cliente y agentes de voz.
• Narración de contenido: artículos, posts, cortes para redes.
• Videojuegos y avatares: voces de personajes.
• Doblaje y localización, manteniendo la identidad del hablante entre idiomas.

Lo que necesitas antes de empezar

Solo dos cosas:

1. Una clave de API de Fish Audio.
2. El skill oficial de Fish Audio instalado en tu agente.

Y un detalle importante que conviene aclarar desde ya, porque es el error de presupuesto más común con esta plataforma:

Los créditos del plan gratuito y el saldo de la API son cosas distintas. El plan Free da 8.000 créditos mensuales para usar la aplicación web. La API se cobra aparte, por prepago y consumo real (pay-as-you-go), sin suscripción ni mínimo mensual. Por eso, aunque tengas créditos gratis en el panel, tu primera llamada por API puede fallar hasta que recargues saldo.

Paso 1: crear tu clave de API

Si todavía no tienes cuenta, créala en Fish Audio antes de seguir: el registro es gratuito y te deja entrar directo al panel. Una vez dentro, ve a la sección de desarrollador (documentación oficial):

1. Haz clic en Crear clave de API.
2. Ponle un nombre reconocible (por ejemplo, claude-code).
3. Define una fecha de expiración, o déjala sin expiración.
4. Copia el token.

Guárdalo como variable de entorno en lugar de pegarlo en el chat de tu agente:

export FISH_API_KEY="tu_clave_aqui"

Datos canónicos de la API, útiles si vas a integrarla a mano:

La selección de modelo TTS se hace con una cabecera model opcional (s1, s2-pro, s2.1-pro, s2.1-pro-free); la recomendación es s2.1-pro para producción y s2.1-pro-free para la capa gratuita de desarrollo, y si se omite, el servidor usa s2.1-pro.

Paso 2: instalar el skill de Fish Audio

Un skill es un paquete de instrucciones que le enseña al agente cómo usar una herramienta: nombres de métodos correctos, unidades, tipos de error. Sin él, el agente tiene que investigar la documentación en internet cada vez (y muchas veces inventa métodos que no existen).

Abre una terminal nueva y ejecuta:

npx skills add https://docs.fish.audio

Esto instala dos skills: fish-audio-api (REST y WebSocket puros, para cualquier lenguaje) y fish-audio-sdk (las librerías de Python y JavaScript). Se guarda una copia canónica en .agents/skills/, con enlaces simbólicos para Claude Code y Cursor, y luego puedes ejecutar npx skills update para actualizarlos.

Opciones útiles del instalador

# Ver qué skills hay disponibles antes de instalar
npx skills add https://docs.fish.audio --list

# Instalar solo uno
npx skills add https://docs.fish.audio --skill fish-audio-api

# Apuntar a un agente específico (claude-code, cursor, codex, ...)
npx skills add https://docs.fish.audio -a claude-code

El instalador te preguntará si quieres instalarlo a nivel de proyecto o global. Instalarlo global lo deja disponible en toda la máquina; como el cuerpo de un skill solo se carga cuando se usa, tenerlo instalado globalmente no consume contexto mientras no lo llames.

Dónde quedan los skills en Claude Code

Después de instalar, reinicia Claude Code (o recarga los skills) y escribe /fish para confirmar que aparecen. Puedes ver todos los detalles en la documentación de skills de Claude Code.

Alternativa: si prefieres documentación en vivo en lugar de un skill offline, Fish Audio también publica un servidor MCP: claude mcp add --transport http fish-audio --scope project https://docs.fish.audio/mcp. El skill es más rápido y no depende de la red; el MCP siempre trae lo más reciente.

Paso 3: la primera prueba

Con el skill instalado, basta con pedirlo en lenguaje natural:

Dame una frase motivacional y léela con Fish Audio.

El agente carga el skill solo, pide la clave si no la encuentra en el entorno, genera el MP3 y lo reproduce. Si te devuelve un error de saldo, entra al panel, dale a recargar y agrega un monto pequeño (con 5 dólares te alcanza para muchísimas pruebas; más abajo verás los números).

Paso 4: crear un skill "reader" para que el agente te avise

Aquí está la parte realmente útil. En vez de pedir la lectura cada vez, creas un skill propio que el agente invoca cuando termina una tarea.

Pídeselo directamente a Claude Code:

Crea un skill llamado reader que, cada vez que lo use, tome el resultado
de la tarea, lo resuma en una o dos frases, limpie el markdown (enlaces,
tablas, bloques de código) y lo lea con Fish Audio usando ffplay.

Un SKILL.md mínimo se ve así:

name: reader
description: Resume el resultado de la tarea y lo lee en voz alta con Fish Audio. Úsalo al terminar tareas largas

# Reader

1. Resume el resultado en máximo 2 frases (menos de 200 caracteres).
2. Elimina markdown: enlaces, tablas, bloques de código, emojis.
3. Llama a POST https://api.fish.audio/v1/tts con la cabecera
   `model: s2.1-pro` y `reference_id` de la voz elegida.
4. Guarda el MP3 en /tmp y reprodúcelo con `ffplay -nodisp -autoexit`.

Ahora puedes lanzar una tarea larga en otra carpeta y seguir trabajando:

Crea una landing muy básica y avísame cuando termines. Usa el skill reader.

Esto se vuelve mucho más valioso cuando corres varios agentes en paralelo (por ejemplo con git worktrees o un multiplexor de terminales): cada instancia te avisa por voz al terminar y tú decides a cuál volver.

El truco que te ahorra dinero: resumir antes de leer

Las respuestas de un agente de código son largas. Leerlas completas es innecesario y se cobra por bytes de entrada, así que conviene que el skill resuma antes de sintetizar:

Cien notificaciones resumidas cuestan menos de 40 centavos. Cien respuestas completas cuestan unos 3 dólares. La diferencia es solo una línea en el skill.

Ojo con el detalle técnico: se factura por bytes UTF-8, no por caracteres. El español con tildes y ñ pesa un poco más que el inglés, y los idiomas con alfabetos no latinos pesan 3 o 4 bytes por carácter.

Modelos y precios reales (verificado en la documentación oficial)

Los precios de TTS se calculan sobre el tamaño del texto de entrada, medido en millones de bytes UTF-8.

Un millón de bytes UTF-8 equivale aproximadamente a 180.000 palabras en inglés, o unas 12 horas de habla.

Sí, existe una versión gratuita del mismo modelo: s2.1-pro-free es el mismo modelo a costo cero para pruebas, prototipos, desarrollo y negocios pequeños, sin garantías de tiempo hasta el primer audio ni acuerdo de procesamiento de datos. Para un skill de notificaciones personales es más que suficiente; para un producto en producción, usa s2.1-pro.

Límites de concurrencia

Los límites se basan en solicitudes concurrentes: menos de $100 pagados da 5 solicitudes simultáneas, $100 o más sube a 15, y $1.000 o más llega a 50. Los niveles se desbloquean apenas el monto prepagado alcanza el umbral, sin necesidad de gastarlo primero.

Clonar tu propia voz

Puedes crear una voz reutilizable a partir de tus propias grabaciones. Hay dos caminos:

• Modelo persistente: entrenas una vez, obtienes un id y lo reutilizas siempre. Ideal si vas a usar la misma voz de forma recurrente.
• Clon instantáneo: mandas el audio de referencia en cada generación, sin modelo que administrar. Ideal para voces de un solo uso.

Requisitos de las muestras

Las muestras pueden ser .wav, .mp3, .m4a u .opus; apunta a al menos 10 segundos por clip, y uno o dos minutos de habla limpia de un solo hablante mejora la fidelidad. Evita música de fondo, reverberación y voces superpuestas.

Desde la web es arrastrar y soltar. Desde la API:

curl --request POST https://api.fish.audio/model \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --form type=tts \
  --form title="Mi voz" \
  --form visibility=private \
  --form train_mode=fast \
  --form voices=@muestra.wav

Y luego la usas como cualquier otra voz, pasando su id como reference_id:

curl --request POST https://api.fish.audio/v1/tts \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "model: s2.1-pro" \
  --data '{ "text": "Ahora hablo con mi voz clonada.", "reference_id": "TU_VOICE_ID" }' \
  --output salida.mp3

Un par de detalles que conviene conocer:

• enhance_audio_quality viene activado por defecto y limpia ruido de fondo y normaliza niveles antes de entrenar; si tu audio ya es limpio, puedes desactivarlo.
• Los modelos son privados por defecto; puedes ponerlos en unlist para compartir por enlace, o public para publicarlos en la biblioteca de voces.
• Con train_mode="fast" (el predeterminado) la voz queda usable casi de inmediato.

Una advertencia que sí importa

La biblioteca comunitaria tiene miles de voces, y entre ellas circulan imitaciones de personas reales y personajes conocidos. Clonar la voz de alguien sin su consentimiento tiene consecuencias legales en un número creciente de jurisdicciones, y publicar esa voz agrava el problema. La propia plataforma te pide confirmar que la voz no suplanta a una persona real antes de crearla. Usa tu propia voz, o una con permiso explícito y por escrito.

Etiquetas de emoción y control fino

Esta es probablemente la característica que más diferencia a Fish Audio de un TTS genérico: puedes marcar la entonación dentro del propio texto.

Con los modelos S2 y S2.1 se usan corchetes:

[happy] ¡Qué buen día!
[whispering] No le cuentes a nadie.
[sad][sighing] Ojalá las cosas fueran distintas.

Los modelos soportan más de 64 expresiones emocionales y estilos de voz controlables mediante marcadores en el texto. Además de emociones, hay marcadores de tono ([shouting], [whispering], [soft tone], [emphasis]), efectos humanos ([laughing], [sighing], [gasping], [clear throat]) y pausas ([break], [long-break]).

Con S2 también puedes combinar hasta tres marcadores y usar descripciones libres, no solo etiquetas de una lista fija:

Qué [cálido y feliz] día tan maravilloso.
[ligeramente triste] Estoy un poco decepcionado.

Diferencia importante entre modelos: S2 y S2.1 usan corchetes [así]. El modelo legado S1 exige paréntesis (así) y un conjunto fijo de etiquetas. Si copias ejemplos viejos de internet, revisa qué sintaxis estás usando.

Reglas prácticas que recomienda la documentación: una emoción principal por oración, colocar las emociones de nivel oración al inicio, no mezclar emociones contradictorias y no abusar de etiquetas en textos cortos. Los marcadores no cuentan para los límites de tokens ni agregan latencia.

Crear tu propia app web de texto a voz

La misma API sirve para tu producto. Puedes pedirle a tu agente: "crea una web que convierta texto a voz usando Fish Audio con esta clave", y con el skill instalado va a escribir el cliente correcto a la primera.

El núcleo es una sola petición:

import { writeFile } from "fs/promises";

const res = await fetch("https://api.fish.audio/v1/tts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FISH_API_KEY}`,
    "Content-Type": "application/json",
    model: "s2.1-pro",
  },
  body: JSON.stringify({
    text: "Hola, esta es una prueba de conversión de texto a voz.",
    reference_id: "TU_VOICE_ID",
    format: "mp3",
  }),
});

if (!res.ok) {
  throw new Error(`Falló la petición TTS: ${res.status}`);
}

await writeFile("salida.mp3", Buffer.from(await res.arrayBuffer()));

Con Python y el SDK oficial:

from fishaudio import FishAudio

client = FishAudio()  # lee FISH_API_KEY del entorno

audio = client.tts.convert(
    text="Hola, esta es una prueba.",
    reference_id="TU_VOICE_ID",
)

A partir de ahí puedes agregar selector de voces (con GET /model), formato de salida, velocidad, expresividad y volumen. Y si necesitas que el audio empiece a sonar mientras el modelo todavía genera —el caso típico de un agente de voz o un chat hablado—, existe el endpoint WebSocket wss://api.fish.audio/v1/tts/live, documentado en la guía de streaming en tiempo real.

Guarda la clave en el servidor. Si la expones en el frontend, cualquiera puede consumir tu saldo prepagado. Enruta las peticiones por un endpoint propio.

Idiomas

S2.1 Pro soporta 83 idiomas, incluidos inglés, japonés, chino, coreano, español, árabe, francés, alemán, portugués y ruso, entre otros; el mismo modelo maneja todos, sin endpoints separados ni precios por idioma.

En la práctica, la calidad no es idéntica en todos. El español y el inglés se escuchan muy sólidos; idiomas con menos datos pueden sonar algo más planos. La recomendación honesta: prueba tu caso concreto con s2.1-pro-free antes de comprometer un producto.

Un matiz de la documentación que vale la pena conocer: la guía de emociones detalla el comportamiento de los marcadores a nivel de oración para 13 idiomas (inglés, chino, japonés, alemán, francés, español, coreano, árabe, ruso, neerlandés, italiano, polaco y portugués). Fuera de esos, la síntesis funciona, pero el control fino de entonación puede ser menos predecible.

Errores comunes al integrarlo

Preguntas frecuentes

¿Fish Audio es gratis? El plan Free da 8.000 créditos mensuales para la aplicación web. La API es aparte, de pago por consumo, aunque existe el modelo s2.1-pro-free a $0 bajo política de uso justo, sin garantías de latencia ni acuerdo de procesamiento de datos.

¿Funciona con Cursor, Codex y OpenCode además de Claude Code? Sí. El instalador npx skills add soporta múltiples agentes y sigue el estándar abierto de Agent Skills. Puedes apuntar a uno concreto con -a claude-code, -a cursor, -a codex, etc.

¿Cuánto audio puedo generar con un dólar? A $15 por millón de bytes UTF-8, un dólar equivale a unos 66.000 bytes de texto: aproximadamente 45 minutos de habla, o más de trescientas notificaciones resumidas.

¿Necesito suscripción para usar la API? No. La documentación oficial indica que el acceso a la API no tiene cuota de suscripción ni mínimo mensual: se paga por consumo sobre saldo prepagado.

¿Se puede clonar una voz con solo 10 segundos? Técnicamente sí, la documentación pide al menos 10 segundos por clip. Pero la fidelidad mejora bastante con uno o dos minutos de audio limpio.

¿Puedo usar las voces generadas comercialmente? Depende del plan y de la voz. El plan gratuito de la web tiene restricciones de uso comercial, y las voces de la biblioteca comunitaria tienen sus propias condiciones. Revisa los términos de la plataforma antes de publicar contenido monetizado.

Conclusión

Darle voz a un agente de código dejó de ser un proyecto: son dos pasos, una clave y un skill. Lo interesante no es la novedad de escuchar a Claude Code hablando, sino el cambio de flujo de trabajo: puedes lanzar varias tareas largas, irte a hacer otra cosa y que cada agente te llame cuando termina.

Si vas a llevarlo a producción, quédate con estas tres ideas: resume antes de sintetizar (te ahorra la mayor parte del costo), guarda la clave en el servidor, y clona solo voces que tengas derecho a usar.

Lo mejor es que la barrera para probarlo es mínima: con el modelo s2.1-pro-free puedes montar el skill de notificaciones sin gastar nada, así que vale la pena abrir una cuenta y medir en tu propio flujo si te sirve antes de pensar en presupuesto.

Si quieres profundizar en flujos con múltiples agentes, automatizaciones o infraestructura para tus propios proyectos, en fazt.dev puedes reservar asesorías personalizadas.

Recursos

• Fish Audio
• Documentación para desarrolladores
• Guía rápida para agentes de código
• Precios y límites
• Clonación de voz
• Control de emociones
• Skills en Claude Code
• Estándar Agent Skills