Skip to content

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.

Quickstart

  1. Create an API key in the dashboard (Google sign-in, no card).
  2. Create a file. The answer comes back at once with an id.
  3. Poll the id until status is done, or pass webhook_url, then download audio_url.
Create
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"}'
Response
HTTP/1.1 202 Accepted
{
  "id": "z57zz1w1j0ay27jztcy9cpv0bn8j9106",
  "object": "speech",
  "status": "queued",
  "tier": "paid",
  "estimated_seconds": 5,
  "credits_held": 5
}
Check status (every ~5 s)
curl "https://api.stork.ai/api/v1/speech?id=z57zz1w1j0ay27jztcy9cpv0bn8j9106" \
  -H "Authorization: Bearer sk_stork_YOUR_KEY"
Finished
{
  "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
}
A free file
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"}'
Python
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"])
Node.js 18+
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 audioPrice
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.

Englishen-ava(f)▶en-leo(m)▶en-nora(f)▶en-sam(m)▶
Arabicar-layla(f)▶ar-omar(m)▶
Hindihi-priya(f)▶hi-arjun(m)▶
Urduur-sana(f)▶ur-bilal(m)▶
Frenchfr-camille(f)▶fr-karim(m)▶
Spanishes-lucia(f)▶es-mateo(m)▶
Portuguesept-beatriz(f)▶pt-rafael(m)▶
Italianit-giulia(f)▶it-marco(m)▶
Russianru-anna(f)▶ru-ivan(m)▶
Turkishtr-elif(f)▶tr-emre(m)▶
Germande-lena(f)▶de-jonas(m)▶
Japaneseja-yui(f)▶ja-haruto(m)▶
Koreanko-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.

400invalid_requestThe JSON body needs text and voice_id.
400text_too_short / text_too_longOne file holds up to 20,000 characters and 30 minutes of audio.
400invalid_voice_idvoice_id is missing or unknown. See GET /voices.
400invalid_tiertier must be "paid" or "free".
401invalid_api_keyNo key, or the key is wrong or revoked.
402insufficient_creditsThe wallet cannot cover the hold. Add credits at stork.ai/credits.
404not_foundNo speech file with that id on this account.
409idempotency_key_reused / request_in_progressSame Idempotency-Key with a different body, or the first request is still running.
429too_many_in_progress / free_daily_limit / free_capacityToo many files are being made on this account, or the free allowance for today is used.
503voiceover_unavailableRetry 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