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.

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. 10M 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.

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 403 plan_required naming the voice.

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.

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