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

Por Equipo editorial VozTexto · Actualizado 2026-11-18

Esta documentación técnica explica cómo integrar la API de texto a voz de VozTexto en tus proyectos. Describe el endpoint principal, los parámetros de solicitud y los formatos de audio disponibles. Incluye ejemplos con cURL y el SDK de OpenAI para que puedas generar audio directamente desde tu código.

Está pensada para freelancers que integran audio en sitios WordPress o blogs sin depender de servicios grandes. Aquí encontrarás la información necesaria para configurar la autenticación, manejar límites de velocidad y procesar errores. Todo está basado en hechos concretos para que puedas implementar la solución con precisión.

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

Preguntas frecuentes

¿Qué es la base_url en la API?

La base_url es https://api.getv777.com/v1. Es el prefijo que usan las solicitudes HTTP para llegar al endpoint correcto. Al configurarla, las librerías SDK reconocen la ruta base y permiten enviar peticiones POST a /v1/audio/speech sin modificar manualmente la URL completa en cada llamada.

¿Cómo se autentican las solicitudes?

Se utiliza un encabezado Authorization con el valor Bearer seguido de tu clave única. El formato es: Authorization: Bearer tts-tu_clave_aqui. Esta clave se genera en tu panel de cuenta y es la única activa; si emites una nueva, la anterior deja de funcionar inmediatamente.

¿Qué formatos de audio son los mejores?

El formato óptimo depende de tu caso de uso. MP3 es ideal para blogs por su equilibrio entre calidad y tamaño. WAV y FLAC ofrecen mayor fidelidad sin pérdida. OPUS es eficiente para ancho de banda. PCM es sin comprimir. Selecciona según la compatibilidad de tu reproductor y la calidad deseada.

¿Cuántas solicitudes puedo hacer por minuto?

El límite es de 60 solicitudes por minuto por clave. Antes de tu primera recarga, el límite es de 10 solicitudes por minuto. Si excedes el límite, las solicitudes adicionales pueden tardar más o fallar. Monitorea tu uso en el panel para ajustar la velocidad de generación según tus necesidades.

¿Qué pasa si el texto excede 4096 caracteres?

La API limita cada solicitud a 4096 caracteres. Debes dividir el texto en partes de este tamaño, enviar cada parte individualmente y luego unir los archivos de audio resultantes. Esto asegura que cada fragmento se procese correctamente dentro de los límites permitidos por el endpoint de síntesis de voz.

¿Se puede ajustar la velocidad de voz?

Sí, el parámetro speed acepta valores entre 0.25 y 4.0. El valor 1.0 es la velocidad normal. Puedes aumentar la velocidad para narraciones rápidas o reducirla para una lectura más pausada. Ajustar la velocidad no afecta el precio ni la calidad de la voz generada.

¿Cómo se usa el SDK de OpenAI con esta API?

Usa el SDK de OpenAI cambiando la base_url a https://api.getv777.com/v1. Configura la clave API de VozTexto en el cliente. Las solicitudes siguen la misma estructura que el endpoint de speech de OpenAI, lo que facilita la integración sin necesidad de aprender una nueva sintaxis de API.

¿Qué modelos de voz están disponibles?

Los modelos disponibles son tts-1 y tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La diferencia principal es el precio, siendo tts-1-hd de mayor costo. Puedes elegir el modelo según tus necesidades de calidad y costo en cada solicitud.

¿Hay límites de caracteres totales?

No hay un límite total acumulado de caracteres. El límite es por solicitud, máximo 4096 caracteres. Puedes generar tantas solicitudes como necesites según tu saldo. Los caracteres se facturan por uso real, con un costo de $0.01 por cada 1000 caracteres procesados con éxito.

¿Qué formato es mejor para blogs?

MP3 es el formato recomendado para blogs. Ofrece una buena relación entre calidad de audio y tamaño de archivo, lo que facilita la carga rápida en las páginas web. Es ampliamente compatible con la mayoría de los reproductores de audio integrados en plataformas de blogging y sitios WordPress.

