API Documentation

Quick Start

curl -X POST https://easyvoice.ae/api/v1/audio/speech \
  -H "Authorization: Bearer ev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kokoro-82m",
    "input": "Hello, this is EasyVoice!",
    "voice": "af_aoede"
  }' \
  --output speech.mp3

This runs as-is with a free key — af_aoede is one of the 12 free voices. Create a free account, generate a key on the API keys page, paste it in. No card.

Prefer tools over raw HTTP? EasyVoice is also a hosted MCP server — speech, long-form narration, podcast episodes, and voice cloning from any MCP-capable agent, authenticated with these same ev_ keys. Connection instructions for Claude, ChatGPT, and Cursor live at /mcp; the TTS MCP server explainer covers what agents can do with it.

Agent framework compatibility

Tested request-shape/auth compatibility against base_url + Bearer key, live against production, 2026-09-15:

• OpenAI Python SDK (2.54.0 & 3.13.0) — worked. Both versions return an identical, clean, typed openai.AuthenticationError on an invalid key. No gap found.
• LiveKit Agents' openai.TTS (livekit-agents 1.8.1) — worked, with both the plugin's default model (gpt-4o-mini-tts) and tts-1 explicit. Clean typed openai.APIStatusError, no retry storm.
• Pipecat OpenAITTSService (pipecat-ai 1.10.0) — failed-with-evidence: an auth failure propagates as an uncaught exception rather than a graceful error frame (client-side bug, confirmed live). Its voice-id allowlist also rejects non-OpenAI voice names before any network call.

Audio-byte format compatibility (Pipecat's pcm/mp3 assumption, LiveKit's SSE-vs-non-SSE default) is untested — these tests used a synthetic invalid key, so every request short-circuits at a 401 before the response body is ever produced. Full detail: 118-COMPAT-TEST.md (not public).

POST /api/v1/audio/speech

Generate speech from text. Returns audio file directly.

Headers

Body Parameters

EasyVoice Extensions

EasyVoice adds optional audio controls on top of the OpenAI-compatible request. On the public POST /v1/audio/speech endpoint these use an ev_ prefix. All are optional and default to a no-op, so standard OpenAI clients that omit them receive identical output to before. These are deterministic audio/voicing controls (pitch shift, output gain, and EQ tone presets) — not generative effects.

Audio parameters

On the web app (POST /api/tts/generate) the same controls are sent without the prefix: pitch, volume_db, and tone (same ranges and defaults). Out-of-range values are rejected with 400.

Example request

curl -X POST https://easyvoice.ae/api/v1/audio/speech \
  -H "Authorization: Bearer ev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kokoro-82m",
    "input": "Take a breath. <break time=\"500ms\"/> Now continue.",
    "voice": "af_aoede",
    "ev_pitch": 2,
    "ev_volume_db": -1.5,
    "ev_tone": "warm"
  }' \
  --output speech.mp3

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="ev_your_api_key",
    base_url="https://easyvoice.ae/api/v1"
)

response = client.audio.speech.create(
    model="kokoro-82m",
    voice="af_aoede",
    input="Hello from EasyVoice!"
)

response.stream_to_file("output.mp3")

Node.js Example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "ev_your_api_key",
  baseURL: "https://easyvoice.ae/api/v1"
});

const mp3 = await client.audio.speech.create({
  model: "kokoro-82m",
  voice: "af_aoede",
  input: "Hello from EasyVoice!"
});

const buffer = Buffer.from(await mp3.arrayBuffer());
await fs.promises.writeFile("output.mp3", buffer);

Plans, Rate Limits & Fair Use

Fair use, in plain words: Pro is unlimited for real products and real audiences — narrate your videos, your app, your audiobooks without counting characters. 10,000,000 API characters a month is roughly 180+ hours of finished audio; past that we may throttle to protect other users before we ever bill you. No overage charges, ever. Reselling raw API capacity is the one thing fair use excludes. Past 10,000,000/mo we may deprioritize your jobs in the shared queue — you keep working, just not first in line. Never a surprise bill, never a mid-job lockout. (disclosure — enforcement not yet active) Selling what you make? See the full commercial-rights breakdown → /license.

When you hit a limit the API returns a structured 429 with a Retry-After header: rate_limit_exceeded (per-minute window), concurrency_limit_exceeded (too many in flight), or daily_quota_exceeded (free daily pool spent — reset_at in the body tells you when it refills). Requesting a Pro voice with a free key returns naming the voice.

Common errors

The four classified error codes any of EasyVoice's API surfaces can return, with the exact current server message and a link to the relevant section on this page.

Available Voices

66 voices across 9 languages. Use the voice ID in your API requests.

Free API keys include 12 voices: af_aoede, af_heart, af_bella, af_nova, af_sky, am_adam, am_eric, am_michael, bf_emma, bm_daniel, plus Arabic ar_m1 and ar_f1. The other 54 return 403 plan_required on a free key.

See the voice browser for the full list with audio previews.

