Documentación técnica de la API de texto a voz para medicina

Por Equipo editorial de GuiaSonoro · Actualizado 2026-11-19

Esta documentación técnica está diseñada para equipos de producto en el sector salud que integran narración automática en sus aplicaciones. Aquí encontrarás los detalles precisos para conectar tu software con la API de GuiaSonoro, desde la autenticación hasta el manejo de guías clínicas y manuales de pacientes, asegurando una implementación fiable sin depender de plataformas genéricas.

Exploraremos el endpoint principal compatible con el formato de OpenAI, los parámetros de las voces y los límites de uso específicos para documentos médicos. También aprenderás a gestionar textos largos dividiéndolos en fragmentos de hasta 4096 caracteres y a interpretar los códigos de error, optimizando el flujo de trabajo de tu equipo para auditar o leer documentación sin complicaciones técnicas.

Documentación técnica de la API de texto a voz para medicina

Preguntas frecuentes

¿Qué es el endpoint principal?

El endpoint principal es POST https://api.scorecrazy.info/v1/audio/speech. Envías un cuerpo JSON con el texto y la configuración de voz, y recibes un archivo de audio. Es compatible con la estructura de la API de OpenAI, lo que facilita la integración en tus aplicaciones de salud sin necesidad de adaptar librerías complejas.

¿Cómo se autentica la API?

Se autentica mediante un token Bearer en el encabezado Authorization. Debes incluir tu clave API (formato tts-...) en cada solicitud. Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente. Esto asegura que solo tu equipo pueda acceder a los recursos de síntesis de voz.

¿Se puede usar el SDK de OpenAI?

Sí, los SDK oficiales de OpenAI funcionan cambiando la base_url a https://api.scorecrazy.info/v1 y usando tu clave API. No ofrecemos un SDK propio, pero esta compatibilidad permite reutilizar el código existente. Solo necesitas ajustar la configuración de conexión para apuntar a nuestra infraestructura de síntesis de voz.

¿Cuántas solicitudes se permiten por minuto?

El límite es de 60 solicitudes por minuto por clave API. Antes de la primera recarga, el límite es de 10 por minuto. Si excedes este límite, recibirás un error 429.

¿Qué formatos de audio se soportan?

Soportamos mp3, wav, opus, flac y pcm. Puedes especificar el formato deseado en el campo response_format de la petición. Estos formatos cubren necesidades desde reproducción web hasta edición profesional, permitiendo integrar la voz generada en diferentes plataformas de visualización de información médica para pacientes.

¿Cuál es el límite de caracteres por petición?

Cada solicitud puede contener hasta 4096 caracteres. Si tu texto supera este límite, debes dividirlo en partes y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Este límite asegura un procesamiento eficiente y consistente para cada fragmento de texto enviado a la API.

¿Qué significa el error 429?

El error 429 indica que has excedido el límite de 60 solicitudes por minuto. Debes esperar a que el contador se reinicie o reducir la frecuencia de tus llamadas. Este límite se aplica por clave API. No se requiere intervención técnica adicional, solo ajustar la velocidad de procesamiento de tus guías.

¿Se puede cambiar la velocidad de voz?

Sí, puedes ajustar la velocidad entre 0.25 y 4.0 mediante el campo speed. Esto permite adaptar la narración a diferentes contextos clínicos, desde explicaciones detalladas hasta resúmenes rápidos. La voz generada mantendrá su tono y claridad independientemente de la velocidad seleccionada, asegurando la comprensión del paciente.

¿Cómo se manejan los textos largos?

Debes dividir el texto en partes de hasta 4096 caracteres y unir los archivos de audio resultantes. Las solicitudes se procesan en secuencia, por lo que bajo carga podría haber una cola. Para manuales clínicos extensos, esto garantiza que cada sección se sintetice correctamente sin perder coherencia narrativa.

¿Hay límite de tamaño de archivo?