¿Cómo se manejan los errores de red?

Si la síntesis falla, la carga se devuelve íntegramente. No se te cobra por las solicitudes fallidas. Asegúrate de implementar lógica de reintento en tu código para manejar errores temporales. Los errores de red no consumen saldo, pero los errores de validación de parámetros tampoco lo hacen.

¿Se puede usar Python para la integración?

Sí, puedes usar Python con el SDK de OpenAI o solicitudes HTTP directas. Configura la base_url y la clave de autenticación. El SDK de OpenAI para Python funciona perfectamente cambiando la URL base. También puedes usar bibliotecas como requests para enviar peticiones POST manualmente a la API.

¿Qué es el endpoint /v1/voices?

El endpoint GET /v1/voices devuelve la lista de voces disponibles, sus idiomas, formatos soportados y precios. Puedes usarlo para obtener información dinámica sobre las 8 voces disponibles y sus características. Esto permite a tu aplicación mostrar opciones de voz al usuario antes de generar el audio.

¿Hay documentación para JavaScript?

La documentación técnica se basa en el estándar HTTP y la estructura de la API compatible con OpenAI. Puedes usar cualquier librería HTTP de JavaScript, como fetch o axios, para realizar solicitudes. No hay un SDK específico de VozTexto, pero el SDK de OpenAI funciona con la configuración adecuada.

Primera solicitud

curl

curl https://api.getv777.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.getv777.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.getv777.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

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

La API de VozTexto utiliza autenticación basada en tokens Bearer. Debes incluir tu clave API en el encabezado Authorization de cada solicitud HTTP para validar tu identidad y aplicar los límites de uso asociados a tu cuenta.

La clave se genera y gestiona desde tu panel en /get-api-key/, donde también puedes visualizar tu saldo, el saldo de prueba y los caracteres restantes.

Uso de clave Bearer

Uso de clave Bearer

Incluye el encabezado Authorization: Bearer tts-... en todas las peticiones al endpoint principal. Esta clave única identifica tu cuenta y permite el cobro preciso por caracteres generados.

  • Formato: Authorization: Bearer tts-tu-clave-aqui
  • La clave debe enviarse en cada solicitud POST o GET.

Generación de nueva clave

Generación de nueva clave

Puedes emitir una nueva clave desde la sección de configuración de tu cuenta en cualquier momento. Esto es útil si compartiste la clave con algún servicio o si sospechas su exposición.

Invalidación inmediata de clave anterior

Al generar una nueva clave, la anterior deja de ser válida al instante. No hay período de gracia; las solicitudes que utilicen la clave vieja recibirán un error de autenticación inmediatamente.

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

El endpoint principal es POST https://api.getv777.com/v1/audio/speech. Envías texto y recibes un archivo de audio. El cuerpo de la solicitud debe ser JSON con los parámetros necesarios para la síntesis.

La API sigue el mismo esquema de solicitud que la interfaz de speech de OpenAI. Esto permite usar SDKs existentes cambiando solo la base_url.

POST /v1/audio/speech

Realiza una solicitud HTTP POST al endpoint. El servidor procesa el texto y devuelve el audio generado en el cuerpo de la respuesta.

Cuerpo JSON estándar

El cuerpo debe contener los campos model, input, voice y response_format. El campo language es opcional.

  • model: "tts-1" o "tts-1-hd".
  • input: Texto a convertir (máx. 4096 caracteres).
  • voice: Identificador de la voz preset.
  • response_format: "mp3", "wav", "opus", "flac" o "pcm".

Parámetros obligatorios

Debes especificar el modelo de TTS, el texto de entrada, la voz deseada y el formato de salida. El campo speed es opcional por defecto a 1.0.

Ejemplo con cURL

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

