API

Send text, get audio. Two calls: one POST to queue the job, one GET to download the file when it is ready. Any language, any voice in the catalogue, from any programming language that can make an HTTP request.

Included with the Unlimited plan. Create your key in your account → Settings → API keys. The key is shown once, when you create it — we only store its hash, so we cannot show it to you again. Lost it? Revoke it and create another.

Authentication

Send the key in the Authorization header. It is never accepted in the URL, on purpose: query strings end up written in server logs, proxies and browser history.

Authorization: Bearer kw_1a2b3c4d_your-secret-here

Check that a key works:

curl -H "Authorization: Bearer $KW_KEY" https://kreawave.com/api/v1/me

It answers with your plan, your remaining balance and your concurrency, so a program can look before it queues a batch instead of hitting a 402 halfway through.

Generate audio

curl -X POST https://kreawave.com/api/v1/tts \
     -H "Authorization: Bearer $KW_KEY" \
     -H "Content-Type: application/json" \
     -d '{"text":"Hello world","voice_id":"en_us_...","out_format":"mp3"}'

# -> {"job_id":"tts_9f...","status":"queued"}

Field	Required	What it does
text	yes	What to say. Up to 600,000 characters per job.
voice_id	yes	From GET /api/v1/voices.
out_format	no	wav (default) or mp3.
lang	no	Overrides the language detected from the text.
seed	no	Same seed + same text + same voice = same take.

Pauses

Write [[N]] in the text to set the pause length in milliseconds at that point. The pause is delivered exactly when it exceeds the natural pause of the punctuation (~550 ms after a period); shorter values blend into the sentence flow, which keeps the narration smooth. Values under ~350 ms are interpreted as natural phrasing. Maximum 30000.

"And then, [[600]] everything went quiet. [[1200]] Nobody moved."

A single pause tops out at 30,000 ms.

Collect the audio

curl -H "Authorization: Bearer $KW_KEY" https://kreawave.com/api/v1/tts/tts_9f...
# -> {"status":"done","duration_s":3.2,...}

curl -H "Authorization: Bearer $KW_KEY" \
     https://kreawave.com/api/v1/tts/tts_9f.../audio -o out.mp3

status goes queued → running → done (or error). Poll every few seconds; there are no webhooks yet. DELETE /api/v1/tts/{job_id} cancels one that has not started.

Endpoints

Method	Path	What it is for
GET	/api/v1/me	Plan, balance and limits.
GET	/api/v1/voices?lang=en&limit=200	Voice catalogue.
POST	/api/v1/tts	Queue a job.
GET	/api/v1/tts/{job_id}	Status of a job.
GET	/api/v1/tts/{job_id}/audio	Download the file.
DELETE	/api/v1/tts/{job_id}	Cancel a queued job.

Limits and errors

Code	Meaning
401	Missing, malformed, unknown or revoked key — all four look identical from outside, on purpose.
403	Your plan does not include the API, your email is unverified, or the account is suspended.
402	Not enough balance for that job. /me tells you how much is left.
429	Too many failed authentication attempts from your IP, or the queue is full.

Your plan sets how many jobs run at once; you can leave as many queued as you like and they enter as slots free up. You are charged for the real duration of the audio delivered, and only when a job finishes successfully — a job that fails costs you nothing.

Keeping your key safe

• Keep it on your server or in an environment variable. Anything you ship to a browser or a mobile app is readable by whoever runs it.
• One key per program, with a name you recognise. Then revoking the one that leaked does not stop the rest.
• Revoke instantly from your account. It stops working on the next request — there is no cache to wait out.