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

Por Equipo editorial de VozNeta · Actualizado 2026-11-18

Esta documentación describe la API REST de VozNeta, diseñada para agencias y freelancers que integran síntesis de voz en flujos de localización. Utiliza el formato estándar de OpenAI, permitiendo cambiar la base URL y aprovechar SDKs existentes sin abstracciones innecesarias.

Aquí encontrarás la guía técnica para autenticación, parámetros de voz, manejo de idiomas y límites de uso. Incluye ejemplos prácticos en Python y cURL para la generación de audio mediante el endpoint /v1/audio/speech, enfocándonos en la integración técnica directa y eficiente.

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

Preguntas frecuentes

¿Qué SDK puedo usar para integrar la API?

Puedes usar los SDK oficiales de OpenAI. La API sigue la misma forma de solicitud que el endpoint de speech de OpenAI, lo que permite una integración directa sin necesidad de adaptadores personalizados ni librerías propietas adicionales.

¿Cómo cambio la base URL para usar esta API?

Configura la propiedad base_url en tu SDK de OpenAI a https://api.playtakbet.com/v1. Utiliza tu clave API con el formato Bearer tts-... en el encabezado de autorización para autenticar tus solicitudes correctamente.

¿Cuál es el límite máximo de caracteres por solicitud?

El campo input acepta hasta 4096 caracteres por solicitud. Si tu texto excede este límite, debes dividirlo en partes más pequeñas y unir los archivos de audio resultantes para obtener el audio completo.

¿Qué formatos de audio están disponibles?

Puedes solicitar audio en los formatos mp3, wav, opus, flac o pcm. Estos formatos se especifican mediante el campo response_format en el cuerpo de la solicitud JSON enviada al endpoint de síntesis.

¿Cómo se especifica un idioma concreto?

Utiliza el campo language con el código ISO correspondiente. Si no se especifica, el sistema intenta adivinar el idioma basándose en el script, por lo que es recomendable establecerlo explícitamente para textos en latinos que no sean inglés.

¿Qué ocurre si envío un texto demasiado largo?

Debes dividir el texto en fragmentos de máximo 4096 caracteres. La API procesa cada fragmento por separado. Luego, debes unir los archivos de audio generados para obtener el resultado final coherente.

¿Se puede ajustar la velocidad de la voz?

Sí, el campo speed acepta valores entre 0.25 y 4.0. Esto permite acelerar o ralentizar la síntesis según las necesidades del proyecto de localización o doblaje sin afectar la calidad de la voz base.

¿Cuántas claves API puedo tener activas?

Solo hay una clave activa por cuenta. Si emites una nueva clave, la anterior deja de funcionar inmediatamente. Esto asegura que solo un token válido esté utilizado en tus integraciones en un momento dado.

¿Qué pasa con la clave antigua al emitir una nueva?

La clave antigua se invalida de forma instantánea al generar la nueva. Asegúrate de actualizar tu configuración antes de emitir una nueva clave para evitar interrupciones en los servicios que dependen de la autenticación.

¿Cuál es el límite de solicitudes por minuto?

El límite es de 60 solicitudes por minuto por clave API. Si tu cuenta no tiene recargas, el límite inicial es de 10 solicitudes por minuto. Estos límites ayudan a gestionar la carga del servidor.

¿Qué significa el código de error 429?

El código 429 indica que has excedido el límite de solicitudes por minuto. Debes esperar a que el contador se reinicie o reducir la frecuencia de tus peticiones para evitar interrupciones en el flujo de trabajo.

¿Se puede usar la API desde JavaScript?

Sí, es totalmente compatible con JavaScript. Puedes usar la librería oficial de OpenAI para Node.js o el navegador, modificando solo la base_url para apuntar a https://api.playtakbet.com/v1 y autenticándote con tu clave.

¿Cómo se manejan los errores de pago?

Si la síntesis falla, el cargo se devuelve íntegramente. No asumimos si el cobro es previo o posterior; el hecho garantizado es que el resultado neto es cero para las solicitudes no exitosas. Solo se factura la generación completa, eliminando la necesidad de gestionar devoluciones manuales tras un error.

