Voice preview

Voice preview

Hear a voice before you ship it. Every preview endpoint returns a audio/wav body you can play directly — no polling, no job id.

There are two ways to preview, and they answer different questions:

All of them accept an API key (x-api-key) or a dashboard JWT.

Preview a saved agent

POST /api/agents/{id}/voice-preview

Loads the agent and auditions the configuration that is actually stored, using the same keys a live call would use. It also picks the engine the way a call does: if the agent's s2sConfig names a provider, you hear the realtime model — otherwise you hear its TTS voice. That matters, because a realtime agent never plays its ttsVoice, so previewing that field would play a voice the caller will never hear.

curl -X POST https://api.telenow.ai/api/agents/{id}/voice-preview \
  -H "x-api-key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hi, thanks for calling Acme. How can I help?"}' \
  --output preview.wav

The response body is the audio. Which engine answered comes back in headers, so the body stays playable:

These four are CORS-exposed, so browser clients can read them.

Check X-Voice-Engine when you expect a realtime agent: cascade means the agent will run the STT→LLM→TTS stack instead — usually because the realtime engine is not enabled on this deployment. This route deliberately mirrors what a call would do rather than refusing, so what you hear is always what the caller will hear.

If the agent's voice is a cloned voice, this route resolves it to the real provider voice — so the clone is what you hear, not a stand-in.

Preview a voice before saving

Use these while a user is still choosing — they take the settings in the request body and touch nothing stored.

Text-to-speech

POST /api/providers/tts/{provider}/preview

curl -X POST https://api.telenow.ai/api/providers/tts/elevenlabs/preview \
  -H "x-api-key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Acme.", "voice": "9BWtsMINqrJLrRacOk9x"}' \
  --output sample.wav

Realtime (speech-to-speech)

POST /api/providers/s2s/{provider}/preview

Opens one short real session with the engine and has the model speak your line, so what you hear is genuine realtime output rather than a TTS approximation.

curl -X POST https://api.telenow.ai/api/providers/s2s/openai/preview \
  -H "x-api-key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-realtime", "voice": "marin"}' \
  --output sample.wav

Returns 404 when the realtime engine is not enabled on the deployment — check enabled on GET /api/catalog/s2s first. (The by-agent route above does not: it falls through to the cascade, because that is what the agent's calls do.)

Rate limits and cost

Every preview opens a real provider session on a real key, so it costs money — your own when you pass a BYOK apiKey, the platform's otherwise. They are throttled per organization, independently for each kind:

Exceeding it returns 429 carrying a Retry-After header and a retryAfter field (whole seconds, rounded up) in the body. The two kinds are throttled independently, so auditioning a TTS voice never locks out the realtime picker.

Previews are meant to be driven by a person auditioning voices — build a picker, not a batch job. A read-only API key (role member or viewer) cannot call them at all, because a preview spends against a real vendor key. POST /api/agents/{id}/voice-preview additionally refuses when the org is suspended or out of credit. Previews themselves are not metered or billed per call — the throttle is the only ceiling, which is why it is strict. If you need bulk synthesis, use the App AI gateway (ai:tts), which is metered instead.

Errors

Related

• Agents API — configuring ttsVoice and s2sConfig
• Catalog & providers — discovering voices and realtime models
• Authentication — API keys and roles