Speech API
Send text and a voice. Get back an MP3. 28 built-in voices in 13 languages, or a voice you added to your account. $0.05 per minute of finished audio from prepaid credits. No subscription.
- • $0.05 a minute, billed per started 10 seconds
- • Free tier: 3 files a day, up to 60 s each
- • Up to 20,000 characters in one file
- • MP3, 128 kbps mono
- • Signed webhooks, idempotent creates, OpenAPI 3.1
- • Same key and credits as the Talking Photo API
Quickstart
- Create an API key in the dashboard (Google sign-in, no card).
- Create a file. The answer comes back at once with an id.
- Poll the id until
statusisdone, or passwebhook_url, then downloadaudio_url.
curl -X POST https://api.stork.ai/api/v1/speech \
-H "Authorization: Bearer sk_stork_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: episode-12-intro" \
-d '{"text": "Welcome back to the channel. Today we are looking at three small habits.", "voice_id": "en-ava"}'HTTP/1.1 202 Accepted
{
"id": "z57zz1w1j0ay27jztcy9cpv0bn8j9106",
"object": "speech",
"status": "queued",
"tier": "paid",
"estimated_seconds": 5,
"credits_held": 5
}curl "https://api.stork.ai/api/v1/speech?id=z57zz1w1j0ay27jztcy9cpv0bn8j9106" \
-H "Authorization: Bearer sk_stork_YOUR_KEY"{
"id": "z57zz1w1j0ay27jztcy9cpv0bn8j9106",
"object": "speech",
"status": "done",
"tier": "paid",
"voice_id": "en-ava",
"characters": 72,
"estimated_seconds": 5,
"seconds": 5.5,
"credits": 5,
"audio_url": "https://...mp3",
"error": null,
"created_at": 1794768909,
"completed_at": 1794768953
}curl -X POST https://api.stork.ai/api/v1/speech \
-H "Authorization: Bearer sk_stork_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "This one costs nothing.", "voice_id": "en-leo", "tier": "free"}'import time, uuid, requests
URL = "https://api.stork.ai/api/v1/speech"
H = {"Authorization": "Bearer sk_stork_YOUR_KEY"}
job = requests.post(URL, headers={**H, "Idempotency-Key": str(uuid.uuid4())}, json={
"text": "Welcome back to the channel. Today we are looking at three small habits.",
"voice_id": "en-ava",
}).json()
if "error" in job:
raise SystemExit(job["error"])
while True:
s = requests.get(URL, headers=H, params={"id": job["id"]}).json()
if s["status"] in ("done", "failed", "stopped"):
break
time.sleep(5)
print(s["audio_url"] or s["error"])const URL = "https://api.stork.ai/api/v1/speech";
const H = { Authorization: "Bearer sk_stork_YOUR_KEY", "Content-Type": "application/json" };
const job = await fetch(URL, {
method: "POST",
headers: { ...H, "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({
text: "Welcome back to the channel. Today we are looking at three small habits.",
voice_id: "en-ava",
}),
}).then((r) => r.json());
let s;
do {
await new Promise((r) => setTimeout(r, 5_000));
s = await fetch(`${URL}?id=${job.id}`, { headers: H }).then((r) => r.json());
} while (s.status === "queued" || s.status === "running");
console.log(s.audio_url ?? s.error);Pricing
| Finished audio | Price |
|---|---|
| 10 seconds | $0.05 (5 credits) |
| 1 minute | $0.05 (5 credits) |
| 10 minutes | $0.50 (50 credits) |
| 30 minutes | $1.50 (150 credits) |
| Free tier | $0, up to 60 s a file, 3 files a day per account |
- 1 credit = 1 cent. Credit packs start at $2.00 and never expire. Buy them at stork.ai/credits.
- 5 credits per minute of finished audio, billed per started 10 seconds, 5 credits minimum a file. Every voice costs the same.
- The estimate plus 10% is held when the file is created (
credits_held). You are charged for the finished length (credits), never more than the hold, and nothing if it fails.
Voices
Write the text in the voice's language. Every built-in voice is synthetic (designed, not cloned from a real person). Live list: GET https://api.stork.ai/api/v1/voices (no key needed). A voice you added to your account in the dashboard works too: pass its id as voice_id.
| English | en-ava(f)▶en-leo(m)▶en-nora(f)▶en-sam(m)▶ |
| Arabic | ar-layla(f)▶ar-omar(m)▶ |
| Hindi | hi-priya(f)▶hi-arjun(m)▶ |
| Urdu | ur-sana(f)▶ur-bilal(m)▶ |
| French | fr-camille(f)▶fr-karim(m)▶ |
| Spanish | es-lucia(f)▶es-mateo(m)▶ |
| Portuguese | pt-beatriz(f)▶pt-rafael(m)▶ |
| Italian | it-giulia(f)▶it-marco(m)▶ |
| Russian | ru-anna(f)▶ru-ivan(m)▶ |
| Turkish | tr-elif(f)▶tr-emre(m)▶ |
| German | de-lena(f)▶de-jonas(m)▶ |
| Japanese | ja-yui(f)▶ja-haruto(m)▶ |
| Korean | ko-jiwoo(f)▶ko-minjun(m)▶ |
Reference
Base URL https://api.stork.ai/api/v1. Machine-readable: openapi.json (OpenAPI 3.1).
Authentication
Authorization: Bearer sk_stork_…. Keys are per account; credits and the free allowance belong to the account.
POST /speech
text(required): what the voice says, up to 20,000 characters.voice_id(required): a built-in voice, or the id of one of your own voices.tier:"paid"(default) or"free"(up to 60 s, 3 a day).webhook_url: https URL we POST the finished file to (signed, see below).- Header
Idempotency-Key(recommended): any unique string. A repeated request with the same key and body returns the first answer (Idempotent-Replayed: true) and makes no second file.
GET /speech?id=<id> · GET /speech?limit=20
One file, or your recent files. status is queued, running, done, failed or stopped. audio_url is set when it is done. Store your copy.
POST /speech/estimate
curl -X POST https://api.stork.ai/api/v1/speech/estimate \
-H "Authorization: Bearer sk_stork_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Welcome back to the channel. Today we are looking at three small habits."}'
{ "characters": 72, "seconds": 5, "credits": 5, "credits_held": 5, "max_characters": 20000 }GET /voices?language=ar
Voices with id, name, language, gender and a preview_url. No key needed.
Webhooks
With webhook_url we POST once when the file is done or has failed, with the event type speech.done or speech.failed and the same object as GET in data. Answer 2xx; otherwise we retry after 1 min, 5 min, 30 min, 2 h and 6 h. Verify Stork-Signature with your signing secret from the dashboard, using the code in the Talking Photo API docs.
Errors
{ "error": { "code", "message", "request_id" } }. Every response carries Stork-Request-Id; quote it if you contact us.
| 400 | invalid_request | The JSON body needs text and voice_id. |
| 400 | text_too_short / text_too_long | One file holds up to 20,000 characters and 30 minutes of audio. |
| 400 | invalid_voice_id | voice_id is missing or unknown. See GET /voices. |
| 400 | invalid_tier | tier must be "paid" or "free". |
| 401 | invalid_api_key | No key, or the key is wrong or revoked. |
| 402 | insufficient_credits | The wallet cannot cover the hold. Add credits at stork.ai/credits. |
| 404 | not_found | No speech file with that id on this account. |
| 409 | idempotency_key_reused / request_in_progress | Same Idempotency-Key with a different body, or the first request is still running. |
| 429 | too_many_in_progress / free_daily_limit / free_capacity | Too many files are being made on this account, or the free allowance for today is used. |
| 503 | voiceover_unavailable | Retry shortly. |
Limits
- Short files are ready in under a minute. Long ones take about three quarters of their own length.
- One file holds up to 20,000 characters and 30 minutes of audio. Split longer scripts into several files.
Need the face too?
The Talking Photo API takes the same text and voice_id plus one photo, and returns a lip-synced MP4. AI agents can reach the video tools on the MCP server at https://mcp.stork.ai/mcp.
Want to try it without code? Use Stork Voiceover.
Comparing options? Text to speech API prices, per minute
