Give your application
a voice.

Integrate Kokorov text-to-speech into your product using a simple HTTP API. Submit text, choose a voice and audio format, and receive generated speech as an audio file.

API base URL

https://Kokorov.duckdns.org

Quick start

Follow these steps to make your first speech-generation request.

1. Register. Submit your name and email address to receive an account ID and API key.
2. Wait for activation. Your account starts with pending status. The service provider must activate it and assign a subscription.
3. Choose a voice. Call GET /voices to retrieve the voices currently available.
4. Generate speech. Send an authenticated request to POST /v1/tts and save the returned audio.

curl -X POST https://Kokorov.duckdns.org/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! Welcome to Kokorov text to speech.",
    "voice": "af_heart",
    "speed": 1.0,
    "format": "wav"
  }' \
  --output speech.wav

Create an account

Request body

{
  "name": "John Banda",
  "email": "john@example.com"
}

Successful response

Registration returns HTTP 200 with your account ID and newly generated API key.

{
  "account_id": "KKR-XXXXXXXXXXXXXXX",
  "api_key": "kk_live_YOUR_SECRET_KEY"
}

An email address can only be registered once. A duplicate registration returns HTTP 409 Conflict.

Account activation

New accounts are created with pending status. Your API key is valid for account and usage lookups, but cannot generate speech until the account is activated.

Contact your Kokorov service provider for activation or subscription questions. Activation, subscription changes, and account administration are handled by the provider.

Authentication

Protected endpoints use Bearer token authentication. Include your API key in the HTTP Authorization header.

Authorization: Bearer YOUR_API_KEY

API keys have the prefix kk_live_. Requests with missing, invalid, or revoked keys are rejected with HTTP 401 Unauthorized.

List voices

Example response

{
  "voices": ["af_heart"]
}

Currently available: af_heart. Always query this endpoint for the latest list before presenting voice choices in your application.

curl https://Kokorov.duckdns.org/voices

Text to speech

Request body

Example request

{
  "text": "Hello! This audio was generated using Kokorov.",
  "voice": "af_heart",
  "speed": 1.0,
  "format": "wav"
}

JavaScript example (Node.js)

This example uses the built-in fetch API available in modern Node.js versions.

const fs = require("node:fs/promises");

const API_URL = "https://Kokorov.duckdns.org";
const API_KEY = process.env.Kokorov_API_KEY;

async function synthesize(text) {
  const response = await fetch(`${API_URL}/v1/tts`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      text,
      voice: "af_heart",
      speed: 1.0,
      format: "mp3"
    })
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Kokorov ${response.status}: ${error}`);
  }

  const audio = Buffer.from(await response.arrayBuffer());
  await fs.writeFile("speech.mp3", audio);
  return audio.length;
}

synthesize("Hello from my application!")
  .then(size => console.log(`Saved ${size} bytes`))
  .catch(console.error);

Successful response

A successful synthesis returns the audio file directly, not JSON. The response includes these headers:

Account details

curl https://Kokorov.duckdns.org/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

The response contains an account object, a subscription object (which may be null), and active_api_keys. Account information includes the account ID, name, email, status, and creation timestamp.

Usage and quota

curl https://Kokorov.duckdns.org/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

When a subscription exists, usage data includes its character limit, characters used, characters remaining, status, start time, and expiry time. Successful speech-generation requests consume quota based on the number of characters submitted.

Audio formats

Choose the output format using the format request field. If omitted, the API returns WAV.

Format names are case-insensitive. Unsupported formats return HTTP 400 Bad Request.

Errors

Errors are returned with an appropriate HTTP status and a message describing the problem.

Security best practices

• Keep API keys on your server. Never embed them in public frontend code.
• Use environment variables or a secrets manager to store credentials.
• Use HTTPS for every API request.
• Do not commit API keys to Git repositories.
• Do not log authorization headers or full API keys.
• Validate user input and enforce sensible request limits in your application.