Tools reference — seven tools, four groups
Instant TTS
text_to_speech
Convert text to a hosted MP3/WAV download link — the core tool, and the one free keys can use. Per-call limit: 8,000 characters (4,000 for Arabic ar_* voices).
| Parameter | Type | Required | Description |
|---|
| text | string | Yes | The text to speak — up to 8,000 characters per call (4,000 on ar_* voices). |
| voice | string | No | Voice id (default af_aoede) — call list_voices for the catalog. |
| speed | number | No | 0.5 to 2 (default 1). |
| format | string | No | mp3 or wav (default mp3). |
// tools/call arguments
{ "text": "Hello from my AI agent!", "voice": "af_aoede", "format": "mp3" }
// result (abridged)
{ "audio_url": "https://easyvoice.ae/api/tts/audio/1f6f7c2e-8a41.mp3",
"voice": "af_aoede", "format": "mp3", "characters": 23 }The result is a hosted download URL (https://easyvoice.ae/api/tts/audio/<uuid>.mp3). Audio links are not guaranteed to persist — download promptly. Over 8,000 characters on a Kokoro voice? Use generate_long_form (Pro) or the web studio. Over 4,000 characters on an ar_* voice? Use POST /api/v1/audio/speech (Arabic sync cap 12,000) or the web app — never the long-form tool, which is Kokoro-only and rejects Arabic voices. Cloned voice_* ids are not accepted here either — the tool returns an error pointing at POST /api/v1/audio/speech for synchronous cloned synthesis, or create_podcast to use clones over MCP.
list_voices
No parameters. Lists all 56 catalog voices with a tier column (free | pro) plus your cloned voices and their status. Free keys can synthesize with the 12 free-tier voices — the rest return a truthful Pro-required error.
// tools/call arguments
{}
// result (abridged)
{ "plan": "free",
"voices": [ { "id": "af_aoede", "name": "Aoede", "language": "English",
"tier": "free", "available": true }, "..." ],
"cloned": [ { "id": "voice_abc123", "name": "My Voice", "status": "ready" } ] }Async jobs — long-form, podcast, status
Pro gate, stated once up front: these tools reuse the Jobs API, and “The Jobs API requires a Pro subscription — free API keys can use /v1/audio/speech.” is exactly what a free key gets back (as an isError result). Free keys can use instant text_to_speech above. The agent flow for all job tools: create → poll get_job_status → download audio_url. Long-form and podcast audio is retained about 7 days after completion, so the audio_url can be re-fetched any time within that window by calling get_job_status again with the same job id.
generate_long_form
Narrate a full script — up to 500,000 characters in one job. Kokoro narration voices only: ar_* and cloned voice_* ids are rejected by the long-form engine.
| Parameter | Type | Required | Description |
|---|
| input | string | Yes | The full script, up to 500,000 characters. |
| voice | string | No | Kokoro voice id (default af_aoede). |
| speed | number | No | 0.5 to 2 (default 1). |
| format | string | No | mp3 or wav (default mp3). |
// tools/call arguments
{ "input": "Chapter 1. The full 120,000-character script...", "voice": "af_aoede" }
// result — a job id, 202-style
{ "job_id": "1f6f7c2e-...", "status": "queued", "input_chars": 120000 }
// then poll get_job_status with that job_id:
{ "id": "1f6f7c2e-...", "status": "active", "completed": 3, "total": 12 }
{ "id": "1f6f7c2e-...", "status": "completed",
"audio_url": "https://easyvoice.ae/api/tts/audio/1f6f7c2e.mp3" }Voice cloning
clone_voice
Enroll a custom cloned voice from an audio sample (async). Honest gating, all enforced server-side: Pro only; consent: true attestation required (recorded); 5 enrollments per day; 3 cloned voices max — a full account returns 409. Sample: 10 MB max, wav/mp3/m4a, a 15–60 second clean single-speaker recording works best.
| Parameter | Type | Required | Description |
|---|
| name | string | Yes | Display name for the cloned voice. |
| consent | boolean | Yes | Must be literally true — you attest you have the recording rights to the sample. Anything else is rejected. |
| audio_base64 | string | One of | Base64-encoded audio sample (10 MB max decoded). |
| audio_url | string | One of | Public https URL to the sample — fetched server-side, same 10 MB bound, redirects not followed. |
| mime_type | string | No | Sample MIME type (default audio/wav) — wav, mp3, m4a accepted. |
// tools/call arguments
{ "name": "My Narrator", "consent": true,
"audio_url": "https://example.com/sample.wav" }
// result
{ "voice_id": "voice_9f2c...", "status": "enrolling" }After enrolling, check list_voices until the clone reports ready, then use it in create_podcast. For synchronous cloned synthesis, use POST /api/v1/audio/speech (REST, same key) — text_to_speech does not take cloned ids.
Account
get_usage
No parameters — returns your plan, remaining free characters, rate limits, and the daily reset time. Agents should call this to self-handle quota errors instead of retrying blindly.
// tools/call arguments
{}
// result (free key)
{ "plan": "free", "used": 1200, "remaining": 3800, "limit": 5000,
"rpm_limit": 20, "concurrency_limit": 2, "reset_at": "2026-07-22T00:00:00Z" }