Documentación técnica para integrar narración en tus vídeos

Por Equipo editorial VozInmobiliaria · Actualizado 2026-11-19

Esta documentación técnica está diseñada para equipos de agencias inmobiliarias que integran narración por voz en tours virtuales y vídeos de propiedades. Aquí aprenderás a conectar nuestra API directamente a tu flujo de producción, generando audio profesional sin contratar locutores adicionales.

Obtendrás ejemplos prácticos de integración, desde la autenticación básica con claves API hasta el manejo de parámetros como velocidad y formato. La guía cubre el uso con el SDK de OpenAI, los límites de uso y los endpoints disponibles, permitiéndote escalar la generación de voz para presentaciones de viviendas de manera eficiente y predecible.

Documentación técnica para integrar narración en tus vídeos

Preguntas frecuentes

¿Qué es la cabecera Authorization Bearer?

Es el mecanismo de autenticación que debes incluir en cada solicitud HTTP. Debe contener tu clave API única con el prefijo 'Bearer', por ejemplo: 'Authorization: Bearer tts-...'. Esto permite al servidor verificar que tu cuenta tiene saldo suficiente para procesar la síntesis de voz y registrar el uso.

¿Qué formato de audio es mejor para vídeos?

Para vídeos, MP3 es la opción más equilibrada por su compatibilidad universal y tamaño de archivo reducido. Si necesitas máxima calidad, elige WAV o FLAC. MP3 y WAV son adecuados para la mayoría de plataformas de video, mientras que OPUS y PCM ofrecen otras alternativas según tu flujo de trabajo.

¿Cuántos caracteres máximos puedo enviar?

El límite es de 4096 caracteres por solicitud, incluyendo espacios y puntuación. Para textos más largos, como guiones completos de tours virtuales, debes dividir el texto en fragmentos de este tamaño y unir los archivos de audio resultantes para obtener la narración completa de la propiedad.

¿Puedo usar el SDK de OpenAI para Python?

Sí, el endpoint es compatible con el SDK oficial de OpenAI. Solo necesitas cambiar la 'base_url' a 'https://api.sv366.info/v1' y configurar tu clave API. Esto permite reutilizar tu código existente de Python sin necesidad de aprender una nueva librería o sintaxis de integración.

¿Qué significa el error 401?

Indica que la clave API proporcionada es inválida o ha sido revocada. Verifica que tu solicitud incluya la cabecera 'Authorization: Bearer' con tu clave activa. Si emitiste una nueva clave, la anterior deja de funcionar inmediatamente. Asegúrate de copiar la clave correcta desde tu panel de cuenta.

¿Cuántas solicitudes puedo hacer por minuto?

El límite es de 60 solicitudes por minuto por clave API. Antes de tu primera recarga, el límite es de 10 por minuto. Si excedes este límite, las solicitudes adicionales se procesarán en cola. Para agencias con alto volumen, recargar tu saldo mantiene el límite estándar de 60 rpm.

¿Es compatible con JavaScript o Node.js?

Sí, es totalmente compatible con JavaScript y Node.js mediante fetch nativo o bibliotecas HTTP. También puedes usar el SDK de OpenAI para JS ajustando la URL base. No ofrecemos un SDK propio, por lo que cualquier cliente HTTP estándar puede integrar la API en tu sitio web o app.

¿Qué es un preset de voz?

Son 8 voces predefinidas con tonos característicos, como Aria (narradora clara) o Felix (energética). Están basadas en grabaciones con licencia y no requieren entrenamiento. Eliges una voz específica en el campo 'voice' de tu solicitud para definir el estilo de la narración de tus propiedades inmobiliarias.

¿Cómo cambio la velocidad de la voz?

Ajusta el parámetro 'speed' en tu solicitud JSON. El rango permitido es de 0.25 a 4.0. Un valor de 1.0 es la velocidad normal. Puedes acelerar la narración para presentaciones rápidas o ralentizarla para tours virtuales detallados, asegurando que la voz sea clara y comprensible en cada caso.

¿Se puede generar audio en segundo plano?

La API es síncrona: envías el texto y recibes el archivo de audio directamente en la respuesta. No hay streaming ni WebSockets. Para procesos en segundo plano, tu servidor debe gestionar las solicitudes y esperar la respuesta. El tiempo de generación es aproximadamente tiempo real para textos largos.

¿Qué pasa si supero el límite de caracteres?

La API rechaza la solicitud si excedes los 4096 caracteres. Debes dividir tu texto en partes más pequeñas dentro de tu aplicación. Cada parte generará un archivo de audio que luego puedes unir. Esto asegura que cada solicitud sea procesada correctamente sin errores de tamaño de entrada.

¿Dónde veo mis solicitudes fallidas?

