Preguntas frecuentes
¿Qué es una clave API?
Es un token de seguridad único que autentifica tus solicitudes a la API. Cada cuenta tiene una clave activa que se envía en la cabecera Authorization. Si la necesitas, puedes emitir una nueva en cualquier momento; la anterior dejará de funcionar inmediatamente.
¿Cómo obtengo mi clave API?
Regístrate en la página /get-api-key/ usando Google o correo electrónico. Una vez creado tu cuenta, la página mostrará tu clave API, tu saldo, el crédito de prueba y ejemplos listos para usar. Las cuentas por email no incluyen crédito inicial.
¿Qué es la base_url?
Es la dirección base para las llamadas HTTP. Debes configurarla como https://api.deusapg.net/v1. Esto permite que los SDKs oficiales de OpenAI funcionen correctamente cambiando solo este parámetro, manteniendo la misma estructura de cuerpo JSON que el endpoint de speech.
¿Puedo usar la API con Python?
Sí, puedes usar el SDK oficial de OpenAI para Python. Solo necesitas ajustar la base_url a https://api.deusapg.net/v1 y proporcionar tu clave API. También puedes realizar llamadas HTTP directas usando cualquier librería de peticiones que soporte JSON y cabeceras.
¿Qué es un formato de respuesta?
Es el tipo de archivo de audio que recibes tras sintetizar el texto. Puedes elegir entre mp3, wav, opus, flac o pcm. Este formato se especifica en el campo response_format del cuerpo JSON de tu solicitud POST al endpoint de audio.
¿Cuántos caracteres puedo enviar por petición?
Cada solicitud puede contener hasta 4096 caracteres de texto. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres en este límite.
¿Qué significa tts-1-hd?
Es el modelo de alta definición disponible en la API. Tiene el mismo motor y precio que tts-1. Utiliza la misma estructura de solicitud y el mismo motor que tts-1, manteniendo el costo de $0.01 por cada 1000 caracteres procesados.
¿Puedo cambiar el idioma de la voz?
Sí, puedes establecer el idioma mediante el campo language con un código ISO. Si no lo indicas, el sistema lo adivina por el guion, asumiendo inglés para texto latino. Es recomendable especificarlo explícitamente para textos en idiomas distintos al inglés.
¿Qué es la cabecera Authorization?
Es el encabezado HTTP que contiene tu clave API para autenticar la solicitud. El formato debe ser Authorization: Bearer tts-... donde ... es tu clave única. Sin esta cabecera, la API rechazará tu solicitud indicando que no estás autorizado.
¿Qué pasa si excedo los límites de solicitudes?
El límite es de 60 solicitudes por minuto por clave. Antes del primer recargo, el límite es de 10 por minuto. Si excedes, las solicitudes adicionales se procesarán en cola, lo que puede añadir latencia.
¿Cómo sé si una solicitud falló?
La API devuelve un código de estado HTTP diferente a 200 en caso de error. Si la síntesis falla, el cargo se devuelve íntegramente. Puedes verificar el estado de tu solicitud inspeccionando la respuesta HTTP y el cuerpo JSON devuelto.
¿Puedo usar la API en producción?
Sí, está diseñada para uso en producción. No hay planes mensuales ni gastos mínimos. Solo necesitas recargar tu saldo en USDT (TRC-20). La velocidad es aproximadamente en tiempo real para textos largos, aunque las solicitudes se procesan en cola bajo carga.
¿Qué es un SDK de OpenAI?
Es una biblioteca de código proporcionada por OpenAI para facilitar las llamadas a su API. Puedes usarla con nuestra API cambiando la base_url. No ofrecemos un SDK propio, pero la compatidad con el formato de solicitud de OpenAI es total.
¿Ofrecen ejemplos en otros lenguajes?
La documentación incluye ejemplos básicos, pero no ofrecemos ejemplos específicos para cada lenguaje más allá de los estándares HTTP y el SDK de OpenAI. Puedes usar cualquier lenguaje que soporte peticiones POST con JSON y la cabecera de autorización adecuada.
Primera solicitud
curl
curl https://api.deusapg.net/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.deusapg.net/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.deusapg.net/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 |
Obtén tu clave API
Comienza creando tu cuenta en el sitio usando tu cuenta de Google o un correo electrónico con contraseña. Este registro inicial es el primer paso para acceder a la potencia de nuestra API de texto a voz, diseñada para que los freelancers empiecen a trabajar de inmediato sin barreras técnicas complejas.
Registro con Google o email
Puedes registrarte rápidamente mediante Google para una experiencia fluida, o usar un correo electrónico tradicional con una contraseña segura. Si eliges el método de email, tu cuenta se crea sin saldo de prueba, mientras que el inicio con Google incluye automáticamente un crédito de $0.50 válido por 7 días.
Genera tu clave en /get-api-key/
Una vez registrado, accede a la página /get-api-key/ para obtener tu credencial única. Esta página muestra claramente tu clave API, el saldo disponible, el crédito de prueba y el consumo de caracteres. Aquí también encontrarás un ejemplo listo en cURL para que puedas hacer tu primera prueba al instante.
Una clave activa por cuenta
Cada cuenta mantiene una única clave activa. Si necesitas generar una nueva por seguridad, la emisión de la nueva clave invalida la anterior de forma inmediata y permanente. Esto asegura que solo tengas un punto de acceso controlado para tus solicitudes de síntesis de voz.
Primera solicitud con cURL
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta, no en formato JSON. Para probar la integración, puedes usar cURL enviando tu texto y configurando los parámetros básicos como el modelo y la voz deseada.
Este enfoque te permite obtener el archivo de audio listo para usar en tus proyectos sin necesidad de análisis adicionales de la respuesta. Asegúrate de que tu cliente HTTP pueda manejar respuestas binarias para evitar errores al recibir el audio.
Envía texto y recibe audio
La respuesta a tu solicitud cURL contiene el archivo de audio binario directamente en el cuerpo.
No hay necesidad de parsear JSON para obtener el audio; simplemente guarda la respuesta en un archivo con la extensión adecuada según el response_format solicitado.
Ejemplo práctico en cURL
Usa el siguiente comando para enviar una solicitud básica. Asegúrate de reemplazar TU_API_KEY con tu clave real.
Este ejemplo utiliza el modelo tts-1 con la voz nova y formato mp3. Ajusta los parámetros según tus necesidades.
- Reemplaza
TU_API_KEYcon tu clave generada en /get-api-key/. - Ajusta el campo
inputcon el texto que deseas convertir. - Modifica
voiceyresponse_formatsegún prefieras.
Respuesta en formato JSON
La respuesta a tu solicitud cURL contiene el archivo de audio binario directamente en el cuerpo.
El código de estado HTTP 200 indica éxito, mientras que otros códigos indicarán errores específicos que puedes consultar en la sección de manejo de errores.
- Código 200: Éxito, archivo de audio recibido.
- Código 401: Clave API inválida o expirada.
- Código 429: Límite de solicitudes excedido.
Uso con SDK de OpenAI
Puedes usar las librerías oficiales de OpenAI simplemente ajustando la URL base. No necesitas un SDK propio ni instalar paquetes adicionales de nuestra API; solo redirige las peticiones hacia nuestro endpoint para aprovechar la misma estructura de datos que ya conoces.
Cambia la base_url a nuestra API
Modifica la propiedad base_url de tu cliente a https://api.deusapg.net/v1. Esto permite que cualquier solicitud dirigida a OpenAI se enrute directamente a nuestros servidores sin cambios en la lógica de tu aplicación.
Compatible con librerías oficiales
Las bibliotecas oficiales de OpenAI funcionan perfectamente porque respetamos el estándar abierto. Puedes mantener tu código existente y solo actualizar la configuración de conexión para integrar la síntesis de voz sin reescribir toda la lógica de red.
Mismo formato de petición
El cuerpo de la solicitud JSON es idéntico al del endpoint de speech de OpenAI. Solo necesitas proporcionar model, input, voice y response_format. La autenticación se maneja con tu clave API en la cabecera Authorization.
- Usa
tts-1otts-1-hdcomo valor de modelo. - Envía el texto en el campo
input. - Especifica el idioma si es necesario para texto en latín.
Parámetros de la solicitud
La configuración básica de tu solicitud determina la calidad del audio y la voz que recibirás. El campo model te permite elegir entre tts-1 o tts-1-hd, motores idénticos con el mismo precio por carácter. No hay diferencia técnica en la generación, solo en la identificación del motor utilizado.
Elegir la voz adecuada es clave para el tono de tu proyecto. Dispones de 8 presets predefinidos que cubren desde narradores claros hasta voces documentales profundas. Puedes especificar un idioma opcional si el texto no es en inglés para evitar que el sistema lo adivine incorrectamente.
model: tts-1 o tts-1-hd
Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. La elección es principalmente para fines de identificación en tu código.
No afecta la velocidad ni la calidad percibida del audio generado. Puedes cambiar entre ellos sin perder compatibilidad con tu integración actual.
- Usa
tts-1para simplicidad. - Usa
tts-1-hdsi prefieres etiquetar tus solicitudes como de alta definición, aunque la calidad es idéntica.
voice: 8 opciones disponibles
Selecciona una de las ocho voces disponibles para dar personalidad a tu audio. Las opciones incluyen voces femeninas como Aria y Nova, y masculinas como Felix y Milo.
Cada voz tiene un carácter distintivo, desde narradoras claras hasta voces documentales profundas. Puedes forzar un idioma específico si el texto está en español para asegurar la pronunciación correcta.
- aria: narradora cálida y clara.
- nova: voz brillante y enérgica.
- luna: suave, ideal para historias.
- sage: calmada, para instrucciones.
- felix: enérgica, para promociones.
- milo: amigable y conversacional.
- atlas: neutral, estilo noticias.
- orion: profunda, estilo documental.
response_format: mp3, wav, opus, flac, pcm
El campo response_format define el contenedor del audio que recibirás. Por defecto, la API devuelve MP3, que es ligero y ampliamente compatible con la mayoría de reproductores y editores.
Puedes solicitar WAV, FLAC o OPUS para mayor calidad sin pérdida, o PCM para datos crudos sin compresión. Todos estos formatos se entregan en la respuesta JSON como datos binarios codificados.
- mp3: recomendado para la mayoría de casos.
- wav: sin compresión, ideal para edición.
- opus: alta calidad con compresión eficiente.
- flac: sin pérdida, tamaño de archivo mayor.
- pcm: datos crudos sin cabecera.
Límites de uso
Para mantener la estabilidad del servicio, la API impone límites claros en el uso. Si superas los 60 solicitudes por minuto, las peticiones se procesarán en cola en lugar de rechazarse inmediatamente, lo que puede añadir latencia durante picos de demanda.
Estos límites garantizan que tu generación de audio sea predecible, incluso cuando procesas textos largos que requieren múltiples solicitudes para completar la síntesis.
60 solicitudes por minuto
El límite estándar es de 60 solicitudes por minuto por clave. Si necesitas procesar textos largos, recuerda que debes dividirlos en fragmentos de hasta 4096 caracteres y unir los archivos de audio resultantes.
10 solicitudes antes del primer pago
Durante la fase de prueba, antes de realizar tu primera recarga, puedes realizar hasta 10 solicitudes por minuto. Esto te permite validar la integración sin compromisos financieros inmediatos.
Texto máximo: 4096 caracteres por petición
Cada solicitud acepta un máximo de 4096 caracteres, incluyendo espacios y puntuación. Para textos más extensos, divide el contenido en bloques manejables y concatena los audios generados para obtener el resultado final.