¿Qué es el campo 'input' en la solicitud?

El campo input contiene el texto plano que deseas convertir a voz. Este texto debe tener una longitud máxima de 4096 caracteres y es el único contenido necesario para generar el archivo de audio solicitado.

Primera solicitud

curl

curl https://api.playtakbet.com/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.playtakbet.com/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.playtakbet.com/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 y clave API

Ilustración de onda de sonido para: Autenticación y clave API

La autenticación en VozNeta requiere una clave API válida que se obtiene en la página /get-api-key/. Al registrarte con Google, recibes un crédito de prueba de $0.50 válido por 7 días; las cuentas creadas con correo y contraseña comienzan sin este saldo inicial.

Para autenticar tus solicitudes, debes incluir la cabecera Authorization con el formato Bearer seguido de tu clave única (tts-...). Esta clave es el único medio para autorizar el uso de la API.

Obtención de clave en /get-api-key/

Obtención de clave en /get-api-key/

Accede a /get-api-key/ para registrar tu cuenta. El proceso es simple y permite obtener la credencial necesaria para empezar a generar audio inmediatamente tras la validación.

Formato de cabecera Bearer

Incluye el encabezado Authorization: Bearer tts-... en cada solicitud HTTP. Las bibliotecas oficiales de OpenAI funcionan automáticamente si configuras el base_url correctamente.

  • Formato: Authorization: Bearer <tu_clave>
  • Tipo de clave: Prefijo tts-

Gestión de claves activas

Tienes una clave activa por cuenta. Si la revocas o generas una nueva, la anterior deja de funcionar inmediatamente, garantizando seguridad sin latencia.

Revisa el estado y uso de tu clave directamente en el panel de la página /get-api-key/.

Endpoint principal de síntesis

Ilustración de onda de sonido para: Endpoint principal de síntesis

La síntesis de audio se realiza mediante una llamada HTTP POST al endpoint /v1/audio/speech. La API procesa la solicitud y devuelve el archivo de audio resultante directamente en el cuerpo de la respuesta, listo para su descarga inmediata. No se almacenan los audios generados en nuestros servidores tras la entrega.

Método POST /v1/audio/speech

Envía texto plano y recibe el archivo de audio sintético en el formato solicitado. La respuesta contiene los datos binarios del audio, listos para ser guardados en tu infraestructura o procesados en la cadena de producción de doblaje.

Cuerpo JSON estándar

El cuerpo de la solicitud debe ser un objeto JSON que sigue la misma estructura que el endpoint de speech de OpenAI. Esto permite usar los SDKs oficiales con solo ajustar la base_url.

Parámetros obligatorios y opcionales

Debes especificar el modelo, el texto de entrada (input), la voz y el formato de respuesta. La velocidad y el idioma son opcionales; si no se indica el idioma, la API lo infiere por el guión, asumiendo inglés para texto en latín.

  • model: tts-1 o tts-1-hd
  • input: texto hasta 4096 caracteres
  • voice: preset de voz (ej. aria, atlas)
  • response_format: mp3, wav, opus, flac, pcm
Endpoint principal de síntesis

Modelos de voz disponibles

Ilustración de onda de sonido para: Modelos de voz disponibles

VozNeta ofrece dos identificadores de modelo idénticos en el backend: tts-1 y tts-1-hd. Ambos activan exactamente el mismo motor de síntesis, entregando la misma calidad de audio y utilizando la misma infraestructura de procesamiento.

La distinción es puramente nominal para mantener compatibilidad con la convención de nomenclatura de la API de OpenAI. No existe diferencia perceptible en fidelidad, latencia ni características entre ambos identificadores al realizar la solicitud.

tts-1: estándar

Este modelo es el identificador estándar para la síntesis de voz. Al enviar tts-1 en el campo model, el sistema procesa la solicitud con el motor principal disponible.