Tu panel de cuenta en /get-api-key/ muestra el historial de uso, incluyendo el estado de cada solicitud. Las solicitudes fallidas no se cobran y el saldo se devuelve automáticamente. Revisa esta sección para identificar errores de formato o límites excedidos y ajustar tus integraciones de narración.

¿Puedo usar un subdominio personalizado?

No, la API utiliza el subdominio fijo api.sv366.info.

¿Cómo se maneja la autenticación en producción?

Usa una única clave API activa por cuenta. Puedes emitir una nueva clave en cualquier momento desde tu panel; la anterior deja de funcionar inmediatamente. Envía la nueva clave en la cabecera Authorization. Esto permite rotar credenciales sin interrupciones si se compromete una clave en tu entorno de producción.

Primera solicitud

curl

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

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

Para comenzar a integrar la narración en tus tours virtuales, necesitas una clave API válida. Regístrate en la página de obtención de clave para generar tu credencial única. El panel muestra la clave activa, el saldo disponible y un ejemplo listo para copiar.

La autenticación se realiza mediante la cabecera Authorization: Bearer <tu-clave>. Incluye esta cabecera en cada solicitud POST. Si la clave es incorrecta o expira, la API devolverá un error 401 indicando que no estás autorizado para generar audio.

Obtener clave en /get-api-key/

Obtener clave en /get-api-key/

Accede a la página de registro para crear tu cuenta. Puedes iniciar sesión con Google o con correo electrónico y contraseña. Al completar el proceso, obtendrás inmediatamente una clave API activa y un saldo inicial si calificas para la prueba gratuita.

El panel de control muestra los detalles de tu cuenta, incluyendo el saldo actual, los caracteres restantes y ejemplos de código curl listos para usar en tus scripts de automatización de propiedades.

  • Registro con Google o email + contraseña
  • Clave generada inmediatamente tras el registro
  • Panel con saldo, uso y ejemplos de código

Cabecera Authorization Bearer

Cabecera Authorization Bearer

Incluye la cabecera Authorization: Bearer <tu-clave> en el encabezado de cada solicitud HTTP. Esta credencial es el único mecanismo de autenticación para tu cuenta. Asegúrate de no compartirla públicamente en tus repositorios de código.

La API verifica esta cabecera antes de procesar la síntesis. Si omites la cabecera o usas una clave incorrecta, recibirás una respuesta 401 Unauthorized. No necesitas enviar la clave en la URL ni en el cuerpo del JSON.

Un key por cuenta, revocable

Un key por cuenta, revocable

Cada cuenta tiene una sola clave API activa. Si necesitas rotar la credencial por seguridad, puedes emitir una nueva clave en cualquier momento desde el panel. La clave anterior deja de funcionar inmediatamente.

Esto permite gestionar el acceso de diferentes desarrolladores o proyectos sin complicaciones. No hay límite de cambios, pero solo una clave será válida en un momento dado.

Primera solicitud con curl

Ilustración de onda de sonido para: Primera solicitud con curl

La integración más directa es mediante una solicitud HTTP POST al endpoint de síntesis. Este método permite generar audio de forma inmediata sin dependencias de librerías complejas, ideal para probar la calidad de las voces en tus tours virtuales inmobiliarios.

El cuerpo de la petición debe contener el texto de la descripción de la propiedad y la voz seleccionada. La API devuelve el archivo de audio listo para incrustar en tu sitio web o aplicación.

Código de ejemplo POST /v1/audio/speech

Ejecuta esta llamada desde tu terminal para generar la primera muestra. Asegúrate de reemplazar TU_API_KEY con la clave obtenida en /get-api-key/.

  • curl -X POST "https://api.sv366.info/v1/audio/speech" \
  • -H "Authorization: Bearer TU_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "voice": "aria", "input": "Bienvenido a esta exclusiva residencia...", "response_format": "mp3"}' \
  • -o output_audio.mp3

JSON body con input y voice

El campo input acepta hasta 4096 caracteres, suficiente para descripciones estándar de propiedades. El campo voice debe coincidir con uno de los 8 presets disponibles, como aria para narración clara o atlas para un tono neutral.

Si no especificas el idioma, el sistema intentará adivinarlo, pero para textos en español es recomendable incluir el parámetro "language": "es" para garantizar la precisión en la pronunciación.

  • model: "tts-1" o "tts-1-hd"
  • voice: "aria", "nova", "luna", "sage", "felix", "milo", "atlas" u "orion"
  • input: texto de la propiedad (máx. 4096 chars)
  • response_format: "mp3" (recomendado para web)
  • speed: valor entre 0.25 y 4.0

Respuesta con archivo de audio

Una vez procesada la solicitud, la API devuelve el archivo de audio binario. Para agencias inmobiliarias, el formato MP3 es el más eficiente para la carga en tours virtuales.

Si la síntesis falla, la carga se devuelve íntegramente. Si el texto excede el límite, deberás dividirlo en partes de 4096 caracteres y unir los archivos resultantes.

