Build voice into anything

Explore the API

Jump straight to the capability you need. Each card scrolls you to its reference.

Before you write any code, it helps to have a map of the platform. Everything in the API is built from a handful of primitives that compose together. Read this once and the rest of the reference will make sense.

How it all fits

Think of it as a stack. Voices are the bottom layer — every spoken output picks one. TTS and STT are the simplest products: text in / audio out, and audio in / text out. Agents sit on top and orchestrate both in real time — they transcribe what the caller says, reason with an LLM (optionally consulting a knowledge base), and speak the reply in your chosen voice. Attach a phone number and that same agent answers calls. While a conversation runs, webhooks notify your backend of key moments, and credits meter the whole thing.

Get from zero to your first response in three steps. You only need an API key and a single HTTP request — no SDK install required.

All requests are made to the versioned base URL below. Prefix every path you see in these docs with it.

The API supports two authentication methods, both passed via the Authorization: Bearer <token> header. Most data endpoints accept either. The same header shape works in every language:

API keys carry a list of scopes that gate which endpoints they can call. New keys default to agent:connect and agent:view. Request only the scopes your integration needs. (Super Admin keys bypass all scope checks.)

Retrieve the canonical list at runtime from GET /auth/api-keys/scopes.

Most errors return a single human-readable message under detail:

Validation failures (HTTP 422) return detail as an array of field-level errors, each with loc, msg and type:

Two independent limits protect the platform: short-term rate limits (requests per window) and plan-based quotas (monthly usage of TTS characters, STT minutes, etc.). Exceeding a rate limit returns 429; exceeding a plan quota returns 403 with an upgrade hint in detail.

Quick answers to the issues developers hit most often.

Exchange email + password for a JWT access token and refresh token.

Exchange a valid refresh token for a fresh access token.

Returns the authenticated user's profile.

A voice is a specific synthetic speaker — a named, gendered model in one language, served by the AgeOfAI Voice speech engine. Listing voices is almost always your first call: TTS needs a voice's numeric id, and when you build an agent you pick a voice too. The catalog spans 53+ languages, so filter the response by the language field to find the right speaker.

The field that identifies a voice to the speech engine is voice_key — an example value looks like hi-IN-isha-hd. The first part (hi-IN) is the BCP-47 language/region. Don't construct these by hand — use a real voice id from GET /voices.

Returns a single voice by its numeric ID — useful for confirming a voice still exists and reading its metadata before synthesizing.

Text-to-Speech follows an asynchronous job model, because rendering high-quality audio takes a moment. You don't get audio back from this call — you get a job record with a status of pending. The work happens in the background; you then poll until it's completed and download the file. This three-step rhythm — submit → poll → download — is the same for STT, so learn it once.

Requires the tts:generate scope on an API key. The body is JSON; the only truly required fields are voice_id and one of input_text / input_file. The prosody knobs (speaking_rate, pitch, volume_gain_db) are optional — leave them out for natural defaults, or nudge them to fit your brand (e.g. speaking_rate: 0.9 for a calmer read).

Poll a synthesis job by ID to check its status (pending → processing → completed / failed).

Download the finished audio file. Returns an audio/<format> binary stream once the synthesis is completed.

Speech-to-Text is the mirror image of TTS: you upload a recording (as multipart/form-data, max 100 MB) and get back a transcript. Like TTS it's an async job — this call returns a record with status PENDING, and you poll until COMPLETED to read the text. Requires the stt:transcribe scope.

Two engines back the service: AgeOfAI Speech (standard) (fast and private) and AgeOfAI Speech (enhanced) for the toughest audio. Leave provider_preference as default unless you have a reason to force one. If you know the spoken language, pass its ISO-639-1 code (e.g. en) — it improves accuracy and speed; omit it to auto-detect. Set diarize when you need "who said what" speaker labels.

Poll a transcription job by ID. The transcript field is populated once status reaches COMPLETED; the response also tells you which engine actually ran (engine) and the detected language.

An agent is a configurable, real-time voice bot. Where TTS and STT are one-shot, an agent holds a live conversation: it listens to the user, decides what to say with an LLM, and speaks back — over and over — until the call ends. It is the central object of the platform, and the one thing that pulls every other concept together.

A single agent bundles all of the following into one reusable configuration:

Once created, the same agent can be used in three places with no extra setup: embedded in your web app over WebRTC, in the dashboard test consoles, and on the telephone by attaching a phone number. Create once, deploy everywhere.

Every agent processes audio through one of two pipelines, set by the pipeline_mode field. They produce the same kind of conversation but make very different trade-offs. Choosing the right one is the most consequential decision after the prompt.

Both modes work in the browser and on the phone, and both can use a knowledge base. You can switch a live agent between modes at any time with PUT /agents/{id}, so it's easy to A/B them on the same prompt.

