# Stork Speech API (text to speech)

Text in, an MP3 out (128 kbps mono). HTML docs: https://www.stork.ai/developers/speech-api

All requests: `Authorization: Bearer sk_stork_...`. Create a key at https://www.stork.ai/dashboard/api. One key and one credit balance cover every API. 1 credit = 1 cent; packs start at $2.00 and never expire (https://www.stork.ai/credits).

## Create: POST /speech

| Field | Required | Meaning |
| --- | --- | --- |
| `text` | yes | What the voice says, in the voice's language. Up to 20000 characters and 30 minutes of audio |
| `voice_id` | yes | A built-in voice (below) or the id of one of your own voices |
| `tier` | no | `paid` (default) or `free` (up to 60 s, 3 files a day per account) |
| `webhook_url` | no | https URL for the signed result |

```bash
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.", "voice_id": "en-ava"}'
```

Returns 202: `{ id, object: "speech", status: "queued", tier, estimated_seconds, credits_held }`.

## Read: GET /speech?id=<id> | GET /speech?limit=20

`status` is `queued`, `running`, `done`, `failed` or `stopped`. When done: `audio_url`, `seconds`, `credits`. Poll about every 5 s. Short files are ready in under a minute; long ones take about three quarters of their own length.

## Estimate: POST /speech/estimate

Body: `{ "text": "..." }`. Returns `characters`, `seconds`, `credits`, `credits_held`, `max_characters`.

## Voices: GET /voices?language=<code> (no key needed)

- English: `en-ava`, `en-leo`, `en-nora`, `en-sam`
- Arabic: `ar-layla`, `ar-omar`
- Hindi: `hi-priya`, `hi-arjun`
- Urdu: `ur-sana`, `ur-bilal`
- French: `fr-camille`, `fr-karim`
- Spanish: `es-lucia`, `es-mateo`
- Portuguese: `pt-beatriz`, `pt-rafael`
- Italian: `it-giulia`, `it-marco`
- Russian: `ru-anna`, `ru-ivan`
- Turkish: `tr-elif`, `tr-emre`
- German: `de-lena`, `de-jonas`
- Japanese: `ja-yui`, `ja-haruto`
- Korean: `ko-jiwoo`, `ko-minjun`

## Pricing

$0.05 per minute of finished audio (5 credits), billed per started 10 seconds, 5 credits minimum a file. Every voice costs the same. The estimate plus 10% is held; you are charged for the finished length, never more than the hold.

## Errors

- 400 `invalid_request`, `text_too_short`, `text_too_long`, `invalid_voice_id`, `invalid_tier`, `invalid_webhook_url`
- 401 `invalid_api_key`
- 402 `insufficient_credits`
- 404 `not_found`
- 409 `idempotency_key_reused`, `request_in_progress`
- 429 `too_many_in_progress`, `free_daily_limit`, `free_capacity`
- 503 `voiceover_unavailable`

## Webhooks

Pass `webhook_url` (https) on create. We POST once when the job reaches a final state. Answer 2xx; otherwise we retry after 1 min, 5 min, 30 min, 2 h and 6 h. `Stork-Webhook-Id` is the same on every retry.

Body: `{ "id": "evt_...", "type": "<object>.<status>", "created_at": "...", "data": { ...same object as GET... } }`

Verify the `Stork-Signature: t=<unix>,v1=<hex>` header: `v1` is HMAC-SHA256, hex, of the string `<t>.<raw body>` keyed with your signing secret (`whsec_...`, shown at https://www.stork.ai/dashboard/api). Reject when `t` is more than 300 seconds old.

```js
import crypto from "node:crypto";
export function verifyStork(raw, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}
```

Event types: `speech.done`, `speech.failed`.

## Conventions

- Base URL: `https://api.stork.ai/api/v1`. OpenAPI 3.1: https://api.stork.ai/api/v1/openapi.json
- Jobs are asynchronous: create returns 202 with an `id`; poll `GET ?id=` or use a webhook.
- Node library: `npm install storkai`, then `import { Stork } from "storkai"`. It wraps every call here (`create`, `get`, `list`, `estimate`, `wait`, `createAndWait`) and verifies webhooks. Reference: https://www.npmjs.com/package/storkai
- Python library: `pip install storkai`, then `from storkai import Stork`. Same calls in snake_case (`create_and_wait`). Reference: https://pypi.org/project/storkai/
- `Idempotency-Key` header on create (any unique string, kept 24 h): a retry with the same key and body returns the first response with `Idempotent-Replayed: true` and creates nothing. Same key, different body: 409 `idempotency_key_reused`.
- Errors: `{ "error": { "code", "message", "param", "request_id", "doc_url" } }`. Every response carries `Stork-Request-Id`. 429 and 503 carry `Retry-After`.
- Money: the price is held when the job is created, you are charged for what is delivered, and a failed job returns every credit.
