# Text to Speech AI - 21 Natural Voices, 8 Languages (`andrew_babo/kokoro-tts`) Actor

Convert text into natural speech with 21 AI voices across English, Spanish, French, Italian, Portuguese, Hindi, Japanese and Chinese. Speed control, long text support, MP3/WAV/Opus download. No rental fee - you pay Apify compute only.

- **URL**: https://apify.com/andrew_babo/kokoro-tts.md
- **Developed by:** [Andrew Babo](https://apify.com/andrew_babo) (community)
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 6 total users, 5 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Text to Speech AI — 21 Natural Voices, 8 Languages

Turn any text into natural-sounding speech in seconds. Paste your text, pick a voice, get a ready-to-use audio file (MP3, WAV or Opus) you can drop straight into a video, podcast, app or website.

**Good for:** YouTube / TikTok / Reels voiceovers, e-learning narration, product demos, audiobooks, IVR and phone prompts, accessibility read-aloud, app notifications.

### Quick start

```json
{
  "text": "Hello! This audio was generated automatically.",
  "voice": "af_heart",
  "format": "mp3"
}
```

Run it and you get back an audio file URL in the run's storage — no setup, no API key, no external account.

### What you get

- **21 voices** across English, Spanish, French, Italian, Portuguese, Hindi, Japanese and Chinese
- **Male and female** voices, several accents per language
- **Long text supported** — the Actor handles the splitting and joins the audio seamlessly
- **Speed control** from slow narration to fast reads
- **MP3, WAV or Opus** output, ready for editing software
- **Fast warm mode** so repeated requests answer almost instantly

### Input

| Field | Default | What it does |
|---|---|---|
| `text` | required | The text you want spoken |
| `voice` | `af_heart` | Which voice to use |
| `lang` | auto | Force a language if your text mixes several |
| `speed` | `1.0` | `0.5` = slower, `1.5` = faster |
| `format` | `wav` | `wav`, `mp3` or `opus` |
| `precision` | `fp32` | Use `int8` to trade a little quality for more speed |

### Output

Each run stores the audio file and adds one dataset row with the audio URL, duration, voice used and processing time — easy to plug into Make, Zapier, n8n or your own backend.

### Pricing

No rental fee. You only pay Apify platform compute, which is typically a fraction of a cent per short clip.

### Notes

- For **Vietnamese**, use the Vietnamese Text to Speech Actor instead — this one is not trained on Vietnamese.
- Generated voices are synthetic. Make sure your use complies with the rules of the platform you publish on.

### For AI agents (MCP-ready)

This actor is built to be called by AI agents. It works out of the box with the
[Apify MCP Server](https://mcp.apify.com) — add it to Claude Desktop, Cursor or any MCP
client: the agent can produce voiceovers on its own.

```json
{
  "mcpServers": {
    "kokoro-tts": {
      "url": "https://mcp.apify.com/?actors=andrew_babo/kokoro-tts",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

#### Agent skill (paste into your agent's instructions)

```text
Use the "kokoro-tts" tool to turn text into natural speech in English,
Spanish, French, Italian, Portuguese, Hindi, Japanese or Chinese — 21
preset voices. It is the fastest, cheapest default for plain narration.
For Vietnamese use "vieneu-tts"; for voice cloning use "chatterbox-tts"
(English) or "qwen3-tts".

HOW TO CALL
- { "text": "...", "voice": "af_heart", "format": "mp3" }
- "speed" 0.5-1.5; "format" wav | mp3 | opus (mp3 for publishing).
- Long scripts are split automatically — send the whole text in one call
  rather than many small calls.

OUTPUT CONTRACT
- One row per run: audio_url, duration, voice, processing time.
- Give the user the audio_url; do not claim audio exists if
  errorCode / NO_INPUT is returned (empty text).
- These are synthetic voices — mention that when the user publishes them.
```

# Actor input Schema

## `text` (type: `string`):

Required text to synthesize. Kokoro automatically splits long text to respect its phoneme limit. Maximum 20,000 characters.

## `voice` (type: `string`):

Which speaker voice to use for the generated audio.

## `lang` (type: `string`):

espeak language code, e.g. en-us, en-gb, es, fr-fr. Leave empty to derive it from the voice.

## `speed` (type: `string`):

Speech rate multiplier. 1.0 is the natural pace of the voice.

## `precision` (type: `string`):

Which quantization of the Kokoro ONNX graph to run.

## `format` (type: `string`):

Container/codec of the returned audio file.

## `chunk_chars` (type: `integer`):

Kokoro caps at 510 phoneme tokens per pass; keep chunks small.

## `chunk_parallel` (type: `integer`):

How many chunks to synthesize at the same time. 0 lets the Actor pick based on available CPU cores.

## Actor input object example

```json
{
  "text": "Hello! This audio was generated by Kokoro running on Apify.",
  "voice": "af_heart",
  "speed": "1.0",
  "precision": "fp32",
  "format": "wav",
  "chunk_chars": 300,
  "chunk_parallel": 0
}
```

# Actor output Schema

## `audio` (type: `string`):

Generated audio record stored in the run's key-value store (audio.wav / audio.mp3 / audio.ogg).

## `metrics` (type: `string`):

Dataset rows with engine, duration, synthesis time, RTF, peak RAM and the audio URL.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "text": "Hello! This audio was generated by Kokoro running on Apify."
};

// Run the Actor and wait for it to finish
const run = await client.actor("andrew_babo/kokoro-tts").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "text": "Hello! This audio was generated by Kokoro running on Apify." }

# Run the Actor and wait for it to finish
run = client.actor("andrew_babo/kokoro-tts").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "text": "Hello! This audio was generated by Kokoro running on Apify."
}' |
apify call andrew_babo/kokoro-tts --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,andrew_babo/kokoro-tts"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/GCH9KiuRUi7wuRhuf/builds/yTfAqhyQ45alu25T8/openapi.json