Uso con SDK de OpenAI

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

Para integrar NexOraWeb con las librerías oficiales de OpenAI, solo necesitas ajustar la configuración inicial. La API sigue la misma estructura de solicitud que el endpoint de speech de OpenAI, lo que permite reutilizar el código existente sin reescribir la lógica de generación de audio.

Cambiar base_url al endpoint

Modifica la propiedad base_url del cliente SDK para apuntar a https://api.sv366.info/v1. Esto redirige las solicitudes al servicio de NexOraWeb manteniendo la compatibilidad con la estructura JSON estándar.

Mantener estructura de parámetros

Envía los parámetros model, input, voice y response_format exactamente como se documenta. La API acepta los mismos valores que el endpoint original, facilitando la transición desde otros servicios de TTS sin cambios complejos en tu código.

Compatibilidad con librerías oficiales

Las librerías oficiales de OpenAI para Python, Node.js y otros lenguajes funcionan directamente. Solo requiere proporcionar la clave API válida con el prefijo Bearer y la URL base actualizada.

Parámetros de la solicitud

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

La API acepta dos modelos idénticos en motor y precio: tts-1 y tts-1-hd. Ambos procesan el texto y generan audio con la misma calidad base, por lo que puedes elegir cualquiera de los dos sin variación en el costo ni en la latencia de generación para tus tours virtuales.

Modelo tts-1 o tts-1-hd

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio por millón de caracteres. No hay diferencia técnica ni de calidad audible entre ellos en la respuesta final, solo una etiqueta para tu código. Puedes usar tts-1 para simplificar o tts-1-hd si tu integración ya espera esa nomenclatura estándar.

Voz entre 8 presets disponibles

Selecciona una de las 8 voces predefinidas según el tono de la propiedad. Para narraciones profesionales, sage ofrece un tono calmado e instruccional, ideal para explicar características técnicas. atlas es neutral y adecuado para noticias o datos de mercado, mientras que felix aporta energía para presentaciones promocionales rápidas.

  • Femeninas: aria, nova, luna, sage
  • Masculinas: felix, milo, atlas, orion

Velocidad de 0.25 a 4.0

El parámetro speed ajusta la tasa de habla entre 0.25 y 4.0, con 1.0 siendo la velocidad normal. En vídeos de tours virtuales, una velocidad ligeramente superior (1.1-1.3) puede mantener el dinamismo sin sacrificar la claridad. Ajusta este valor para sincronizar la narración con los cortes visuales de tu presentación.

Formatos de audio soportados

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

La API permite generar archivos de audio en cinco formatos distintos, adaptándose a las necesidades específicas de cada flujo de trabajo de producción inmobiliaria. Puedes elegir el formato más adecuado según el destino final del vídeo o tour virtual, equilibrando calidad y tamaño de archivo.

Todos los formatos se entregan mediante la misma llamada API, sin necesidad de conversión adicional. Elige el que mejor se integre en tu pipeline de edición o publicación.

MP3 para web y vídeos

El formato MP3 es la opción recomendada para la mayoría de los casos de uso en el sector inmobiliario. Ofrece una buena relación entre calidad de voz y tamaño de archivo, lo que facilita la carga rápida en plataformas web y redes sociales.

Es ideal para narraciones de propiedades en vídeos promocionales de YouTube, Instagram o páginas de ventas de casas.

  • Tamaño de archivo optimizado para carga web
  • Amplio soporte en reproductores de vídeo y navegadores
  • Adecuado para narraciones de tours virtuales en web

WAV para alta calidad

Si necesitas la máxima fidelidad para edición profesional en software de escritorio, WAV es la opción adecuada. Proporciona audio sin pérdida de calidad, manteniendo el tono claro y profesional de las voces generadas.

Utiliza este formato cuando la narración se vaya a procesar con efectos de audio adicionales o mezclas complejas en la postproducción.

  • Audio sin pérdida de calidad
  • Ideal para edición profesional en DAWs
  • Mayor tamaño de archivo que MP3

OPUS, FLAC y PCM disponibles

Además de MP3 y WAV, la API soporta OPUS, FLAC y PCM para casos específicos. OPUS es un formato de audio eficiente., mientras que FLAC ofrece compresión sin pérdida.

PCM es útil si necesitas datos de audio crudos para procesamiento personalizado. Todos estos formatos se generan bajo demanda, sin costos adicionales por el formato elegido.

  • OPUS para eficiencia de archivo
  • FLAC para compresión sin pérdida
  • PCM para datos de audio crudos

Límites y rendimiento

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

Cada llamada a la API acepta un máximo de 4.096 caracteres por solicitud. Para guiones de tours virtuales más extensos, debes dividir el texto en fragmentos y unir los archivos de audio resultantes.