Para textos más largos, se generan múltiples archivos que debes unir. El tiempo de generación es aproximadamente en tiempo real, facilitando la gestión.

¿Se requiere SSML para voces médicas?

No, no soportamos SSML ni diccionarios de fonemas personalizados. La API utiliza 8 voces predefinidas optimizadas para claridad. Para términos médicos específicos, puedes ajustar la ortografía del texto input. Esto simplifica la integración, ya que no necesitas aprender una sintaxis adicional para obtener una narración precisa y natural.

¿Cómo se detecta el idioma automáticamente?

Si no especificas el idioma, el sistema lo adivina según el script. El texto en latín por defecto se interpreta como inglés. Para textos en español o otros idiomas con script latino, es recomendable establecer el campo language explícitamente para evitar errores de pronunciación en términos clínicos o nombres propios.

¿Se puede especificar el idioma en la petición?

Sí, puedes usar el campo language con un código ISO para forzar un idioma específico. Esto es crucial para textos en español, francés o alemán que usan caracteres latinos, evitando que se lean como inglés. Soportamos 23 idiomas, asegurando que las guías de pacientes se entiendan correctamente en su región.

¿Qué modelo usar para mayor calidad?

Usa tts-1-hd para mayor calidad. Ambos modelos (tts-1 y tts-1-hd) usan el mismo motor y tienen el mismo precio. La diferencia es la fidelidad del audio. Para documentación médica donde la precisión es crítica, tts-1-hd ofrece una claridad superior, aunque la diferencia puede ser sutil en contextos de lectura rápida.

Primera solicitud

curl

curl https://api.scorecrazy.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.scorecrazy.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.scorecrazy.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemenino
novafemenino
lunafemenino
sagefemenino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Autenticación

Ilustración de onda de sonido para: Autenticación

La API requiere autenticación mediante un token Bearer en el encabezado Authorization: Bearer <tu-clave>. Cada cuenta tiene una única clave activa. La credencial se genera al registrarse en /get-api-key/ y se muestra junto al saldo y el historial de uso.

Uso de clave Bearer

Uso de clave Bearer

Incluye la cabecera en cada petición HTTP. La clave valida tu identidad y descuenta el saldo según los caracteres procesados. Si la clave es incorrecta o ha expirado, la API devuelve un error 401.

  • Formato: Authorization: Bearer tts-xxxxxxxxxxxxxxxxxxxxxxxx
  • Ejemplo: curl -H "Authorization: Bearer tts-abc123" ...

Emisión de nueva clave

Emisión de nueva clave

Puedes generar una nueva clave en cualquier momento desde el panel de control. Esto es útil si sospechas que la clave fue expuesta o quieres rotarla periódicamente por seguridad en tus aplicaciones de salud.

Invalidación inmediata

Al emitir una nueva clave, la anterior deja de funcionar inmediatamente. No hay período de transición. Asegúrate de actualizar la variable de entorno en tus servicios antes o simultáneamente para evitar interrupciones en la síntesis de audio.

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

El endpoint principal /v1/audio/speech procesa la síntesis de voz mediante una solicitud HTTP POST. El cuerpo de la petición debe ser un objeto JSON que contenga el texto a convertir, el modelo de voz seleccionado y el formato de salida deseado.

La API devuelve el archivo de audio binario directamente en la respuesta. Este diseño estándar permite que los equipos de producto en salud integren la narración automática en sus flujos de trabajo clínicos sin necesidad de adaptaciones complejas.

Método POST /v1/audio/speech

Envía texto plano a este endpoint para recibir audio sintetizado. La solicitud debe incluir la cabecera Authorization: Bearer con tu clave única y el cuerpo JSON con los parámetros de generación.

  • URL: https://api.scorecrazy.info/v1/audio/speech
  • Método: POST
  • Formato de entrada: JSON
  • Formato de salida: Audio binario (mp3, wav, opus, flac, pcm)