Es la opción predeterminada para la mayoría de los casos de uso, incluyendo generación rápida de audios para localización y doblaje, garantizando la misma calidad que la versión "alta definición".

  • Motor de síntesis principal
  • Compatible con todos los formatos de salida
  • Velocidad de generación real-time

tts-1-hd: alta definición

El identificador tts-1-hd utiliza el mismo motor que tts-1. No ofrece mayor fidelidad ni mayor latencia; simplemente cumple con la convención de nomenclatura de la API.

Útil si tu cliente o integración espera explícitamente el sufijo "hd" para indicar calidad premium, aunque técnicamente los datos generados son idénticos en calidad de audio.

  • Mismo motor que tts-1
  • Sin latencia adicional
  • Misma calidad de audio

Mismo motor y precio

Tanto tts-1 como tts-1-hd cuestan lo mismo: $0.01 por cada 1 000 caracteres. No hay tarifa adicional por usar el modelo "hd".

Puedes alternar entre ambos identificadores según tu preferencia de codificación sin incurrir en costes extra ni esperar tiempos de procesamiento diferentes. La facturación es idéntica.

  • Precio: $0.01 / 1k caracteres
  • Mismo tiempo de procesamiento
  • Sin sobrecosto por hd

Configuración de parámetros

Ilustración de onda de sonido para: Configuración de parámetros

La configuración de parámetros permite ajustar el resultado final de la síntesis. El campo voice acepta uno de los 8 presets disponibles, seleccionando el timbre y registro adecuados para el proyecto.

El response_format define la codificación del audio generado. El formato no influye en el coste por carácter, solo en el uso de ancho de banda y almacenamiento. El precio es estrictamente por carácter.

Selección de voz (8 presets)

Selecciona una voz específica mediante el campo voice. Cada preset tiene un registro definido: femeninas (aria, nova, luna, sage) o masculinas (felix, milo, atlas, orion).

El campo language es opcional. Si no se proporciona, se infiere del script (el latín por defecto es inglés). Para textos en latín no ingleses, especifica el código ISO.

  • Aria: narradora clara y cálida
  • Luna: suave, ideal para storytelling
  • Felix: enérgico, promocional
  • Milo: amigable, conversacional
  • Atlas: neutral, informativo
  • Orion: profundo, documental

Ajuste de velocidad (0.25–4.0)

El parámetro speed ajusta la tasa de habla entre 0.25 y 4.0. El valor predeterminado es 1.0.

Velocidades superiores pueden afectar la legibilidad. Ajusta según la densidad del texto de localización para mantener la claridad.

Formato de respuesta (mp3, wav, etc.)

Elige response_format entre mp3, wav, opus, flac o pcm. El precio se mantiene fijo por carácter independientemente del formato.

Selecciona el formato que mejor se adapte a tu pipeline de postproducción sin penalización de costo adicional.

Manejo de idiomas

Ilustración de onda de sonido para: Manejo de idiomas

La API detecta el idioma automáticamente a partir del guión del texto enviado. Si no se especifica, el sistema asume inglés para cualquier texto en latín. Para textos en latín que no sean inglés, es obligatorio pasar el código ISO 2-letter en el campo language para evitar errores de síntesis.

Detección automática por guión

El motor analiza la codificación del texto para inferir el idioma. Por defecto, cualquier entrada en alfabeto latino se interpreta como inglés si no se indica lo contrario.

Forzar idioma con ISO code

Envía el código de dos letras (ej. es, fr) en el parámetro language para asegurar la pronunciación correcta en textos latinos no ingleses.

Lista de 23 idiomas soportados

Todos los modelos de voz soportan la totalidad de los 23 idiomas listados. Cualquier voz puede generar audio en cualquiera de estos idiomas.

  • Árabe
  • Chino
  • Danés
  • Holandés
  • Inglés
  • Finés
Manejo de idiomas

Límites y rendimiento

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

60 solicitudes por minuto

Límite estándar de 60 solicitudes por minuto por clave API. Para cuentas nuevas sin recargo, el límite inicial es de 10 por minuto. Al realizar el primer depósito, este límite se eleva automáticamente a 60 por minuto.