El límite de velocidad es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si envías muchas propiedades simultáneamente, las peticiones se procesan en cola secuencial.

4.096 caracteres por solicitud

El campo input acepta hasta 4.096 caracteres, incluyendo espacios y puntuación. Para descripciones largas de propiedades, divide el texto en partes y une los audios generados.

60 solicitudes por minuto

Cada clave API permite 60 solicitudes por minuto. Antes de la primera recarga, el límite es de 10 por minuto. Si superas este límite, la API devolverá un error de rate limit.

Procesamiento secuencial bajo carga

Las solicitudes se procesan una tras otra. Bajo carga, una petición puede esperar en cola. La velocidad típica es de 25 caracteres por segundo de audio generado.

  • Tiempo de espera variable según la cola
  • Generación aproximada: 25 caracteres/segundo
  • Sin streaming ni audio parcial.

Manejo de errores comunes

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

Antes de integrar la API, es útil anticipar los errores más frecuentes al narrar tours virtuales. La clave de autenticación debe enviarse correctamente para evitar rechazos inmediatos, y el texto debe respetar los límites de caracteres para garantizar una síntesis exitosa.

Error 401 por clave inválida

Este error indica que la cabecera Authorization: Bearer contiene una clave incorrecta o expirada. Verifica que tu API key esté activa en el panel de /get-api-key/. Si emitiste una nueva clave, la anterior deja de funcionar inmediatamente.

Error 413 por texto largo

La API rechaza solicitudes con más de 4096 caracteres en el campo input. Para vídeos largos, divide el guion en fragmentos menores a este límite y une los archivos de audio resultantes manualmente.

Retries automáticos recomendados

Debido al procesamiento secuencial, las solicitudes pueden retrasarse bajo carga. Implementa reintentos exponenciales para manejar tiempos de espera sin duplicar cobros si la solicitud ya se completó.

Endpoints disponibles

Ilustración de onda de sonido para: Endpoints disponibles

La API de NexOraWeb está diseñada para integrarse directamente en los flujos de producción de agencias inmobiliarias, permitiendo la generación automática de narraciones para tours virtuales y presentaciones de propiedades.

Los tres endpoints principales cubren desde la creación del audio hasta la gestión de recursos, asegurando que el equipo técnico pueda automatizar la voz en off sin intervención manual.

POST /v1/audio/speech para generar

Este es el endpoint principal para convertir texto en audio. Envía una solicitud JSON con el texto de la descripción de la propiedad (máximo 4096 caracteres) y la voz deseada. La API devuelve el archivo de audio generado directamente en la respuesta.

Es necesario incluir la cabecera de autenticación con tu clave API. Si la síntesis falla, no se cobra el crédito, lo que permite probar diferentes voces o textos sin riesgo financiero.

  • Envía texto y selecciona una de las 8 voces disponibles.
  • Recibe el archivo de audio en el formato seleccionado (mp3, wav, etc.).
  • Procesamiento secuencial: las solicitudes se manejan una tras otra bajo carga.

GET /v1/voices para listar voces

Utiliza este endpoint para obtener la lista completa de voces disponibles, sus idiomas y formatos soportados. Esto es útil para configurar dinámicamente el selector de voz en tu panel de administración o para verificar la compatibilidad de idiomas antes de generar el audio.

Las voces incluyen opciones femeninas como Aria o Nova, y masculinas como Felix o Milo, todas capaces de hablar los 23 idiomas soportados, incluyendo español.

  • Obtén detalles de cada voz preestablecida.
  • Verifica los idiomas disponibles para cada voz.
  • Consulta los formatos de audio compatibles.

GET /v1/models para detalles

Este endpoint proporciona información sobre los modelos de síntesis disponibles, como tts-1 y tts-1-hd. Ambos utilizan el mismo motor y tienen el mismo precio, pero puedes consultar sus detalles específicos para asegurar que se ajustan a la calidad requerida para tus vídeos.

La información devuelta ayuda a entender las capacidades técnicas subyacentes, como la velocidad de generación y los límites de caracteres, facilitando la planificación de cargas de trabajo para grandes catálogos de propiedades.

  • Consulta las especificaciones de los modelos tts-1 y tts-1-hd.
  • Verifica la información de precios y capacidad de procesamiento.
  • Accede a metadatos técnicos para integración avanzada.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. No se puede subir una grabación para clonar la voz de un agente o locutor específico.

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-python on GitHub
  3. FFmpeg documentation
  4. Tether (USDT)
  5. LibriVox public-domain audiobooks
  6. curl documentation
  7. ISO 639 language codes
  8. openai-node on GitHub
  9. TRON developer hub: TRC-20
  10. OpenAI API reference: create speech
  11. IETF RFC 7845: Ogg Opus
  12. LibriTTS-R paper (arXiv 2305.18802)

Más en este sitio