Cuerpo JSON estándar

El cuerpo de la petición requiere los campos model, input y voice. El campo input acepta hasta 4096 caracteres por solicitud. Los campos response_format y speed son opcionales pero recomendados para control preciso del resultado.

  • model: "tts-1" o "tts-1-hd"
  • input: Texto a sintetizar (máx. 4096 caracteres)
  • voice: Una de las 8 voces disponibles
  • response_format: mp3, wav, opus, flac o pcm
  • speed: Flotante entre 0.25 y 4.0
  • language: Código ISO opcional

Compatibilidad con OpenAI

La estructura de la petición es idéntica a la de OpenAI. Puedes reutilizar tus scripts actuales simplemente cambiando la base_url a https://api.scorecrazy.info/v1 y actualizando la clave de API. Las SDKs oficiales de OpenAI funcionan cambiando la base_url a https://api.scorecrazy.info/v1.

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

La integración más directa mediante la terminal permite verificar la sintaxis y la respuesta de audio en segundos. Este método es ideal para pruebas rápidas antes de implementar la lógica en el código de la aplicación clínica.

El comando cURL envía el texto en formato JSON y recibe el audio binario o la estructura de error correspondiente, facilitando la depuración inmediata de los parámetros de voz y velocidad.

Comando completo

Utilice la siguiente solicitud para generar audio con la voz "nova" en formato mp3. Asegúrese de reemplazar YOUR_API_KEY con su credencial única.

```bash curl -X POST "https://api.scorecrazy.info/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Guía de dosificación para adultos", "voice": "nova", "response_format": "mp3"}' \ -o audio_generado.mp3 ```

  • Método: POST
  • Endpoint: /v1/audio/speech
  • Formato: JSON

Variables de entorno

Para automatizar scripts en entornos de producción, almacene la clave API en una variable de entorno en lugar de hardcodearla. Esto evita exposiciones accidentales en repositorios de código.

```bash export TTS_API_KEY="tts-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" curl -X POST "https://api.scorecrazy.info/v1/audio/speech" \ -H "Authorization: Bearer $TTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Texto de prueba", "voice": "nova"}' \ -o output.mp3 ```

Descarga del archivo

La bandera -o redirige la salida binaria del audio directamente a un archivo local. Esto es más eficiente que almacenar todo el stream en memoria para guías clínicas extensas.

Si la síntesis falla, la API devuelve un código de estado HTTP diferente a 200 y no se cobra el saldo.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

La API sigue el formato de solicitud de la API de audio de OpenAI, lo que permite reutilizar las bibliotecas oficiales. Solo es necesario ajustar la URL base para apuntar a nuestro servicio.

Este enfoque simplifica la integración en tus aplicaciones de salud existentes sin necesidad de aprender un nuevo protocolo o SDK propietario.

Cambio de base_url

Configura la URL base de tu cliente SDK para apuntar a https://api.scorecrazy.info/v1. Esto redirige todas las solicitudes al endpoint correcto de GuiaSonoro mientras mantienes la estructura de la API de OpenAI.

Este ajuste es suficiente para que cualquier cliente compatible con OpenAI funcione correctamente con nuestro servicio de síntesis de voz.

Instalación del paquete

Instala la biblioteca oficial de OpenAI utilizando pip. Este paquete contiene las clases necesarias para interactuar con el endpoint de audio.

La instalación es estándar y no requiere dependencias adicionales específicas de la industria médica.

  • pip install openai

Ejemplo en Python

Utiliza la clase OpenAI pasando tu clave API y la URL base modificada. Luego, llama al método audio.speech.create con el texto y la voz deseados.

Este código genera el archivo de audio directamente, listo para ser reproducido o guardado en tu sistema de documentación.

  • from openai import OpenAI
  • client = OpenAI(
  • base_url="https://api.scorecrazy.info/v1",
  • api_key="tts-tu-clave-aqui"
  • )
  • response = client.audio.speech.create(
  • model="tts-1",
  • voice="nova",
  • input="Bienvenido a la guía del paciente."
  • )

