@matubyte/matuvoice

Convierte texto en audio con las voces de MatuVoice.

Requisitos

• Una cuenta en MatuVoice
• Una API key (mv_live_…) creada en tu dashboard
• Node.js 18 o superior

Instalación

npm install @matubyte/matuvoice

Configuración

Guarda tu API key en una variable de entorno. No la escribas en el código.

MATUVOICE_API_KEY=mv_live_xxxxxxxx

Opcional (por defecto ya apunta a producción):

MATUVOICE_BASE_URL=https://api.matuvoice.matubyte.com

Ejemplo rápido

import { writeFileSync } from "node:fs";
import { MatuVoice } from "@matubyte/matuvoice";

const client = MatuVoice.fromEnv();

const result = await client.speech.synthesize({
  text: "Hola desde mi aplicación",
  voice: "juan",
});

writeFileSync("salida.mp3", result.audio);

Generar audio

const result = await client.speech.synthesize({
  text: "El texto que quieres escuchar",
  voice: "juan",
  rate: 1,    // opcional: velocidad (0.5 a 2)
  volume: 1,  // opcional: volumen (0.2 a 2)
});

// result.audio → archivo MP3 listo para guardar o enviar
// result.usage.remaining → caracteres que te quedan en tu plan

Ver voces disponibles

const { data: voces } = await client.voices.list({ language: "es" });

for (const voz of voces) {
  console.log(voz.id, voz.name);
}

Usa el id de la voz en speech.synthesize.

Consultar tu plan y saldo

const cuenta = await client.account.me();

console.log(cuenta.plan);
console.log(cuenta.usage.remaining, "caracteres restantes");

Errores frecuentes

| Código | Qué significa | |--------|---------------| | invalid_api_key | La API key es incorrecta o fue revocada | | quota_exceeded | Agotaste los caracteres de tu plan | | voice_not_found | El id de voz no existe | | synthesis_failed | No se pudo generar el audio; intenta de nuevo |

import { MatuVoiceError } from "@matubyte/matuvoice";

try {
  await client.speech.synthesize({ text: "Hola", voice: "juan" });
} catch (error) {
  if (error instanceof MatuVoiceError) {
    console.error(error.message);
  }
}

Más información

• Sitio web: matuvoice.matubyte.com
• Documentación de la API: matuvoice.matubyte.com/api
• Crear API keys: matuvoice.matubyte.com/dashboard/keys

Licencia

MIT