Text-to-speech

The AI Reserve gateway exposes text-to-speech under /v1/audio/speech with the same API key, rate limits, wallet, and spend caps as every other route. Two providers sit behind one OpenAI-compatible request shape — pick a model and a voice:

Model	Provider	Best for	Max input	Price / 1M chars
`grok-tts`	xAI	Fast, inexpensive narration with the xAI voices	4,096	$15
`eleven-v4`	ElevenLabs	The most expressive, emotive speech; 90+ languages	10,000	$80
`eleven-v3`	ElevenLabs	Dramatic, performed delivery; 70+ languages	5,000	$80
`eleven-multilingual-v2`	ElevenLabs	Stable, consistent long-form audio; 29 languages	10,000	$80
`eleven-flash-v2-5`	ElevenLabs	Lowest latency and half the price; 32 languages	40,000	$40

Two layers of voices are available:

Built-in voices — the xAI voices (for grok-tts) and the ElevenLabs catalog (for the eleven-* models): ElevenLabs’ premade library plus the professional Voice Library voices the platform has added. Usable by any caller, no org gate required.
Custom voices — clones of consented speakers, owned and namespaced by your organization (org-gated, xAI Enterprise contract required; synthesized with grok-tts).

Custom voices are available on request. The full CRUD surface (POST /v1/custom-voices and all /v1/custom-voices/{voiceId} routes) requires the customVoicesEnabled org gate to be on for your organization and an xAI Enterprise contract on the platform. Contact your AI Reserve representative to enable both. Until enabled, custom-voice endpoints return 403.Speech synthesis (POST /v1/audio/speech) with built-in voices is available to any org. Custom voices additionally require customVoicesEnabled.

Built-in voices

GET /v1/voices returns the live catalog of voices you can pass as voice in any TTS call (xAI voices also drive realtime sessions). Every entry carries a provider (grok or elevenlabs) and the models it can be synthesized with, so you can pick a voice and a model together. No org gate — available to every caller.

curl https://api.aireserve.com/v1/voices \
  -H "Authorization: Bearer $AIRESERVE_API_KEY"

const response = await fetch("https://api.aireserve.com/v1/voices", {
  headers: { Authorization: `Bearer ${process.env.AIRESERVE_API_KEY}` },
});
const { voices } = await response.json();

import os, requests

response = requests.get(
    "https://api.aireserve.com/v1/voices",
    headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
)
voices = response.json()["voices"]

The response is

{ "voices": [ { "voice_id": "ara", "name": "Ara", "language": "en", "gender": "female", "provider": "grok", "models": ["grok-tts"] }, { "voice_id": "JBFqnCBsd6RMkjVDRZzb", "name": "George", "gender": "male", "accent": "British", "category": "premade", "provider": "elevenlabs", "models": ["eleven-v4", "eleven-v3", "eleven-multilingual-v2", "eleven-flash-v2-5"] }, … ] }

. Each provider’s list is cached for 5 minutes and a stale list is served during brief upstream outages rather than an error — an outage at one provider never hides the other’s voices. Use GET /v1/voices for the current catalog. ElevenLabs voices may be addressed by voice_id or by name (case-insensitive, e.g. "voice": "George"); xAI voices by voice_id (ara is the default). An ElevenLabs voice_id that is not in the catalog answers 404 — the catalog is the premade library and the platform’s Voice Library picks, never a voice cloned or designed on the shared platform account.

Text-to-speech synthesis

POST /v1/audio/speech synthesizes speech from text. The call is synchronous — the full audio is returned in one response body. The response Content-Type matches response_format (audio/mpeg by default).

Parameters

Field	Required	Description
`model`	yes	`grok-tts`, `eleven-v4`, `eleven-v3`, `eleven-multilingual-v2` or `eleven-flash-v2-5`
`input`	yes	Text to synthesize, counted in Unicode code points — max 4,096 for `grok-tts`, 10,000 for `eleven-v4` / `eleven-multilingual-v2`, 5,000 for `eleven-v3`, 40,000 for `eleven-flash-v2-5`
`voice`	yes	Built-in voice ID (ElevenLabs voices also accept their `name`) or your organization’s custom voice ID (`grok-tts` only)
`language`	no	Language hint (e.g. `en`, `en-US`, `es`). xAI: defaults to the voice’s primary language. ElevenLabs: sent as an ISO 639-1 `language_code` where the model accepts one; `eleven-multilingual-v2` detects it
`response_format`	no	`grok-tts`: `mp3` only. `eleven-*`: `mp3` (44.1 kHz / 128 kbps), `opus` (48 kHz), `pcm` (24 kHz 16-bit mono) or `wav` (24 kHz). Defaults to `mp3`
`speed`	no	Playback speed 0.7–1.2, ElevenLabs models only (1.0 is normal)

