API Overview
Use voice cloning, text-to-speech and voice conversion from your own app.
The API gives you the same voice features as the web app: clone voices, convert text to speech (one at a time or in batches), convert voices, check tasks and receive webhooks. Every endpoint lives under /api/v1 and returns JSON.
Base URL
https://voiceailabs.com/api/v1Authentication
Send your API key in the Authorization header of every request:
curl https://voiceailabs.com/api/v1/account \
-H "Authorization: Bearer sk-your-api-key"- Keys start with
sk-and are shown only once. Keep them on your server - never in frontend code or public repositories. - If a key leaks, delete it on the API Keys page and create a new one.
- All keys of an account share its credits, plan limits and rate limit.
Response format
Every endpoint returns { code, message, data } together with a matching HTTP status code.
On success code is 0:
{
"code": 0,
"message": "ok",
"data": { "id": "6f1c…", "object": "synthesis", "status": "pending" }
}On failure code is -1 and data holds the error code, whether it is retryable, and the request ID:
{
"code": -1,
"message": "Insufficient credits",
"data": {
"error_code": "INSUFFICIENT_CREDITS",
"retryable": false,
"request_id": "0b5e2f1a-…",
"required": 120,
"available": 30
}
}Handle errors by data.error_code, not by the message text. See Errors & Limits for the full list. Include the request_id (also in the X-Request-Id response header) when contacting support.
Asynchronous tasks
Text-to-speech and voice conversion are asynchronous: the create endpoint returns 202 with a task right away, and the audio URL is available once generation finishes.
Create a task with POST /tts, POST /tts/batches or POST /voice-conversion, and keep the returned id.
Wait for it to finish. We recommend a webhook so we notify you when the task ends. You can also poll GET /syntheses/{id} every 2–5 seconds.
Download the audio from audio_url (MP3) when status is completed. Audio is kept for your plan's retention period, so copy it to your own storage.
Task statuses:
| Status | Meaning |
|---|---|
pending | Created, queued or waiting to be generated |
processing | Generated, audio is being saved |
completed | Done - audio_url is ready |
failed | Failed - charged credits are refunded automatically (see refund) |
Billing
- Credits are deducted when a task is created, following the pricing rules, and fully refunded if the task fails.
- Text-to-speech is billed by characters. Your pronunciation dictionary from the web app also applies to API requests; if a replacement makes the text longer, the replaced text is billed.
- Voice conversion is billed by the duration of the input audio.
- Cloning a voice costs no credits but uses one of your plan's voice slots.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /account | Account, credit balance and plan limits |
GET | /voices | List your voices |
GET | /voices/public | List public voices |
GET | /voices/{id} | Get a voice |
POST | /voices | Clone a voice |
DELETE | /voices/{id} | Delete a voice |
POST | /tts | Create a text-to-speech task |
POST | /tts/batches | Create text-to-speech tasks in a batch |
GET | /tts/batches/{id} | Get a batch |
POST | /voice-conversion | Create a voice conversion task |
GET | /syntheses | List tasks |
GET | /syntheses/{id} | Get a task |
Versioning and legacy endpoints
- The current version is
v1. We only add fields, endpoints and error codes tov1- we never remove fields or change their meaning. Make your code ignore fields it doesn't recognize. - Endpoints from earlier docs such as
/api/voice/*and/api/get-user-infoare internal to the web app and stop accepting API keys after November 30, 2026. Please migrate to/api/v1before then.