Parámetros de la petición

Ilustración de onda de sonido para: Parámetros de la petición

La API de GuíaSonoro ofrece dos modelos de síntesis de voz diseñados para la documentación clínica y guías de pacientes. La elección del modelo afecta directamente la experiencia de escucha en la aplicación de salud integrada.

Ambos modelos operan con la misma infraestructura y precio, permitiendo intercambiarlos según la prioridad de claridad versus velocidad de procesamiento sin cambios en la lógica de la aplicación.

Modelo tts-1 y tts-1-hd

Seleccione tts-1 para una generación rápida y eficiente, ideal para narraciones largas de manuales clínicos donde el volumen de caracteres es prioritario.

Elija tts-1-hd cuando la claridad vocal sea crítica para la comprensión de instrucciones médicas complejas. La diferencia reside en la calidad del audio generado, ofreciendo mayor riqueza tonal sin afectar el precio por carácter.

Voces disponibles

La API cuenta con ocho voces predefinidas que cubren distintos registros narrativos, desde la calidez de aria hasta la neutralidad de atlas. Todas las voces pueden pronunciar los 23 idiomas soportados, incluyendo español, sin necesidad de especificar el código de idioma si el texto está en inglés.

Para textos en otros idiomas con script latino, se recomienda establecer explícitamente el parámetro language para evitar la detección automática por defecto en inglés.

  • aria: narradora cálida y clara
  • nova: voz brillante y enérgica
  • luna: suave, ideal para historias
  • sage: calma e instructiva
  • felix: enérgica, promocional
  • milo: amigable y conversacional
  • atlas: neutral, estilo noticias
  • orion: profundo, documental

Formatos de salida

El parámetro response_format permite definir cómo se entregará el audio sintetizado. Los formatos disponibles son mp3, wav, opus, flac y pcm.

Elija mp3 para eficiencia de almacenamiento o wav/flac si requiere calidad sin pérdida.

El formato PCM es útil para procesamiento inmediato sin decodificación adicional, mientras que opus ofrece una compresión eficiente con buena calidad para transmisión web.

  • mp3: estándar, compresión con pérdida
  • wav: calidad sin pérdida, mayor tamaño
  • opus: alta compresión, buen equilibrio
  • flac: sin pérdida, eficiente en tamaño
  • pcm: audio sin comprimir, crudo
Parámetros de la petición

Límites y rendimiento

Ilustración de onda de sonido para: Límites y rendimiento

Comprender los límites técnicos permite planificar la carga de guías clínicas extensas sin interrupciones inesperadas en la producción de audio.

La API está diseñada para manejar volúmenes predecibles, asegurando que las integraciones en aplicaciones de salud mantengan la estabilidad durante la generación de narraciones para manuales y documentación médica.

60 solicitudes por minuto

Cada clave de API tiene un límite de 60 solicitudes por minuto. Antes de la primera recarga, este límite se reduce a 10 solicitudes por minuto. Este control asegura que el servicio permanezca estable y predecible para equipos de producto que integren la narración automática en sus flujos de trabajo.

Si excedes este límite, la API devolverá un error 429. Para trabajos masivos, es recomendable distribuir las solicitudes o realizar recargas para aumentar la capacidad de procesamiento.

  • Límite estándar: 60 requests/min.
  • Límite inicial: 10 requests/min.
  • Contador por clave API activa.

4096 caracteres por petición

Cada solicitud puede contener hasta 4096 caracteres, incluyendo espacios y puntuación. Este límite es suficiente para la mayoría de párrafos de guías de pacientes o instrucciones clínicas.