Quickstart

curl https://api.aireserve.com/v1/audio/speech \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-tts","input":"Welcome to AI Reserve.","voice":"ara"}' \
  --output speech.mp3

const response = await fetch("https://api.aireserve.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRESERVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-tts",
    input: "Welcome to AI Reserve.",
    voice: "ara",
  }),
});
// response body is raw MP3 bytes
const buffer = Buffer.from(await response.arrayBuffer());
await Bun.write("speech.mp3", buffer);

import os, requests

response = requests.post(
    "https://api.aireserve.com/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
    json={"model": "grok-tts", "input": "Welcome to AI Reserve.", "voice": "ara"},
)
with open("speech.mp3", "wb") as f:
    f.write(response.content)

ElevenLabs example

Same request shape — choose an eleven-* model and an ElevenLabs voice (by name or voice_id). eleven-flash-v2-5 is the pick for real-time chat (lowest latency, half the price); eleven-v4 for the most expressive delivery.

curl https://api.aireserve.com/v1/audio/speech \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"eleven-flash-v2-5","input":"Welcome to AI Reserve.","voice":"George","response_format":"mp3"}' \
  --output speech.mp3

const response = await fetch("https://api.aireserve.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRESERVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "eleven-v4",
    input: "Welcome to AI Reserve.",
    voice: "George",
    speed: 1.0,
  }),
});
await Bun.write("speech.mp3", Buffer.from(await response.arrayBuffer()));

import os, requests

response = requests.post(
    "https://api.aireserve.com/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
    json={"model": "eleven-v4", "input": "Welcome to AI Reserve.", "voice": "George"},
)
with open("speech.mp3", "wb") as f:
    f.write(response.content)

Billing

Billed per Unicode code point in input at the model’s published rate: grok-tts $15 / 1 M characters; `eleven-v4`, `eleven-v3` and `eleven-multilingual-v2` $80 / 1 M; eleven-flash-v2-5 $40 / 1 M (ElevenLabs’ public API card, billed in USD). The character count is known before synthesis begins, so the wallet reservation equals the settlement amount — no post-call adjustment.

Limits and notes

Input length: per-model ceilings above. For longer text, split at sentence boundaries and concatenate the returned audio on your side.
Output format: grok-tts emits MP3 only; the ElevenLabs models emit mp3, opus, pcm or wav. Streaming TTS is deferred — see Deferred features.
Request timeout: 120 seconds. Long inputs near a model’s ceiling may take tens of seconds; set your HTTP client timeout accordingly.
Content: ElevenLabs’ terms of service prohibit sexually explicit and certain other content; requests that violate them are rejected by the provider. Use grok-tts for voices in those products.
Auth requirement: a client-scoped API key is required (personal keys without org context are rejected with 403).

Custom voices

Custom voices are speaker clones your organization creates from reference audio. Once created, a custom voice ID can be used anywhere a built-in voice ID is accepted: POST /v1/audio/speech and POST /v1/realtime/sessions.

Requirements

Requirement	Detail
Org gate	`customVoicesEnabled` must be on for your organization — off by default
xAI Enterprise	An xAI Enterprise contract is required on the platform; `POST /custom-voices` returns a shaped `403` until it is active
Consent	`consent_attestation=true` is required on every create — you attest the speaker consented to the clone
Geography	Voice cloning is available in the United States except Illinois; do not upload voices from Illinois or create voices whose use would violate biometric, publicity, privacy, or impersonation laws

Reference audio recommendations

The quality of the clone depends heavily on the recording:

Format: single-speaker mono WAV at 24 kHz
Duration: 90–120 seconds produces the best results; at least 30 seconds is recommended
Environment: quiet room, no background music, minimal noise
Upload limit: 31 MB (bounds a 120-second uncompressed WAV with multipart overhead)
Duration ceiling: 120 seconds (enforced upstream by xAI)

Create a custom voice

POST /v1/custom-voices is multipart/form-data. Required fields are name, language, file, and consent_attestation=true.

curl -X POST https://api.aireserve.com/v1/custom-voices \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -F "name=Product narrator" \
  -F "language=en-US" \
  -F "tone=warm" \
  -F "use_case=narration" \
  -F "consent_attestation=true" \
  -F "file=@reference.wav;type=audio/wav"

const form = new FormData();
form.set("name", "Product narrator");
form.set("language", "en-US");
form.set("tone", "warm");
form.set("use_case", "narration");
form.set("consent_attestation", "true");
form.set("file", new Blob([await Bun.file("reference.wav").arrayBuffer()], { type: "audio/wav" }), "reference.wav");

