Play Speakvora speech in a browser safely

Call /v1/speak from your backend and pass the audio URL to the browser. Agent tokens work in the browser directly but are limited to agents.

Short answer. To play Speakvora speech in a browser without exposing your API key, call /v1/speak from your backend and send the audio URL to the browser. If you are using voice agents, you can issue a 10-minute browser token instead and let the browser call the agent endpoint directly.

Why not call /v1/speak from the browser

Plain /v1/speak rejects scoped keys, so your full API key must stay on your server, not in client-side code or network requests that a user can inspect.

Backend-to-browser flow for catalog voices

Call POST /v1/speak from your backend with your API key. The response includes a public audio URL that you can safely pass to the browser. The browser then fetches and plays the audio.

The audio URL is unguessable and reusable for the same text and voice. Catalog audio is cached with a one-year lifetime, so repeated requests for the same phrase are instant.

Backend calls /v1/speak

const response = await fetch('https://speakvora.com/api/v1/speak', {
  method: 'POST',
  headers: { 'x-api-key': process.env.SPEAKVORA_KEY },
  body: JSON.stringify({
    text: 'Welcome to our app',
    voice: 'af_heart',
    lang: 'en'
  })
});
const { url } = await response.json();
// Send url to browser

Browser plays the audio URL

Once your backend sends the URL, the browser can play it with an audio element or fetch it directly. No API key is needed.

Browser plays the audio

const audio = new Audio(audioUrl);
audio.play();

Agent tokens for browser-based agents

If you are building a voice agent, use agent-scoped keys instead. Call POST /v1/agents/{id}/sessions with your agent key to get a browser token valid for 10 minutes. The browser then sends this token in the Authorization header to reach only that agent.

Agent tokens are restricted to a single agent and cannot access /v1/speak or other endpoints.

Backend: POST /v1/agents/{id}/sessions with agent key → returns a token
Browser: send Authorization: Bearer <token> with agent turn requests
Token expires after 10 minutes; request a new one if needed

API key scoping and security

You can create up to 5 API keys per account. Agent-scoped keys can only reach their assigned agent and cannot call /v1/speak. Keep all API keys in environment variables or a secure secrets manager.

Billing

Each account receives 100,000 free characters. Calls to /v1/speak are billed by character, whether the text is in the library or generated live. Agent turns are billed at $10 per 1,000 turns after 200 free turns per account.

Frequently asked questions

Can I call /v1/speak directly from JavaScript in the browser?

No. Plain /v1/speak rejects scoped keys, so you must call it from your backend and pass the audio URL to the browser.

What are browser tokens and when do I use them?

Browser tokens are 10-minute credentials for voice agents only. Call POST /v1/agents/{id}/sessions with your agent key to issue a token, then the browser can send agent turns with that token in the Authorization header.

Is the audio URL safe to send to the browser?

Yes. Audio URLs are public, unguessable, and reusable for the same text and voice. They do not expose your API key. Catalog audio is cached for one year.

How long does a browser token last?

10 minutes. Request a new token from your backend when it expires.

Can an agent-scoped key call /v1/speak?

No. Agent-scoped keys can only reach their assigned agent. Use a full API key for /v1/speak, but keep it on your backend.