Este ejemplo muestra una solicitud básica para generar audio. Se utiliza cURL para enviar texto plano al endpoint principal y obtener el archivo de audio resultante.

La respuesta contiene el audio binario listo para guardar o reproducir. Los caracteres se cuentan incluyendo espacios y puntuación.

Comando de terminal

Ejecuta este comando en tu terminal, reemplazando TU_CLAVE con tu clave API real.

  • curl -X POST https://api.getv777.com/v1/audio/speech \
  • -H "Authorization: Bearer TU_CLAVE" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hola mundo", "voice": "nova", "response_format": "mp3"}'

Cuerpo de solicitud

El cuerpo JSON debe incluir model ("tts-1" o "tts-1-hd"), input (texto de hasta 4096 caracteres), voice y response_format. El campo language es opcional; si no se establece, se intenta adivinar por el script (el texto en latín por defecto es inglés).

Respuesta de audio

La respuesta es el archivo de audio binario en el formato solicitado (mp3, wav, opus, flac o pcm). Si la síntesis falla, se devuelve un código de error HTTP y no se cobra el crédito.

SDK de OpenAI

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

La API de VozTexto es compatible con los SDKs oficiales de OpenAI. Solo necesitas ajustar la URL base para apuntar al endpoint de VozTexto en lugar del servicio original de OpenAI.

Cambio de base_url

Configura la variable de entorno o el parámetro de inicialización del cliente para usar https://api.getv777.com/v1 como base URL. Esto permite reutilizar la misma lógica de llamada sin modificar la estructura del cuerpo de la solicitud.

Uso de cliente Python

Inicializa el cliente de OpenAI en Python, proporcionando tu clave API y la nueva URL base. El método audio.speech() funciona directamente con esta configuración, enviando el texto y las opciones de voz al servicio de VozTexto.

  • Requiere instalar el paquete openai.

Compatibilidad de métodos

Los métodos estándar de generación de audio son completamente compatibles. El cuerpo JSON enviado mantiene la misma estructura que la API de OpenAI, incluyendo parámetros como model, input, voice y response_format.

Formatos de audio

Ilustración de onda de sonido para: Formatos de audio

El campo response_format determina el contenedor del archivo de audio devuelto por la API. Se pueden seleccionar MP3, WAV, OPUS, FLAC o PCM según la necesidad de latencia o calidad del proyecto.

MP3 para web

El formato MP3 es la opción estándar para la mayoría de los sitios web y blogs de WordPress. Ofrece una buena relación entre calidad y tamaño de archivo, garantizando una carga rápida en navegadores modernos sin requerir codecs adicionales.

WAV para alta calidad

WAV proporciona audio sin pérdida de compresión, ideal para proyectos que requieren la máxima fidelidad sonora o para procesamiento posterior en software de edición. El archivo resultante es significativamente más grande que el MP3, lo que debe considerarse para el ancho de banda.

OPUS y FLAC disponibles

OPUS ofrece una compresión eficiente con buena calidad, útil para aplicaciones con restricciones de ancho de banda. FLAC es una opción sin pérdida para archivado. Ambos formatos son válidos en el parámetro response_format para casos de uso específicos.

Formatos de audio

Límites y velocidad

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

La velocidad de generación es aproximadamente tiempo real en textos largos (25 caracteres por segundo). Las frases cortas pueden tardar unos segundos en procesarse.

60 solicitudes por minuto

El límite estándar es de 60 solicitudes por minuto por clave. Antes de la primera recarga, este límite es de 10 solicitudes por minuto.

Límite de 4096 caracteres

Cada solicitud de POST acepta hasta 4096 caracteres. El cuerpo JSON debe incluir el texto completo dentro de este límite.

Cola de procesamiento

Las solicitudes se procesan en orden. Bajo carga alta, una petición puede esperar en cola antes de iniciarse.

Para textos más largos que el límite, se dividen en partes; el cliente debe unir los archivos de audio resultantes.

Manejo de errores

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