const response = await fetch("https://api.aireserve.com/v1/custom-voices", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AIRESERVE_API_KEY}` },
  body: form,
});
const voice = await response.json();
// voice.voice_id is the 8-character ID to use in /audio/speech

import os, requests

with open("reference.wav", "rb") as audio:
    response = requests.post(
        "https://api.aireserve.com/v1/custom-voices",
        headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
        files={"file": ("reference.wav", audio, "audio/wav")},
        data={
            "name": "Product narrator",
            "language": "en-US",
            "tone": "warm",
            "use_case": "narration",
            "consent_attestation": "true",
        },
    )
voice = response.json()
# voice["voice_id"] is the 8-character ID to use in /audio/speech

A successful create returns 201 with the voice object including voice_id — an 8-character lowercase alphanumeric ID assigned by xAI. Optional metadata fields: description (free text), gender (male / female / neutral), accent, age (young / middle-aged / old), use_case (conversational / narration / characters / educational / advertisement / social_media / entertainment), tone (warm / casual / professional / friendly / authoritative / expressive / calm).

Manage custom voices

Operation	Endpoint	Notes
List your voices	`GET /v1/custom-voices`	Returns your org’s ownership map, never xAI’s team-wide list
Read one voice	`GET /v1/custom-voices/{voiceId}`	Refreshes from upstream on every call
Update metadata	`PATCH /v1/custom-voices/{voiceId}`	At least one field required; `name` cannot be `null`
Delete a voice	`DELETE /v1/custom-voices/{voiceId}`	Removes from xAI and soft-deletes the ownership record; idempotent

curl https://api.aireserve.com/v1/custom-voices \
  -H "Authorization: Bearer $AIRESERVE_API_KEY"

curl -X PATCH https://api.aireserve.com/v1/custom-voices/ab3f9c2e \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Warm narrator v2","tone":"warm"}'

curl -X DELETE https://api.aireserve.com/v1/custom-voices/ab3f9c2e \
  -H "Authorization: Bearer $AIRESERVE_API_KEY"

Tenant isolation

Every custom voice lives on the platform’s single xAI team — xAI cannot separate one organization’s voices from another’s at the team level. AI Reserve enforces tenant isolation through an ownership map: every id-addressed operation checks that the voice is owned by the calling organization. A voice ID owned by a different organization returns 404 — the same response as a nonexistent ID. Voice existence is never confirmed cross-tenant.

Capacity

The shared upstream capacity is currently 200 live custom voices across the platform. Delete an unused voice or contact support when POST /v1/custom-voices returns 409; the API does not expose other organizations or their usage of the shared capacity. Larger allocations are available on request.

Data handling

Reference audio uploaded to create a custom voice is transmitted to xAI, which builds and stores the resulting voice model. AI Reserve stores only the ownership record and consent attestation — no reference audio is retained by AI Reserve. See the provider data handling page for details.

Click-to-copy snippets in the portal

The AI Reserve portal’s Voice workspace surfaces the same API operations with a click-to-copy UI: browse the catalog, preview voices, manage your organization’s custom voices, and copy the exact code snippet for any operation. The portal snippets match the endpoints documented here — there is no separate portal-only API.

Deferred features

The following are not available in this release:

Streaming TTS: real-time audio streaming from text input. Use POST /v1/realtime/sessions (speech-to-speech) for live voice sessions.
Standalone speech-to-text: transcription-only calls without synthesis. See POST /v1/audio/transcriptions for the existing OpenAI-compatible transcription endpoint.
SIP / telephony integration: direct PSTN or SIP dial-in/dial-out.
Tool calling over TTS: function calling is not available on the grok-tts surface.

Getting started

Connect your tool

GPU Infrastructure

AWS Hub

Capabilities

Migrate

Performance

Data & privacy

Reliability

Built-in voices

Text-to-speech synthesis

Parameters

Quickstart

ElevenLabs example

Billing

Limits and notes

Custom voices

Requirements

Reference audio recommendations

Create a custom voice

Manage custom voices

Tenant isolation

Capacity

Data handling

Click-to-copy snippets in the portal

Deferred features

​Built-in voices

​Text-to-speech synthesis

​Parameters

​Quickstart

​ElevenLabs example

​Billing

​Limits and notes

​Custom voices

​Requirements

​Reference audio recommendations

​Create a custom voice

​Manage custom voices

​Tenant isolation

​Capacity

​Data handling

​Click-to-copy snippets in the portal

​Deferred features

Built-in voices

Text-to-speech synthesis

Parameters

Quickstart

ElevenLabs example

Billing

Limits and notes

Custom voices

Requirements

Reference audio recommendations

Create a custom voice

Manage custom voices

Tenant isolation

Capacity

Data handling

Click-to-copy snippets in the portal

Deferred features