# AI Text-to-Speech Voiceover (`dami_studio/ai-tts-voiceover`) Actor

Turns text or a script into a downloadable AI voiceover audio file (MP3, WAV, Opus, or AAC) using OpenAI TTS voices. Built for faceless YouTube narration, IVR phone menus, audiobooks, and batch app prompts.

- **URL**: https://apify.com/dami\_studio/ai-tts-voiceover.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** AI, Automation, Other
- **Stats:** 5 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $40.00 / 1,000 voiceover generateds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## AI Text-to-Speech Voiceover

Turns a block of text or a full script into a natural-sounding AI voiceover file. Pick a voice, set the speed, and choose MP3, WAV, Opus, or AAC. It's meant for the usual narration jobs: faceless videos, audiobooks, IVR prompts, explainer voiceovers.

### How it works

The actor sends your text to an OpenAI-compatible TTS endpoint. Long scripts get split at sentence boundaries into chunks under ~3,500 characters, each chunk is synthesized separately, and the parts are stitched back into one file with ffmpeg (using stream copy, so there's no re-encode and no quality loss). Each finished audio file is saved to the run's key-value store and a row is pushed to the dataset.

### Input

Nothing is strictly required by the schema, but in practice you need an `openaiApiKey` and at least one of `text` or `texts`. If neither is provided the run errors out.

| Field | Required | Notes |
|-------|----------|-------|
| `text` | one of `text`/`texts` | The script to voice, as a single string. |
| `texts` | one of `text`/`texts` | Batch mode. Array of strings, or objects keyed by `script` / `scriptText` / `text` / `narration`. One audio file per item. |
| `voice` | no | `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. Default `onyx` (deep male). `nova` and `shimmer` are female. |
| `model` | no | `tts-1` (fast, default) or `tts-1-hd` (higher quality, costs more on the OpenAI side). |
| `format` | no | `mp3` (default), `wav`, `opus`, or `aac`. |
| `speed` | no | Playback speed from 0.25 to 4.0. Default `1.0`. Values outside that range are clamped. |
| `openaiApiKey` | yes in practice | Your OpenAI key, used for the TTS call. Stored as a secret. Falls back to the `OPENAI_API_KEY` env var if set. |
| `baseUrl` | no | Advanced. Point at any OpenAI-compatible `/audio/speech` endpoint. Defaults to `https://api.openai.com/v1`. |

### Output

Each input item produces one audio file in the key-value store and one dataset record. The record includes `audioKey` and `audioUrl` (where to fetch the file), `durationSeconds`, `characters`, `chunks` (how many pieces the script was split into), plus the `voice`, `model`, and resolved `format`. Failed items get a record with `ok: false` and the error message instead of stopping the whole run.

### Example

```json
{
  "text": "Welcome back to the channel. Today we're looking at one of the strangest mysteries of the deep ocean.",
  "voice": "onyx",
  "model": "tts-1",
  "format": "mp3",
  "speed": 1.0,
  "openaiApiKey": "sk-..."
}
```

### Pricing

$0.04 per voiceover, pay per result, no subscription. The OpenAI TTS usage is billed separately on your own key.

### Notes

This actor calls OpenAI for synthesis, so it needs your own OpenAI API key. Individual chunks are capped at 4,000 characters before they're sent, which keeps each request within the model's per-call limit; there's no hard limit on total script length since long inputs are chunked and concatenated.

# Actor input Schema

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

The text to convert to speech. Long scripts are chunked and stitched automatically.

## `texts` (type: `array`):

Array of strings OR objects (uses script/scriptText/text/narration). One audio file per item.

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

AI voice.

## `model` (type: `string`):

tts-1 (fast) or tts-1-hd (higher quality).

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

Output audio format.

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

Playback speed 0.25–4.0 (1.0 = normal).

## `openaiApiKey` (type: `string`):

Your OpenAI key (TTS). Kept private.

## `baseUrl` (type: `string`):

OpenAI-compatible base URL. Default https://api.openai.com/v1.

## Actor input object example

```json
{
  "text": "Welcome back to the channel. Today, we're diving into one of the strangest mysteries of the deep ocean.",
  "voice": "onyx",
  "model": "tts-1",
  "format": "mp3",
  "speed": "1.0"
}
```

# Actor output Schema

## `results` (type: `string`):

Result rows / metadata are stored in the default dataset (one row per item).

## `files` (type: `string`):

Generated media/files (video, audio, images, captions) are stored in the default key-value store.

# 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": "Welcome back to the channel. Today, we're diving into one of the strangest mysteries of the deep ocean."
};

// Run the Actor and wait for it to finish
const run = await client.actor("dami_studio/ai-tts-voiceover").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": "Welcome back to the channel. Today, we're diving into one of the strangest mysteries of the deep ocean." }

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": "Welcome back to the channel. Today, we'\''re diving into one of the strangest mysteries of the deep ocean."
}' |
apify call dami_studio/ai-tts-voiceover --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dami_studio/ai-tts-voiceover",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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