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.mp3Python (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 | |
|---|---|
aria | femenino |
nova | femenino |
luna | femenino |
sage | femenino |
felix | masculino |
milo | masculino |
atlas | masculino |
orion | masculino |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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
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
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
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.

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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- OpenAI API reference: create speech
- Python documentation
- curl documentation
- LibriVox public-domain audiobooks
- Creative Commons Attribution 4.0
- IETF RFC 7845: Ogg Opus
- openai-python on GitHub
- W3C WAI: making audio and video accessible
- Node.js documentation
- LibriTTS-R corpus (OpenSLR 141)
- TRON developer hub: TRC-20