Returns all voice agents in the authenticated workspace. Requires agent:view with an API key.

Create a new voice agent. Requires the agent:manage scope. The voice_id is the agent voice's string UUID (not the numeric TTS voice ID).

Returns a single agent by ID. Requires agent:view.

Update any field on an existing agent. All fields are optional. Requires agent:manage.

Permanently delete an agent. Requires agent:manage.

Voice agents stream audio over WebRTC via Pipecat. The easiest integration is the @ageofai/vp-ui React component, which negotiates the peer connection for you. Connecting requires the agent:connect scope.

RAG (Retrieval-Augmented Generation) is how you make an agent knowledgeable about your specific content — your product docs, policies, price lists, FAQs — so it answers accurately instead of making things up. You don't fine-tune anything; you just upload documents into a knowledge base, and at conversation time the agent retrieves the passages most relevant to the question and grounds its answer in them.

Here's the lifecycle:

This endpoint handles steps 1–3 for a single file. Requires rag:manage. Max file size 50 MB. It accepts a wide range of formats — PDF, Office, OpenDocument, CSV/TSV, JSON, HTML, RTF, EML, images (OCR), and plain text/markdown — so most source material works as-is.

Fetch and ingest a document directly from a public URL — handy for web pages and hosted PDFs. Requires rag:manage.

List all documents in your knowledge base.

This is the retrieval step an agent performs automatically — but you can call it yourself to test what your documents will return before wiring them to an agent, or to build your own search experience. It runs a semantic (meaning-based, not keyword) search and returns the most relevant chunks with a similarity score and their source. Requires rag:query. To restrict the search to the documents attached to one agent, use POST /rag/agents/{agent_id}/query instead.

Remove a document and its embeddings from the knowledge base. Deletion is immediate — the agent will no longer retrieve from it on the next turn — so use this to keep answers fresh when source content changes.

Connect your voice agents to the telephone network. Import phone numbers (Twilio-backed), then place outbound calls that run an agent over the line, or receive inbound calls. Call audio is bridged through the same Standard or Realtime pipeline your agent uses. Number management requires phone:manage / phone:view; placing and viewing calls requires calls:manage / calls:view.

Returns the phone numbers imported into the authenticated workspace. Requires phone:view.

Dial a destination number and connect it to one of your agents. The call runs asynchronously — poll /calls/{id} or listen for the call-completed webhook for the outcome. Requires calls:manage.

Returns call logs for the workspace with status, duration, and recording references. Requires calls:view.

Billing is usage-based and metered in credits. Every paid operation — TTS characters synthesized, STT minutes transcribed, call seconds, etc. — debits your workspace's credit balance. These four endpoints let you observe and predict that spend: check your balance, see an aggregate summary, drill into individual records, and estimate a job's cost before you run it.

This endpoint returns the current credit balance for the authenticated workspace.

Aggregated usage across services for the current billing window.

Paginated log of individual metered operations and their credit cost.

Ask "what would this cost?" before committing. Pass the service and the number of units (e.g. characters for TTS) and get back a credit estimate. This is the safe way to size a large batch — estimate first, confirm you have the balance, then run.

Returns all API keys for the authenticated user. The full key value is never returned after creation.

Create a new API key. The full key value is returned only once — store it immediately. Maximum 10 keys per account.

Returns the canonical list of all 11 scopes and their descriptions. Useful for building a key-creation UI.

Revoke a key without deleting its record (keeps an audit trail). Revoked keys immediately fail authentication.

Permanently delete an API key. All requests using it fail immediately afterwards.

Webhooks push real-time events to your server. Agents can fire events on connect, disconnect, error, idle, and on a custom event you define (e.g. lead_captured). The platform also fires a call-completed webhook when a phone call ends. Every payload is JSON and HMAC-signed so you can verify it came from us.

Recompute the HMAC over the exact string {timestamp}.{raw_body} (the literal timestamp, a dot, then the raw request body) with your shared secret, and compare it to the X-Webhook-Signature header using a constant-time comparison. Use the raw, un-parsed body — re-serializing JSON will change the bytes and break the signature.

Register a webhook on an agent (or set webhook_url + webhook_secret when creating the agent). Choose which events fire: connected, disconnect, error, idle, plus one custom event per agent.

The smallest useful thing you can build: turn a sentence into an audio file. This walks the full async TTS rhythm — pick a voice, submit, poll, download.

Take a recording and get text back. Same async rhythm as TTS, but the upload is a multipart form.

Create a conversational agent and connect to it in the browser. This is the core of the platform — a real-time bot you can speak with.

Make your agent answer accurately from your own content. You'll upload a document, verify retrieval, and attach it to the agent.

Put an agent on the phone, dial a number, and reliably capture the outcome when the call ends — without polling — by handling the call-completed webhook.