La API devuelve códigos HTTP estandarizados para indicar el estado de la síntesis. Un 200 indica éxito y entrega el archivo de audio. Los códigos 4xx señalan errores de cliente, como una clave inválida o un cuerpo JSON mal formado.

Los errores 5xx son transitorios y pueden deberse a carga alta en el servidor.

Códigos de estado HTTP

Utiliza el código de estado HTTP para determinar si la solicitud fue procesada correctamente. Un 200 OK incluye el archivo de audio en el cuerpo de la respuesta. Un 400 Bad Request indica que los parámetros enviados no son válidos. Un 401 Unauthorized significa que la clave Bearer es incorrecta o ha sido revocada.

Los errores 429 Too Many Requests aparecen si superas los 60 solicitudes por minuto. Los errores 503 Service Unavailable indican que el servicio está temporalmente saturado.

  • 200 OK: Éxito, audio entregado
  • 400 Bad Request: Parámetros inválidos
  • 401 Unauthorized: Clave incorrecta
  • 429 Too Many Requests: Límite de velocidad excedido
  • 503 Service Unavailable: Servicio saturado

Mensajes de error comunes

Los errores de validación incluyen un campo message que describe el problema específico. Por ejemplo, si excedes los 4096 caracteres, recibirás un error indicando el límite excedido. Si la voz no existe, el error especifica la voz inválida.

No se incluye información detallada de depuración en producción para mantener la simplicidad. Revisa el cuerpo de la respuesta JSON para obtener el código de error y la descripción clara.

  • Input too long: Excede 4096 caracteres
  • Invalid voice: Voz no encontrada
  • Invalid model: Modelo no soportado
  • Rate limit exceeded: Demasiadas peticiones

Reintento de solicitudes fallidas

Implementa un reintento con backoff exponencial para los errores 503 o 429. Los errores 400 no deben reintentarse automáticamente porque no cambiarán con el tiempo. Los errores 401 requieren verificar la validez de la clave antes de reintentar.

Si la síntesis falla, el cargo se devuelve automáticamente. No se cobra por las solicitudes que no completan la generación. Asegúrate de manejar los errores de red en tu aplicación para evitar pérdidas de audio.

  • Reintenta solo 5xx y 429
  • No reintentes 400 automáticamente
  • Verifica la clave en 401
  • Los fallos son gratuitos

Endpoints adicionales

Ilustración de onda de sonido para: Endpoints adicionales

Además del endpoint principal de síntesis, la API ofrece dos rutas informativas para gestionar recursos sin generar audio. Estas rutas permiten inspeccionar la disponibilidad de voces y verificar la configuración de los modelos disponibles en el sistema.

GET /v1/voices

Devuelve la lista completa de 8 voces disponibles, sus lenguajes soportados y formatos de audio. Útil para validar antes de enviar solicitudes.

  • Lista de voces con metadatos
  • Lenguajes soportados por voz
  • Formatos de audio disponibles

GET /v1/models

Enumera los modelos activos actualmente en la plataforma. Permite verificar la disponibilidad técnica antes de integrar en producción.

  • Modelos activos
  • Estado del servicio

Información de modelos tts-1

El modelo tts-1 es el motor base. Ofrece la misma calidad que tts-1-hd y tiene el mismo costo. Ambos comparten la misma infraestructura y velocidad de procesamiento.

  • Motor base
  • Costo estándar

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Esto evita bloquear el hilo principal y permite que el contenido principal sea visible inmediatamente.

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. OpenAI API reference: create speech
  3. Python documentation
  4. curl documentation
  5. LibriVox public-domain audiobooks
  6. Creative Commons Attribution 4.0
  7. IETF RFC 7845: Ogg Opus
  8. openai-python on GitHub
  9. W3C WAI: making audio and video accessible
  10. Node.js documentation
  11. LibriTTS-R corpus (OpenSLR 141)
  12. TRON developer hub: TRC-20

Más en este sitio