# Speakvora Voice API (for AI coding assistants)

Speakvora turns text into speech with premium voices, delivered from a CDN.
Status: live on the development environment at https://dev.speakvora.com/api. Library phrases in every voice; any text, live, for Kokoro voices: en af_heart af_bella af_nicole af_sarah af_sky am_adam am_michael; es ef_dora em_alex; fr ff_siwis; pt pf_dora pm_alex; hi hf_alpha hm_omega; ja jf_alpha jm_kumo; zh zf_001 zm_009 (send the matching lang; write numbers out in words; non-English replies carry review_status native_review_pending). Use openapi.yaml as the contract.

Authentication: send your key in the header `x-api-key`. Never put the key in client-side code that ships to users; call from your server.

Core call:
  POST {base}/v1/speak   JSON {"text": "...", "voice": "<id from /v1/voices>", "lang": "en|es|zh|hi|ja|ko|fr|de|pt|ar|auto"}
  -> 200 {"url": "...", "lang": "...", "duration_s": 1.8, "status": "approved|review"}  then GET the url (audio/mp4).
  -> 202 means another request is generating the same sentence: wait retry_after_ms and call again. Do not generate twice.
  -> 503 means play your fallback voice; you were not billed.

Rules an integration must follow:
  1. Never send personal data. Use placeholders such as "Hello, (name). Your appointment is on (date)." and speak the personal part with an on-device voice or a
     pack of generic words. Speakvora stores the audio generated for the exact text it receives.
  2. Safety-critical lines (alarms, stop commands) must come from audio stored on the device or the platform's own voice. Never depend on the network for them.
  3. Clip URLs are immutable for one year; the same text, voice and lang always returns the same clip, so you may store the URL.
  4. lang="auto" detects script and common Latin-script languages only and refuses to guess; send lang explicitly for short texts like "Hola."
  5. Do not present the voice as a human. Disclose that it is automated where the law or good practice requires it.

Other endpoints: GET /v1/voices (voices and languages), POST /v1/feedback (thumbs), GET /v1/packs (planned: offline phrase packs).
Examples (replace {base} and the key):
  curl -s -X POST {base}/v1/speak -H "x-api-key: $KEY" -H "content-type: application/json" -d '{"text":"Thank you for calling.","voice":"easygoing-friend","lang":"en"}'
  python: requests.post(f"{base}/v1/speak", headers={"x-api-key": KEY}, json={"text": "Gracias por su paciencia.", "voice": "easygoing-friend", "lang": "auto"}).json()["url"]
  js:     const r = await (await fetch(`${base}/v1/speak`, {method: "POST", headers: {"x-api-key": KEY, "content-type": "application/json"}, body: JSON.stringify({text, voice, lang: "en"})})).json();

SDKs (single files, no dependencies): https://dev.speakvora.com/sdk/speakvora.js and https://dev.speakvora.com/sdk/speakvora.py
Webhooks: events test.ping, key.created, key.revoked; header x-speakvora-signature = hex HMAC-SHA256(secret, timestamp + "." + rawBody), header x-speakvora-timestamp. Reject if older than 5 minutes.
Developer portal (keys, test, code, webhooks): https://dev.speakvora.com/dashboard