Manejo de errores
La API devuelve códigos de estado HTTP claros para indicar el resultado de cada solicitud. Si la síntesis falla, no se descuenta crédito de tu cuenta, asegurando que solo pagues por audio generado con éxito.
Los errores comunes suelen deberse a límites de caracteres o formato inválido. La respuesta incluye un mensaje descriptivo que indica exactamente qué corregir, facilitando la depuración rápida en tus flujos de trabajo.
Solicitudes fallidas sin cargo
Si la generación de audio no se completa, el cargo se devuelve íntegramente. No pagas por texto que no se convierte en audio, lo que protege tu balance durante las pruebas.
Códigos de estado HTTP
El endpoint devuelve 200 en éxito, 400 para errores de formato o parámetros, y 429 si superas los 60 solicitudes por minuto. Monitorea estos códigos para ajustar tu lógica de reintento.
- 200: Éxito, audio disponible en la respuesta
- 400: Error de sintaxis o límite excedido
- 429: Límite de tasa alcanzado
Mensajes de error descriptivos
Cada error incluye un campo de detalle que explica la causa, como un carácter de control inválido o un formato de voz desconocido. Esto permite automatizar la corrección sin consultar documentación adicional.
Autenticación
La seguridad de tu integración depende de una cabecera de autorización clara y directa. Cada solicitud que envíes a la API debe incluir tu clave única en el encabezado HTTP, garantizando que solo tú puedas generar audio con tu cuenta.
El formato es estándar y fácil de implementar en cualquier lenguaje de programación, manteniendo la simplicidad que caracteriza a nuestra solución para freelancers y desarrolladores independientes que priorizan la agilidad sin complicaciones.
Cabecera Authorization: Bearer
Envía tu clave con cada petición POST. El formato debe ser Authorization: Bearer tts-tu_clave_aqui. Esto identifica tu cuenta y descuenta el saldo correspondiente.
Asegúrate de que la clave se envíe correctamente para evitar errores 401. La API verifica la autenticación antes de procesar el texto.
- - Formato:
Authorization: Bearer <tu_clave> - - Incluida en cada solicitud POST
Clave única por cuenta
Tu panel de control en /get-api-key/ muestra una sola clave activa. Esta es tu identidad única para generar audio y consultar balances.
Puedes ver el estado de la clave y el saldo restante directamente en la interfaz sin necesidad de herramientas externas.
Revocación instantánea al emitir nueva clave
Si sospechas que tu clave fue expuesta, simplemente genera una nueva desde tu panel. La clave antigua deja de funcionar al instante.
No hay periodo de gracia ni retrasos; la revocación es inmediata, permitiendo que recuperes el control de tu API en segundos.
Ejemplo completo
Este ejemplo integra todos los parámetros para generar audio inmediatamente. Copia el bloque y reemplaza tu_clave_aqui con tu credencial real para probar la integración sin configuraciones complejas.
Código listo para copiar
```bash curl -X POST "https://api.deusapg.net/v1/audio/speech" \ -H "Authorization: Bearer tu_clave_aqui" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "Hola, esta es una prueba de la API de Deusap.", "voice": "nova", "response_format": "mp3", "speed": 1.0 }' \ -o output.mp3 ```
Parámetros configurables
Puedes ajustar la voz entre las 8 opciones, como aria o atlas, y modificar la velocidad entre 0.25 y 4.0. El formato de salida admite mp3, wav, opus, flac o pcm, adaptándose a tu flujo de trabajo de desarrollo.
Resultado en formato de audio
La respuesta contiene el archivo de audio binario listo para reproducirse o almacenarse. No se requiere almacenamiento adicional ni gestión de archivos temporales complejos para la respuesta inmediata.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