Textos más largos deben dividirse lógicamente antes de enviar la solicitud. La API no divide automáticamente los textos, por lo que la lógica de fragmentación debe implementarse en el lado del cliente.

  • Máximo: 4096 caracteres.
  • Incluye espacios y puntuación.
  • Fragmentación manual requerida.

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. En momentos de alta demanda, las peticiones pueden esperar en una cola antes de iniciarse.

La velocidad típica es de aproximadamente 25 caracteres por segundo de audio generado. Para textos largos, esto equivale a una generación en tiempo real.

  • Procesamiento secuencial.
  • Cola bajo carga.
  • Velocidad: ~25 caracteres/seg.

Códigos de error

Ilustración de onda de sonido para: Códigos de error

La API retorna códigos de estado HTTP estándar para indicar el resultado de la síntesis. Estos códigos permiten integrar la lógica de manejo de errores directamente en tus aplicaciones de salud sin ambigüedades.

Error 401 no autorizado

Se devuelve cuando la clave API en el encabezado Authorization: Bearer es inválida o falta. Verifica que la clave enviada coincida exactamente con la mostrada en tu panel de cuenta.

  • Verifica que no haya espacios extra al final de la clave.
  • Si emitiste una nueva clave, la anterior dejó de ser válida inmediatamente.

Error 429 límite alcanzado

Indica que has excedido los 60 solicitudes por minuto permitidas por clave. Para cuentas nuevas sin top-up, el límite es de 10 solicitudes por minuto.

Espera a que el contador se reinicie o revisa tu plan de uso en el panel.

Error 500 fallo de síntesis

Se produce si la generación de audio falla internamente. En este caso, el cargo se devuelve íntegramente a tu saldo.

Reintenta la solicitud; si persiste, verifica que el texto no exceda los 4096 caracteres.

  • Verifica el formato del JSON de entrada.
  • Asegúrate de que el modelo especificado sea tts-1 o tts-1-hd.

Manejo de textos largos

Ilustración de onda de sonido para: Manejo de textos largos

La API impone un límite estricto de 4096 caracteres por solicitud, lo que requiere dividir guías clínicas extensas en fragmentos manejables. Este límite incluye espacios y puntuación, por lo que el texto médico completo debe segmentarse lógicamente antes de enviarlo.

División en fragmentos

Para procesar manuales o protocolos largos, se deben dividir los textos en bloques que no superen los 4096 caracteres. Es recomendable cortar en límites de oraciones o párrafos para mantener la coherencia narrativa de la guía de paciente.

Unión de archivos de audio

Cada fragmento generado devuelve un archivo de audio independiente. Su aplicación debe concatenar estos archivos en el orden correcto para reproducir la narración completa sin silencios artificiales entre secciones, manteniendo la continuidad de la información médica.

Gestión de caracteres restantes

El panel de control muestra el saldo de caracteres disponible para su cuenta. Al enviar múltiples fragmentos, cada uno consume caracteres de su cuota, por lo que debe monitorear el uso para evitar interrupciones en la generación de audios críticos.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Es la opción preferida para narrativas lineales donde la precisión es prioritaria.

Avatar de la voz aria
ariafemenino
Avatar de la voz nova
novafemenino
Avatar de la voz luna
lunafemenino
Avatar de la voz sage
sagefemenino
Avatar de la voz felix
felixmasculino
Avatar de la voz milo
milomasculino
Avatar de la voz atlas
atlasmasculino
Avatar de la voz orion
orionmasculino

23 idiomas

Cualquier voz puede hablar cualquiera de estos idiomas.

Fuentes y lecturas adicionales

  1. Wikipedia
  2. Node.js documentation
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. OpenAI API reference: create speech
  5. curl documentation
  6. FFmpeg documentation
  7. openai-node on GitHub
  8. IETF RFC 7845: Ogg Opus
  9. LibriTTS-R corpus (OpenSLR 141)
  10. ISO 639 language codes
  11. openai-python on GitHub
  12. Creative Commons Attribution 4.0

Más en este sitio