Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// POST /api/v1/ai/tts — text-to-speech for agents (free daily quota → x402).
// GET /api/v1/ai/tts?voices=1 — list the available voices (free, public).
//
// Productizes the platform's free NVIDIA NIM Magpie lane (api/_lib/tts-nvidia.js)
// as a versioned, agent-callable endpoint:
// • Free tier: 10 calls/day per IP, text ≤500 chars — the funnel.
// • Above the free tier (quota exhausted OR text >500 chars OR an X-PAYMENT
// header is present) the request falls through to the x402 rail: a 402
// challenge with bazaar discovery, settled per call in USDC.
//
// Both tiers run the SAME synthesis (api/_lib/ai-speech.js) and return the SAME
// JSON shape (base64 audio) — the paid rail must return JSON so settlement runs,
// so the free lane matches for a uniform contract.
import { cors, method, error, json, wrap, readBody } from '../../_lib/http.js';
import { clientIp, limits } from '../../_lib/rate-limit.js';
import { priceFor } from '../../_lib/x402-prices.js';
import { paidEndpoint } from '../../_lib/x402-paid-endpoint.js';
import { declareHttpDiscovery, withService } from '../../_lib/x402/bazaar-helpers.js';
import { installAccessControl } from '../../_lib/x402/access-control.js';
import { TTS_VOICE_IDS, DEFAULT_VOICE } from '../../_lib/tts-voices.js';
import {
ttsVoicesPayload,
readTtsInput,
ttsConfigured,
ttsSynthesize,
FREE_TTS_MAX_CHARS,
PAID_TTS_MAX_CHARS,
TTS_MAX_BODY_BYTES,
} from '../../_lib/ai-speech.js';
export const maxDuration = 45;
const ROUTE = '/api/v1/ai/tts';
const PRICE_ATOMICS = priceFor('ai-tts', '5000'); // $0.005 per call (env: X402_PRICE_AI_TTS)
// Uniqueness-first: the first sentence answers "what can I only get here".
const DESCRIPTION =
'Text-to-speech for agents over x402 — a keyless neural TTS lane you can call ' +
'with no account and no API key; pay $0.005 USDC per call for multilingual ' +
'Magpie voices (English, Spanish, French, German, Italian, Hindi, Chinese, ' +
'Vietnamese, Japanese). POST { text, voice? } and receive base64 WAV/PCM audio. ' +
'A free daily quota lets you try it before paying.';
const INPUT_EXAMPLE = {
text: 'Your deploy finished — three services are green and latency is nominal.',
voice: 'nova',
format: 'wav',
language: 'en-US',
};
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['text'],
properties: {
text: {
type: 'string',
minLength: 1,
maxLength: PAID_TTS_MAX_CHARS,
description: `Text to synthesize (≤${PAID_TTS_MAX_CHARS} chars; free tier ≤${FREE_TTS_MAX_CHARS}).`,
},
voice: {
type: 'string',
enum: TTS_VOICE_IDS,
default: DEFAULT_VOICE,
description: 'Voice id. Unknown values fall back to the default persona.',
},
format: {
type: 'string',
enum: ['wav', 'pcm'],
default: 'wav',
description: 'Audio container. Magpie emits WAV or raw PCM.',
},
language: {
type: 'string',
default: 'en-US',
description: 'BCP-47 language tag (en-US, es-US, fr-FR, de-DE, it-IT, hi-IN, zh-CN, vi-VN, ja-JP).',
},
},
};
const OUTPUT_EXAMPLE = {
audio: 'UklGR... (base64-encoded WAV)',
encoding: 'base64',
format: 'wav',
content_type: 'audio/wav',
sample_rate: 44100,
voice: 'Magpie-Multilingual.EN-US.Aria',
model: 'magpie-tts-multilingual',
characters: 71,
bytes: 132_344,
tier: 'paid',
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['audio', 'format', 'content_type', 'sample_rate', 'voice', 'model'],
properties: {
audio: { type: 'string', description: 'Base64-encoded audio in `format`.' },
encoding: { type: 'string', const: 'base64' },
format: { type: 'string' },
content_type: { type: 'string' },
sample_rate: { type: 'integer' },
voice: { type: 'string' },
model: { type: 'string' },
characters: { type: 'integer' },
bytes: { type: 'integer' },
tier: { type: 'string', enum: ['free', 'paid'] },
},
};
const BAZAAR = declareHttpDiscovery({
method: 'POST',
bodyType: 'json',
input: INPUT_EXAMPLE,
inputSchema: INPUT_SCHEMA,
output: { example: OUTPUT_EXAMPLE, schema: OUTPUT_SCHEMA },
});
// The x402 paid twin — built once, lazily (constructing it touches env-derived
// pay-to config). Reused for every over-quota / paying request.
let _paid = null;
function paidHandler() {
if (_paid) return _paid;
_paid = paidEndpoint({
route: ROUTE,
method: 'POST',
priceAtomics: PRICE_ATOMICS,
networks: ['base', 'solana'],
description: DESCRIPTION,
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws Text-to-Speech',
tags: ['tts', 'speech', 'voice', 'audio', 'ai'],
}),
requiredScope: 'x402:bypass',
accessControl: installAccessControl({ requiredScope: 'x402:bypass' }),
async handler({ req }) {
const raw = req._aiSpeechBody ?? (await readBody(req, TTS_MAX_BODY_BYTES));
const input = readTtsInput(raw, { maxChars: PAID_TTS_MAX_CHARS });
const payload = await ttsSynthesize(input);
return { ...payload, tier: 'paid' };
},
});
return _paid;
}
export default wrap(async function handler(req, res) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET', 'POST'])) return;
// ── Voices / capability probe (free, public) ─────────────────────────────
if (req.method === 'GET') {
const url = new URL(req.url, 'http://localhost');
if (url.searchParams.has('voices')) {
return json(res, 200, { data: ttsVoicesPayload() }, { 'cache-control': 'public, max-age=3600' });
}
return json(
res,
200,
{
data: {
endpoint: ROUTE,
description: 'POST text to synthesize speech. GET ?voices=1 lists voices.',
configured: ttsConfigured(),
free_tier: { per_day: 10, max_chars: FREE_TTS_MAX_CHARS },
paid: { price_usdc: Number(PRICE_ATOMICS) / 1e6, max_chars: PAID_TTS_MAX_CHARS, networks: ['base', 'solana'] },
},
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── POST: synthesize ──────────────────────────────────────────────────────
// ttsSynthesize falls through to the Gemini TTS lane when Magpie cannot
// serve, so the endpoint is available whenever EITHER is configured. Gating
// on the NVIDIA key alone used to 503 a request the Gemini lane could have
// answered on platform credits.
if (!ttsConfigured()) {
return error(
res,
503,
'not_configured',
'Text-to-speech is not configured (set NVIDIA_API_KEY, or GOOGLE_CLOUD_PROJECT for the Gemini lane)',
);
}
// Buffer the body once, then decide the lane — the paid rail reads the same
// bytes (req._aiSpeechBody) so the stream is never consumed twice.
let raw;
try {
raw = await readBody(req, TTS_MAX_BODY_BYTES);
} catch (e) {
if (e?.status === 413) return error(res, 413, 'payload_too_large', `request body exceeds ${TTS_MAX_BODY_BYTES} bytes`);
return error(res, 400, 'bad_request', e?.message || 'could not read request body');
}
req._aiSpeechBody = raw;
// The stream is drained now; leave the bytes where readBody looks first so
// the paid wrapper hashes the real request into its idempotency key.
if (!Buffer.isBuffer(req.rawBody)) req.rawBody = raw;
// A payment header means the caller is on the paid rail already.
const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);
if (paymentPresent) return paidHandler()(req, res);
// Validate against the paid ceiling first, so genuinely bad input (empty / too
// long) is a clean 400 rather than a payment prompt.
let input;
try {
input = readTtsInput(raw, { maxChars: PAID_TTS_MAX_CHARS });
} catch (e) {
return error(res, e.status || 400, e.code || 'bad_request', e.message);
}
// Beyond the free-tier char cap → pay per call.
if (input.text.length > FREE_TTS_MAX_CHARS) return paidHandler()(req, res);
// Free daily quota (per IP). Exhausted → the 402 challenge.
const rl = await limits.aiTtsFreeIp(clientIp(req));
if (!rl.success) return paidHandler()(req, res);
try {
const payload = await ttsSynthesize(input);
return json(
res,
200,
{ data: { ...payload, tier: 'free', free_remaining_today: Math.max(0, rl.remaining) } },
{ 'cache-control': 'no-store' },
);
} catch (e) {
return error(res, e.status || 502, e.code || 'provider_error', e.message);
}
});