¿MatuVoice tiene API de texto a voz?

Sí. Es una API REST con un endpoint principal, POST /v1/speech, que recibe texto y devuelve directamente el audio en formato audio/mpeg.

¿Qué devuelve el endpoint de síntesis?

El cuerpo de la respuesta es el archivo de audio en audio/mpeg, no un JSON con una URL. Además incluye cabeceras con la voz utilizada, los caracteres facturados y el cupo restante del periodo.

¿Puedo llamar a la API desde el navegador?

El endpoint responde con CORS, pero no conviene: la API key quedaría expuesta en el cliente. La recomendación es llamarla desde tu backend y servir el audio ya generado a tu aplicación.

Referencia

API de texto a voz

La API de MatuVoice tiene un solo endpoint que importa: POST /v1/speech. Le mandas texto y el identificador de una voz, y la respuesta es el MP3. El contrato no cambia según de dónde venga el texto, así que sirve igual para un agente de IA, un IVR o un generador de contenido.

Autenticación

Cada petición viaja con una API key en la cabecera Authorization usando el esquema Bearer. Las claves se crean y se revocan desde el dashboard, y lo recomendable es usar una por aplicación para poder cortarla sin afectar al resto.

Authorization: Bearer mv_live_...

POST /v1/speech

Genera el audio y lo devuelve en el cuerpo de la respuesta.

curl -X POST https://matuvoice.matubyte.com/v1/speech \
  -H "Authorization: Bearer mv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Tu pedido llega mañana entre 8 y 11 de la mañana.",
    "voice": "edge:es-CR-JuanNeural"
  }' --output voz.mp3

Parámetros del cuerpo

Parámetros aceptados por POST /v1/speech
Campo	Tipo	Requerido	Detalle
text	string	Sí	Texto a sintetizar. Entre 1 y 5000 caracteres.
voice	string	No	Identificador de la voz. Por defecto edge:es-CR-JuanNeural.
rate	number	No	Velocidad de habla, entre 0.5 y 2. Por defecto 1.
volume	number	No	Volumen relativo, entre 0.2 y 2. Por defecto 1.

Respuesta

El cuerpo es el audio en audio/mpeg. Junto a él llegan cabeceras con metadatos de la síntesis y del consumo, útiles para mostrar el saldo restante o para registrar el gasto por cliente.

Cabeceras de respuesta
Cabecera	Detalle
X-MatuVoice-Voice	Nombre del personaje que sintetizó el audio.
X-MatuVoice-Voice-Id	Identificador exacto de la voz utilizada.
X-MatuVoice-Provider	Proveedor del motor de síntesis.
X-MatuVoice-Characters	Caracteres facturados en esta petición.
X-MatuVoice-Usage	Caracteres consumidos en el periodo actual.
X-MatuVoice-Limit	Límite de caracteres del plan.
X-MatuVoice-Remaining	Caracteres restantes del periodo.

Ejemplos de integración

Node.js

const response = await fetch("https://matuvoice.matubyte.com/v1/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MATUVOICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text, voice: "edge:es-CR-JuanNeural" }),
});

const audio = Buffer.from(await response.arrayBuffer());

Python

import os, requests

response = requests.post(
    "https://matuvoice.matubyte.com/v1/speech",
    headers={"Authorization": f"Bearer {os.environ['MATUVOICE_API_KEY']}"},
    json={"text": texto, "voice": "edge:es-CR-JuanNeural"},
)

open("voz.mp3", "wb").write(response.content)

Errores

Códigos de error de la API
HTTP	Código	Cuándo ocurre
400	invalid_json / invalid_request	El cuerpo no es JSON válido o falta el campo text.
401	unauthorized	Falta la API key o no es válida.
402	quota_exceeded	Se agotó el cupo de caracteres del periodo.
402	voice_unavailable	El proveedor de esa voz no está activo en el servidor.
404	voice_not_found	El identificador de voz no existe en el catálogo.
502	synthesis_failed	El motor de síntesis no pudo generar el audio.

Cupos y límites

Cada plan define un tope de caracteres al mes y un número máximo de claves. Las cabeceras de uso permiten saber en todo momento cuánto queda del periodo. El detalle está en precios y planes.

Preguntas frecuentes sobre la API

¿MatuVoice tiene API de texto a voz?: Sí. Es una API REST con un endpoint principal, POST /v1/speech, que recibe texto y devuelve directamente el audio en formato audio/mpeg.
¿Cómo autentico las peticiones a la API?: Con una API key en la cabecera Authorization usando el esquema Bearer. Las claves se crean y se revocan desde el dashboard, y conviene usar una distinta por aplicación.
¿Qué devuelve el endpoint de síntesis?: El cuerpo de la respuesta es el archivo de audio en audio/mpeg, no un JSON con una URL. Además incluye cabeceras con la voz utilizada, los caracteres facturados y el cupo restante del periodo.
¿Puedo llamar a la API desde el navegador?: El endpoint responde con CORS, pero no conviene: la API key quedaría expuesta en el cliente. La recomendación es llamarla desde tu backend y servir el audio ya generado a tu aplicación.