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
// Unit tests for the multi-provider voice registry (api/_lib/voice-providers.js)
// and the Gemini TTS lane (api/_lib/tts-gemini.js).
//
// fetch and the GCP token minter are mocked so these run with no network and no
// credentials. They pin the contract /api/tts/catalog and /api/tts/synthesize
// depend on: which lanes exist, which are free, what each lane's catalog looks
// like, and that a lane's failure is tagged with a code the router can map to
// an HTTP status.
import { vi, describe, it, expect, beforeEach, afterAll } from 'vitest';
const { getGcpAccessToken } = vi.hoisted(() => ({ getGcpAccessToken: vi.fn() }));
vi.mock('../api/_lib/gcp-auth.js', () => ({ getGcpAccessToken }));
import {
VOICE_PROVIDERS,
PROVIDER_IDS,
getProvider,
providerAvailability,
providerModels,
providerDefaultVoice,
usdForSynthesis,
creditActionFor,
listProviderVoices,
synthesizeVoice,
} from '../api/_lib/voice-providers.js';
import {
GEMINI_VOICES,
GEMINI_DEFAULT_VOICE,
isGeminiVoice,
synthesizeGeminiTts,
geminiTtsConfigured,
} from '../api/_lib/tts-gemini.js';
import { TTS_ELEVEN_USD_PER_1K, TTS_OPENAI_USD_PER_1K } from '../api/_lib/pricing/catalog.js';
const realFetch = global.fetch;
const savedEnv = { ...process.env };
afterAll(() => {
global.fetch = realFetch;
process.env = savedEnv;
});
beforeEach(() => {
global.fetch = vi.fn();
getGcpAccessToken.mockReset();
for (const key of [
'GOOGLE_CLOUD_PROJECT',
'GOOGLE_CLOUD_LOCATION_TTS',
'GEMINI_API_KEY',
'GOOGLE_API_KEY',
'OPENAI_API_KEY',
'NVIDIA_API_KEY',
'ELEVENLABS_API_KEY',
]) {
delete process.env[key];
}
});
/** A generateContent response carrying `bytes` of PCM. */
function geminiAudioResponse(bytes = 32) {
return {
ok: true,
status: 200,
json: async () => ({
candidates: [
{ content: { parts: [{ inlineData: { data: Buffer.alloc(bytes, 7).toString('base64') } }] } },
],
}),
};
}
describe('registry shape', () => {
it('exposes every lane the platform ships', () => {
expect(PROVIDER_IDS).toEqual(['edge', 'gemini', 'nvidia', 'openai', 'elevenlabs']);
});
it('gives every lane the fields a picker renders', () => {
for (const p of VOICE_PROVIDERS) {
expect(typeof p.label).toBe('string');
expect(typeof p.tagline).toBe('string');
expect(['free', 'gcp', 'credits']).toContain(p.billing);
expect(typeof p.anonymous).toBe('boolean');
}
});
it('returns null for an unknown provider', () => {
expect(getProvider('nope')).toBeNull();
});
});
describe('availability', () => {
it('keeps the keyless Edge lane on with no env at all', () => {
expect(providerAvailability().edge).toBe(true);
});
it('gates the keyed lanes on their credentials', () => {
expect(providerAvailability()).toMatchObject({
gemini: false,
nvidia: false,
openai: false,
elevenlabs: false,
});
process.env.OPENAI_API_KEY = 'sk-test';
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'proj';
process.env.ELEVENLABS_API_KEY = 'sk_test';
expect(providerAvailability()).toMatchObject({
gemini: true,
nvidia: true,
openai: true,
elevenlabs: true,
});
});
it('counts a user-supplied ElevenLabs key as availability', () => {
expect(providerAvailability({ elevenUserKey: true }).elevenlabs).toBe(true);
});
});
describe('billing', () => {
it('never charges for a free or GCP-credit lane', () => {
for (const provider of ['edge', 'gemini', 'nvidia']) {
expect(usdForSynthesis({ provider, chars: 100_000 })).toBe(0);
expect(creditActionFor(provider)).toBeNull();
}
});
it('meters the vendor-billed lanes per 1k characters', () => {
expect(usdForSynthesis({ provider: 'elevenlabs', chars: 1000 })).toBeCloseTo(
TTS_ELEVEN_USD_PER_1K,
6,
);
expect(usdForSynthesis({ provider: 'openai', chars: 1000 })).toBeCloseTo(
TTS_OPENAI_USD_PER_1K,
6,
);
expect(creditActionFor('elevenlabs')).toBe('tts.eleven');
expect(creditActionFor('openai')).toBe('tts.openai');
});
it('charges a floor rather than zero for a very short clip', () => {
expect(usdForSynthesis({ provider: 'openai', chars: 1 })).toBeGreaterThan(0);
});
it('bypasses the charge entirely for BYOK', () => {
expect(usdForSynthesis({ provider: 'elevenlabs', chars: 5000, byok: true })).toBe(0);
});
});
describe('catalogs', () => {
it('lists all 30 Gemini prebuilt voices with a character each', async () => {
const voices = await listProviderVoices('gemini');
expect(voices).toHaveLength(30);
expect(voices.every((v) => v.provider === 'gemini' && v.labels.description)).toBe(true);
expect(isGeminiVoice(GEMINI_DEFAULT_VOICE)).toBe(true);
expect(isGeminiVoice('NotAVoice')).toBe(false);
expect(GEMINI_VOICES).toHaveLength(30);
});
it('lists the OpenAI voice set', async () => {
const voices = await listProviderVoices('openai');
expect(voices.length).toBeGreaterThan(0);
expect(voices.map((v) => v.id)).toContain('nova');
});
it('lists only the NVIDIA voices Magpie actually maps', async () => {
const voices = await listProviderVoices('nvidia');
expect(voices.every((v) => v.labels.persona)).toBe(true);
});
it('returns an empty ElevenLabs catalog rather than throwing with no key', async () => {
expect(await listProviderVoices('elevenlabs')).toEqual([]);
});
it('returns an empty list for an unknown provider', async () => {
expect(await listProviderVoices('nope')).toEqual([]);
});
it('reports the models and default voice a lane offers', () => {
expect(providerModels('gemini').length).toBeGreaterThan(0);
expect(providerModels('edge')).toEqual([]);
expect(providerDefaultVoice('edge')).toBe('en-US-AriaNeural');
expect(providerDefaultVoice('gemini')).toBe(GEMINI_DEFAULT_VOICE);
});
});
describe('gemini synthesis', () => {
it('is unconfigured without a project or a key', () => {
expect(geminiTtsConfigured()).toBe(false);
});
it('accepts GOOGLE_API_KEY as well as GEMINI_API_KEY', async () => {
process.env.GOOGLE_API_KEY = 'gk-test';
expect(geminiTtsConfigured()).toBe(true);
global.fetch.mockResolvedValue(geminiAudioResponse());
const out = await synthesizeGeminiTts({ text: 'hello' });
expect(out.lane).toBe('api-key');
expect(out.contentType).toBe('audio/wav');
// 44-byte RIFF header wrapped around the PCM.
expect(out.audio.subarray(0, 4).toString()).toBe('RIFF');
});
it('prefixes the direction onto the prompt', async () => {
process.env.GEMINI_API_KEY = 'gk-test';
global.fetch.mockResolvedValue(geminiAudioResponse());
await synthesizeGeminiTts({ text: 'hello', direction: 'slowly and low' });
const body = JSON.parse(global.fetch.mock.calls[0][1].body);
expect(body.contents[0].parts[0].text).toBe('Say the following, slowly and low: hello');
expect(body.generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName).toBe(
GEMINI_DEFAULT_VOICE,
);
});
it('falls back from Vertex to the API key rung', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'proj';
process.env.GEMINI_API_KEY = 'gk-test';
getGcpAccessToken.mockResolvedValue('ya29.token');
global.fetch
.mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
.mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
.mockResolvedValueOnce(geminiAudioResponse());
const out = await synthesizeGeminiTts({ text: 'hello' });
// Both Vertex regions 404 before the key rung serves.
expect(out.lane).toBe('api-key');
expect(global.fetch).toHaveBeenCalledTimes(3);
});
it('stops trying regions once auth is the problem', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'proj';
getGcpAccessToken.mockResolvedValue('ya29.token');
global.fetch.mockResolvedValue({ ok: false, status: 403, text: async () => 'denied' });
await expect(synthesizeGeminiTts({ text: 'hello' })).rejects.toThrow(/Gemini TTS failed/);
expect(global.fetch).toHaveBeenCalledTimes(1);
});
it('keeps a safety block distinct from a provider error', async () => {
process.env.GEMINI_API_KEY = 'gk-test';
global.fetch.mockResolvedValue({
ok: true,
status: 200,
json: async () => ({ promptFeedback: { blockReason: 'SAFETY' }, candidates: [] }),
});
await expect(synthesizeGeminiTts({ text: 'hello' })).rejects.toMatchObject({
code: 'content_blocked',
});
});
it('retries without the direction when the model answers instead of speaking', async () => {
process.env.GEMINI_API_KEY = 'gk-test';
global.fetch
.mockResolvedValueOnce({
ok: false,
status: 400,
text: async () =>
'{"error":{"message":"Model tried to generate text, but it should only be used for TTS."}}',
})
.mockResolvedValueOnce(geminiAudioResponse());
const out = await synthesizeGeminiTts({ text: 'hello', direction: 'brightly' });
expect(out.lane).toBe('api-key');
// The retry drops the style framing so the transcript is unambiguous.
expect(JSON.parse(global.fetch.mock.calls[1][1].body).contents[0].parts[0].text).toBe('hello');
});
it('does not retry the same prompt when there was no direction to drop', async () => {
process.env.GEMINI_API_KEY = 'gk-test';
global.fetch.mockResolvedValue({
ok: false,
status: 400,
text: async () => 'Model tried to generate text, but it should only be used for TTS.',
});
await expect(synthesizeGeminiTts({ text: 'hello' })).rejects.toMatchObject({
code: 'answered_instead_of_spoke',
});
expect(global.fetch).toHaveBeenCalledTimes(1);
});
it('keeps a quota failure distinct so the caller can answer 429', async () => {
process.env.GEMINI_API_KEY = 'gk-test';
global.fetch.mockResolvedValue({ ok: false, status: 429, text: async () => 'quota' });
await expect(synthesizeGeminiTts({ text: 'hello' })).rejects.toMatchObject({
code: 'rate_limited',
});
});
});
describe('router', () => {
it('rejects an unknown provider with invalid_argument', async () => {
await expect(synthesizeVoice({ provider: 'nope', text: 'hi' })).rejects.toMatchObject({
code: 'invalid_argument',
});
});
it('rejects empty text before touching a lane', async () => {
await expect(synthesizeVoice({ provider: 'edge', text: ' ' })).rejects.toMatchObject({
code: 'invalid_argument',
});
expect(global.fetch).not.toHaveBeenCalled();
});
it('requires an ElevenLabs key', async () => {
await expect(
synthesizeVoice({ provider: 'elevenlabs', text: 'hi', voiceId: 'v1' }),
).rejects.toMatchObject({ code: 'not_configured' });
});
it('requires a voiceId for ElevenLabs', async () => {
await expect(
synthesizeVoice({ provider: 'elevenlabs', text: 'hi', elevenKey: 'sk_x' }),
).rejects.toMatchObject({ code: 'invalid_argument' });
});
it('sends only a supported OpenAI direction and clamps speed', async () => {
process.env.OPENAI_API_KEY = 'sk-test';
global.fetch.mockResolvedValue({
ok: true,
status: 200,
arrayBuffer: async () => new ArrayBuffer(16),
});
await synthesizeVoice({
provider: 'openai',
text: 'hi',
voiceId: 'nova',
model: 'tts-1',
direction: 'whisper it',
speed: 9,
});
const body = JSON.parse(global.fetch.mock.calls[0][1].body);
expect(body.instructions).toBeUndefined(); // tts-1 rejects instructions
expect(body.speed).toBe(2);
global.fetch.mockClear();
await synthesizeVoice({
provider: 'openai',
text: 'hi',
voiceId: 'nova',
model: 'gpt-4o-mini-tts',
direction: 'whisper it',
});
expect(JSON.parse(global.fetch.mock.calls[0][1].body).instructions).toBe('whisper it');
});
it('falls back to a valid OpenAI voice rather than forwarding a bad one', async () => {
process.env.OPENAI_API_KEY = 'sk-test';
global.fetch.mockResolvedValue({
ok: true,
status: 200,
arrayBuffer: async () => new ArrayBuffer(16),
});
const out = await synthesizeVoice({ provider: 'openai', text: 'hi', voiceId: 'not-a-voice' });
expect(out.voiceId).toBe('nova');
});
it('maps an OpenAI 429 to rate_limited', async () => {
process.env.OPENAI_API_KEY = 'sk-test';
global.fetch.mockResolvedValue({ ok: false, status: 429, text: async () => 'slow down' });
await expect(
synthesizeVoice({ provider: 'openai', text: 'hi', voiceId: 'nova' }),
).rejects.toMatchObject({ code: 'rate_limited' });
});
it('maps an ElevenLabs 401 to invalid_key', async () => {
global.fetch.mockResolvedValue({ ok: false, status: 401, text: async () => 'bad key' });
await expect(
synthesizeVoice({ provider: 'elevenlabs', text: 'hi', voiceId: 'v1', elevenKey: 'sk_x' }),
).rejects.toMatchObject({ code: 'invalid_key' });
});
});