Límite de 4096 caracteres por request

Cada solicitud acepta un máximo de 4096 caracteres. Para textos más extensos, se deben dividir en fragmentos y unir los archivos de audio resultantes.

Tiempo de generación real

La generación es aproximadamente en tiempo real, procesando unos 25 caracteres por segundo. Las frases cortas pueden tardar unos segundos. Las solicitudes se procesan en cola, por lo que la latencia puede variar bajo carga.

Ejemplo de integración con SDK

Ilustración de onda de sonido para: Ejemplo de integración con SDK

La integración es directa porque la API adopta el mismo formato de solicitud que OpenAI. Solo necesitas ajustar la URL base del SDK para que apunte a nuestro endpoint sin modificar la lógica de tu código.

Esto permite reutilizar las librerías oficiales de OpenAI, eliminando la necesidad de aprender una nueva sintaxis o mantener un cliente personalizado.

Cambio de base_url en OpenAI SDK ['Configura la variable base_url para apuntar a https://api.playtakbet.com/v1. El resto de los parámetros (model, voice, input) permanecen idénticos a la implementación estándar de OpenAI.', {'h3': 'Código Python de ejemplo', 'paras': ['```python\nimport openai\n\nclient = openai.OpenAI(\n api_key="tts-tu-clave-aqui",\n base_url="https://api.playtakbet.com/v1"\n)\n\nresponse = client.audio.speech.create(\n model="tts-1",\n voice="nova",\n input="Texto a sintetizar para localización.",\n response_format="mp3"\n)\n\nwith open("output.mp3", "wb") as f:\n f.write(response.content)\n``', {'h3': 'Código cURL de ejemplo', 'paras': ['``bash\ncurl -X POST "https://api.playtakbet.com/v1/audio/speech" \\\n -H "Authorization: Bearer tts-tu-clave-aqui" \\\n -H "Content-Type: application/json" \\\n -d \'{"model": "tts-1", "voice": "nova", "input": "Texto de prueba", "response_format": "mp3"}\' \\\n -o audio.mp3\n```', 'image']}]}]

Códigos de error comunes

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

La API devuelve códigos de estado HTTP estándar junto con mensajes de error descriptivos en formato JSON para facilitar la depuración de integraciones.

Estos errores se generan en tiempo real durante el procesamiento de la solicitud o al validar los parámetros de entrada antes de la síntesis.

Error de autenticación

Se produce un 401 si la cabecera Authorization: Bearer está ausente o contiene una clave inválida. Verifica que la clave proporcionada en /get-api-key/ esté activa y no haya sido revocada tras la emisión de una nueva.

  • Código HTTP: 401 Unauthorized
  • Causa: Token ausente, expirado o incorrecto
  • Solución: Regenerar clave desde el panel

Límite de caracteres excedido

Se devuelve un 400 si el campo input supera los 4096 caracteres. La API no realiza división automática; debes fragmentar el texto en tu lado antes de enviar la solicitud POST.

  • Código HTTP: 400 Bad Request
  • Límite estricto: 4096 caracteres por request
  • Incluye espacios y puntuación en el conteo

Formato de audio no soportado

Si se solicita un formato no válido en response_format, la API rechaza la solicitud. Solo se permiten mp3, wav, opus, flac y pcm. Otros formatos generarán un error de validación inmediato.

  • Código HTTP: 400 Bad Request
  • Formatos válidos: mp3, wav, opus, flac, pcm
  • Verificar valor exacto en la cabecera

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. La voz perfecta conecta tu talento con audiencias de todo el mundo en la localización.

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. Tether (USDT)
  4. Python documentation
  5. LibriVox public-domain audiobooks
  6. openai-python on GitHub
  7. curl documentation
  8. MDN: Web Speech API
  9. OpenAI API reference: create speech
  10. W3C WAI: making audio and video accessible
  11. TRON developer hub: TRC-20
  12. Creative Commons Attribution 4.0

Más en este sitio