{"openapi": "3.1.0", "info": {"title": "voicekit API", "version": "0.1.0", "summary": "Local text generation, voice cloning and text-to-speech.", "description": "The voicekit API lets you **generate text** with a local LLM, **clone voices** from a short recording, and\n**synthesize speech** in those voices. Everything runs on the machine that hosts this server: no audio or\ntext is sent to third-party services.\n\n## Authentication\n\nEvery request (except `health`, `me`, `login` and this documentation) needs an API key:\n\n```\nAuthorization: Bearer vk_…\n```\n\n`X-API-Key: vk_…` works too. The server administrator creates keys in the admin panel (\"API keys\" tab)\nor on the host:\n\n```\nvoicekit keys create --name my-app --scope tts\nvoicekit keys list\nvoicekit keys revoke my-app\n```\n\n**Never put a key in browser code.** Call the API from your backend, or through a proxy that adds the\nheader. The server sends no CORS headers.\n\nA key is shown only once when it is created; the server stores only its SHA-256 hash. Revoking a key takes\neffect immediately, without a restart. Repeated failed attempts from one client are refused with\n`429 Too Many Requests` for a few minutes.\n\n### Scopes\n\n| Scope | Grants |\n|---|---|\n| `text` | Text generation with the local LLM (`POST /chat`, `POST /write`, `GET /llm`) |\n| `clone` | Creating, listing, inspecting and deleting voices (`/voices`, `/train`) |\n| `tts` | Speech synthesis, audio downloads and the history (`/speak`, `/audio`, `/history`) |\n| `admin` | Managing API keys (`/keys`). Only for trusted tools: an admin can create keys with any scope |\n\nListing voices is allowed with either `clone` or `tts`. A key can hold any combination of scopes.\n\n## Quick start for TTS clients\n\n1. **Handshake**: `GET /api/v1/handshake` once at startup. With the `tts` scope it returns the available\n `voices`, all `languages` (with ISO code and native name), the `default_voice` / `default_language`\n and the limits. Show the voices and languages in your UI and let the user choose.\n2. **Speak**: `POST /api/v1/speak` with the chosen `voice` and `language` (its `id` or `code`) and the text.\n3. **Download**: fetch the returned `url` (WAV) or `mp3_url`.\n\nEvery voice can speak every listed language (`cross_lingual: true`). It sounds most natural in the\nvoice's own `language`, so preselect that when the user picks a voice. Voices with `recommended: false`\ncarry `warnings` that are worth showing. Call the handshake again whenever you want a fresh voice list,\nfor example after cloning a new voice.\n\n## Jobs: asynchronous by default\n\nVoice cloning and speech synthesis run on a single GPU, one job at a time. Starting one returns\n`202 Accepted` with a job id. You then have three options:\n\n1. **Poll** `GET /api/v1/jobs/{id}` until `status` is `done` or `error`.\n2. **Stream** `GET /api/v1/jobs/{id}/events` (Server-Sent Events) for live progress.\n3. **Wait**: pass `\"wait\": true` (or `wait=true` in a form) and the request returns only when the job has\n finished, with the same body as polling.\n\nIf the GPU is busy, starting a job returns `409 Conflict`: retry after a few seconds. Finished jobs are kept for one hour.\n\nThe first job after the server has been idle loads the TTS model (about 10 s). The model then stays\nloaded for 5 minutes. Synthesis takes roughly 1.5 s per second of generated speech.\n\n## Errors\n\nErrors use the usual HTTP status codes, with a JSON body:\n\n```\n{\"error\": \"A voice named 'anna' already exists.\", \"hint\": \"Pick another name, or replace it (overwrite=true).\"}\n```\n\n`400` invalid input · `401` missing or invalid key · `403` key lacks the scope (or the admin panel is used\nfrom a network that is not allowed) · `404` unknown voice, job or file · `409` name taken, GPU busy or text\ngenerator busy · `411` chunked body (send `Content-Length`) · `413` body too large · `429` hourly limit for\nthis key reached, or too many failed logins (see `Retry-After`) · `507` server disk almost full.\n\n## Limits\n\nText to speak: at most 5,000 characters per request (split longer documents). Voice reference audio: WAV,\nFLAC, MP3 or M4A, at most 32 MiB. 6–15 seconds of clean speech works best; longer references make the voice\nramble. Text-generation chat: at most 16 messages of history per request.\n\n## Running it on the internet\n\nAt least one account or API key must exist before the server listens on a network interface. Use HTTPS,\nso that keys and passwords are never sent in clear text.\n\n**Reverse proxy on another machine** (e.g. a gateway that routes traffic to the machines of a private\nnetwork): let voicekit listen on its private address, trust forwarding headers only from the proxy, and\ntell it the public URL:\n\n```\nvoicekit studio --host 192.168.1.20 --port 8765 \\\n --trust-proxy 192.168.1.10 --allow-ip 192.168.1.10 \\\n --public-url https://voice.example.com --admin-allow 192.168.1.0/24\n```\n\n- `--allow-ip`: accept connections only from the proxy (and, if needed, your webapp server).\n- `--admin-allow`: the admin panel and admin keys work only from your own network.\n\n- `--trust-proxy 192.168.1.10`: client IP (for the failed-login throttle), scheme and host are taken from\n `X-Forwarded-For/-Proto/-Host`, but only when the request comes from that address. Other machines on the\n network cannot fake them.\n- `--public-url`: the origin browsers see. The admin panel's changes are only accepted from that origin,\n even when the proxy rewrites `Host` (nginx does by default). Session cookies are also marked `Secure`.\n- Firewall port 8765 so that only the proxy can reach it.\n- Per key: 120 jobs and 300 text generations per hour by default (`--jobs-per-hour`, `--writes-per-hour`);\n exceeding them returns `429` with `Retry-After`. A disk that is almost full returns `507`.\n\nThe server operator's full checklist is in `docs/SECURITY.md` in the project.\n\nProxy configuration (Caddy, on the proxy machine; automatic Let's Encrypt certificates):\n\n```\nvoice.example.com {\n reverse_proxy 192.168.1.20:8765 {\n flush_interval -1\n }\n}\n```\n\nnginx: `proxy_pass http://192.168.1.20:8765;`, `proxy_buffering off;` (live progress and streamed text),\n`proxy_read_timeout 1h;`, `client_max_body_size 40m;` (voice uploads), and set `X-Forwarded-For`,\n`X-Forwarded-Proto` and `X-Forwarded-Host`.\n\n**Built-in TLS** without a proxy: `voicekit studio --host 0.0.0.0 --port 8443 --tls-cert fullchain.pem --tls-key privkey.pem`.\n\nThe \"local use without a login\" mode applies only to direct loopback requests without any credentials\nconfigured. It never applies to proxied requests.\n\n## Admin panel and key management\n\nPeople sign in to the web admin panel (`/`) with a username and password. Accounts are created on the\nserver with `voicekit users add --admin`. Accounts with the `admin` scope manage API keys in the\npanel, or through `GET/POST/DELETE /api/v1/keys` (also usable with an API key that has the `admin` scope).\n"}, "servers": [{"url": "/", "description": "This server"}], "security": [{"bearer": []}, {"apiKeyHeader": []}], "tags": [{"name": "Speech (TTS)", "description": "Turn text into speech with a saved voice. Scope `tts`."}, {"name": "Voice cloning", "description": "Create and manage voices. Scope `clone`."}, {"name": "Text generation", "description": "Draft text with the local LLM. Scope `text`."}, {"name": "Jobs", "description": "Follow asynchronous cloning and synthesis jobs."}, {"name": "API keys", "description": "Create, list and revoke API keys. Scope `admin`."}, {"name": "Activity log", "description": "Sign-ins, API calls and changes, as shown in the admin panel. Scope `admin`."}, {"name": "System", "description": "Health, identity and browser login. No key required."}], "paths": {"/api/v1/handshake": {"get": {"tags": ["Speech (TTS)"], "operationId": "handshake", "x-scope": "any key (sections per scope)", "summary": "Handshake: available voices and languages", "description": "Call once when your client starts. It returns the API version and the key's scopes, plus one section per scope the key holds (`null` otherwise). The `tts` section lists the voices and languages to offer to your users, the defaults to preselect, and the limits for `POST /speak`. Voices are sorted with recommended ones first.", "responses": {"200": {"description": "Capabilities for this key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Handshake"}, "example": {"api_version": "v1", "server_version": "0.1.0", "key": {"name": "my-website", "scopes": ["tts"]}, "scopes": ["tts"], "text": null, "clone": null, "tts": {"voices": [{"id": "anna", "name": "anna", "language": "German", "language_code": "de", "mode": "icl", "created_at": "2026-10-30T11:17:43+00:00", "recommended": true, "warnings": []}, {"id": "old-voice", "name": "old-voice", "language": "German", "language_code": "de", "mode": "icl", "created_at": "2026-10-29T23:06:23+00:00", "recommended": false, "warnings": ["Built from a 1124 s reference; output may ramble or repeat. Re-create the voice from 6-15 s of speech."]}], "languages": [{"id": "German", "code": "de", "name": "German", "native_name": "Deutsch"}, {"id": "English", "code": "en", "name": "English", "native_name": "English"}, {"id": "French", "code": "fr", "name": "French", "native_name": "Français"}], "default_voice": "anna", "default_language": "German", "cross_lingual": true, "max_text_chars": 5000, "formats": ["wav", "mp3"], "sample_rate": 24000, "busy": false, "model_loaded": true}}}}}, "401": {"description": "Missing or invalid API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "The key lacks the required scope.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-code-samples": [{"lang": "curl", "label": "curl", "source": "curl -s -H \"Authorization: Bearer $VOICEKIT_KEY\" https://voice.example.com/api/v1/handshake | jq '.tts | {voices: [.voices[] | {id, language, recommended}], languages: [.languages[].code], default_voice}'"}, {"lang": "python", "label": "Python", "source": "import requests\n\nBASE, H = \"https://voice.example.com\", {\"Authorization\": \"Bearer vk_...\"}\ntts = requests.get(f\"{BASE}/api/v1/handshake\", headers=H).json()[\"tts\"]\n\nfor v in tts[\"voices\"]:\n flag = \"\" if v[\"recommended\"] else \" (!) \" + v[\"warnings\"][0]\n print(f\"{v['id']:<16} {v['language']}{flag}\")\nlanguages = {l[\"code\"]: l[\"native_name\"] for l in tts[\"languages\"]}\n\nvoice = tts[\"default_voice\"]\nlanguage = next(v[\"language\"] for v in tts[\"voices\"] if v[\"id\"] == voice) # its own language sounds best"}, {"lang": "javascript", "label": "JavaScript", "source": "// Fill two