Arabic voices: ar_m1–ar_m5 and ar_f1–ar_f5 work directly in POST /v1/audio/speech. Arabic numerals, dates, and AED amounts are normalized to spoken form automatically. See Arabic text to speech.

Pro subscribers can also use cloned voice IDs (e.g. voice_abc123) returned by the GET /v1/voices endpoint.

Enroll, list, and delete custom voice clones. Cloned voice IDs can be used directly in POST /v1/audio/speech requests. Requires a Pro subscription and explicit consent for each enrolled voice.

POST /api/v1/voices — Enroll a voice clone

Multipart form upload. Returns 202 with {voice_id, status:"enrolling"}. Enrollment typically completes in 1–2 minutes; poll GET /v1/voices for status.

curl -X POST https://easyvoice.ae/api/v1/voices \
  -H "Authorization: Bearer ev_your_api_key" \
  -F "name=My Voice" \
  -F "consent=true" \
  -F "audio=@sample.wav"

GET /api/v1/voices — List voice clones

Returns all cloned voices for the authenticated user. Use status === "ready" voices in speech requests.

curl https://easyvoice.ae/api/v1/voices \
  -H "Authorization: Bearer ev_your_api_key"

# Response:
# {
#   "voices": [
#     { "id": "voice_abc123", "name": "My Voice", "status": "ready", "createdAt": 1234567890 }
#   ]
# }

Async Jobs API

For long inputs, submit an asynchronous job instead of waiting on the synchronous endpoint. Jobs are queued, processed, and the result is fetched by polling. Works with any voice ID, including Arabic and cloned voices. API-key access to the Jobs API requires Pro — free keys use the synchronous /v1/audio/speech endpoint above.

POST /api/v1/jobs — Submit a TTS job

curl -X POST https://easyvoice.ae/api/v1/jobs \
  -H "Authorization: Bearer ev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "A long article text...",
    "voice": "af_aoede",
    "format": "mp3"
  }'

# 202 Accepted
# { "id": "1f6f7c2e-...", "status": "queued" }

GET /api/v1/jobs/{id} — Poll job status

curl https://easyvoice.ae/api/v1/jobs/1f6f7c2e-... \
  -H "Authorization: Bearer ev_your_api_key"

# { "id": "1f6f7c2e-...", "status": "completed",
#   "audio_url": "/audio/....mp3", "created_at": ..., "completed_at": ... }

Statuses: queued → active → completed / failed. Jobs are visible only to the account that created them.

Optional: callback_url (webhook on completion)

Add callback_url to a job submission (long-form or podcast) and EasyVoice POSTs the completed job payload to that URL instead of you polling. Requires Bearer API-key auth and an https:// URL. Delivered on success only — a failed job still requires polling GET /v1/jobs/{id}; retried up to 3 times (2s/4s backoff) on a non-2xx response or network error.

curl -X POST https://easyvoice.ae/api/v1/jobs \
  -H "Authorization: Bearer ev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "longform",
    "input": "A long article text...",
    "voice": "af_aoede",
    "callback_url": "https://your-endpoint.example/webhook"
  }'

# 202 Accepted -- on completion, EasyVoice POSTs the job payload to callback_url
# with header: X-EasyVoice-Signature: sha256=<hex>

Generate two-host dialogue podcasts from a list of script segments. Submit a job via POST /api/v1/jobs with type:"podcast", then poll for the stitched result. Per-segment audio URLs are returned alongside the final episode URL.

POST /api/v1/jobs — Submit a podcast job

curl -X POST https://easyvoice.ae/api/v1/jobs \
  -H "Authorization: Bearer ev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "podcast",
    "voices": { "A": "af_aoede", "B": "am_echo" },
    "format": "mp3",
    "segments": [
      { "speaker": "A", "text": "Welcome to the show. Today we explore the future of AI." },
      { "speaker": "B", "text": "Thanks for having me. AI is evolving at a remarkable pace." },
      { "speaker": "A", "text": "Absolutely. What do you think the next five years will look like?" },
      { "speaker": "B", "text": "I expect multimodal models to become the default in most apps." }
    ]
  }'

# 202 Accepted
# { "id": "3a9f1b7c-...", "status": "queued" }

GET /api/v1/jobs/{id} — Poll podcast job

curl https://easyvoice.ae/api/v1/jobs/3a9f1b7c-... \
  -H "Authorization: Bearer ev_your_api_key"

# {
#   "id": "3a9f1b7c-...",
#   "status": "completed",
#   "audio_url": "/audio/episode-3a9f1b7c.mp3",
#   "segments": [
#     { "speaker": "A", "audioUrl": "/audio/seg-0.mp3" },
#     { "speaker": "B", "audioUrl": "/audio/seg-1.mp3" },
#     { "speaker": "A", "audioUrl": "/audio/seg-2.mp3" },
#     { "speaker": "B", "audioUrl": "/audio/seg-3.mp3" }
#   ],
#   "error": null,
#   "created_at": 1749500000000,
#   "completed_at": 1749500045000
# }

Tier limits & voice options