Developers · API Access

Kokoro Web exposes an OpenAI-compatible speech synthesis endpoint so you can generate voices from any application. Use this page to understand the request flow, configure authentication, and generate API keys for your deployment.

1. Generate an API key

Use the generator below to create a random key. Store the value in the KW_SECRET_API_KEY environment variable for your backend or Cloudflare Worker deployment. The Kokoro API validates incoming requests against this secret.

Generated key

Environment setup:

() => `KW_SECRET_API_KEY="${"your-generated-key"}"`

Restart your server (or redeploy) after updating the environment value so the API authenticates with the new secret.

2. Configure requests

All requests must include a bearer token matching the secret above. Point the OpenAI SDK (or your HTTP client) to the Kokoro base URL.

Base URL

https://kokoro.lancesmith.cc/api/v1

Required header

Authorization: Bearer <your-api-key>

Available models

Use the same model identifiers shown in the web app (e.g. model_q8f16). Voice formulas follow the voice_id*weight syntax.

Endpoint reference

Method	Path	Description
POST	`/api/v1/audio/speech`	Generate an `mp3` or `wav` file from text.

Swagger/OpenAPI documentation is also available at /api/v1/index.html.

Request payload

Field	Type	Required	Description
`model`	string	Yes	Any model id exposed in the UI (e.g. `model_q8f16`).
`voice`	string	Yes	Voice formula such as `af_alloy` or `af_alloy0.5+am_melissa0.5`.
`input`	string	Yes	Text to transform into audio. Silence tags like `[0.5s]` are supported.
`response_format`	string	No	`mp3` (default) or `wav`.
`speed`	number	No	Playback speed multiplier between `0.25` and `5`. Defaults to `1`.

Voice formula tips

Combine voices with weights that add up to 1.0.
The first voice controls language/phonemization.
Find supported voice ids inside the web app voice picker or via the OpenAPI spec.

Examples

curl

() => `curl -X POST   ${BASE_URL}/audio/speech   -H "Authorization: Bearer ${"your-api-key"}"   -H "Content-Type: application/json"   --data '{
    "model": "model_q8f16",
    "voice": "af_alloy",
    "input": "Hello from Kokoro!",
    "response_format": "mp3"
  }' --output speech.mp3`

Node.js (OpenAI SDK)

import fs from "fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://kokoro.lancesmith.cc/api/v1",
  apiKey: process.env.KOKORO_API_KEY,
});

const response = await client.audio.speech.create({
  model: "model_q8f16",
  voice: "af_alloy",
  input: "Hello from Kokoro!",
});

await fs.writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));

Python (OpenAI SDK)

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://kokoro.lancesmith.cc/api/v1",
    api_key="YOUR_API_KEY",
)

with client.audio.speech.with_streaming_response.create(
    model="model_q8f16",
    voice="af_alloy",
    input="Hello from Kokoro!",
) as response:
    response.stream_to_file(Path("speech.mp3"))