# Text To Speech (`calm_necessity/text-to-speech`) Actor

AI Text-to-Speech API that converts written text into high-quality natural voice audio. Supports multiple voices, languages, adjustable speed and pitch, ideal for audiobooks, podcasts, accessibility, automation, and voice-enabled applications.

- **URL**: https://apify.com/calm\_necessity/text-to-speech.md
- **Developed by:** [Taher Ali Badnawarwala](https://apify.com/calm_necessity) (community)
- **Categories:** AI, Other, Automation
- **Stats:** 15 total users, 0 monthly users, 93.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 results

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

## Text to Speech Actor

An Apify Actor that converts text to speech using AI-powered voice synthesis technology. Simply provide the text you want to convert, along with language and voice preferences, and the Actor will generate a high-quality audio file for you.

### What This Tool Does

This Actor connects to the MultipleWords text-to-speech API to convert written text into natural-sounding speech. It accepts text input along with language and voice configuration, processes the request through the API, and returns a downloadable audio file along with detailed metadata about the voice generation.

**Key Features:**

🎙️ Convert text to natural-sounding speech\
🚀 Fast and automated audio generation\
📦 Structured output with audio URLs and metadata\
🔄 Reliable error handling and validation\
📊 Complete generation details and timestamps\
🌍 Support for multiple languages and voices

### Purpose & Use Cases

This tool is designed to help individuals, businesses, and developers automate text-to-speech conversion for various purposes:

#### Content Creation

- Generate voiceovers for videos and presentations
- Create audio versions of blog posts and articles
- Produce podcast introductions and outros
- Generate narration for e-learning courses

#### Accessibility

- Convert written content to audio for visually impaired users
- Create audio descriptions for multimedia content
- Generate spoken versions of documents and reports
- Make content accessible through audio format

#### Business & Marketing

- Create automated phone system messages
- Generate voice prompts for IVR systems
- Produce marketing audio content
- Create audio advertisements and announcements

#### Development & Automation

- Integrate text-to-speech into automated workflows
- Batch convert multiple text documents to audio
- Create audio content programmatically via API integration
- Generate dynamic voice content for applications

#### Media Production

- Quickly generate voiceovers for video projects
- Create multiple voice variations for A/B testing
- Produce audio content for social media
- Generate voice samples and demos

### Input Parameters

The Actor requires the following input:

#### `text` (Required)

**Type:** String\
**Description:** The text content you want to convert to speech. Can be a single sentence, paragraph, or multiple paragraphs.\
**Example:** `"Technology that thinks with you, builds for you, and moves you forward. Welcome to the future—simple, smart, and powered by AI."`\
**Best Practices:**

- Use clear, well-formatted text
- Include proper punctuation for natural pauses
- Break long content into paragraphs for better audio flow
- Avoid special characters that may cause issues

#### `language_id` (Required)

**Type:** String\
**Description:** Language identifier for the speech synthesis (e.g., 'en' for English, 'es' for Spanish, 'fr' for French).\
**Default:** `"en"`\
**Example:** `"en"`, `"es"`, `"fr"`, `"de"`

#### `voice_id` (Required)

**Type:** String\
**Description:** Voice identifier specifying the voice type to use (e.g., 'male' or 'female').\
**Default:** `"male"`\
**Example:** `"male"`, `"female"`

#### `user_id` (Required)

**Type:** Integer\
**Description:** User identifier for the API authentication.\
**Default:** `663569`\
**Example:** `663569`

#### `isPro` (Required)

**Type:** Integer\
**Description:** Pro account flag indicating whether to use premium features (0 = No, 1 = Yes).\
**Default:** `0`\
**Valid Values:** `0` or `1`

### Output Structure

The Actor returns structured data containing the generated audio file information:

```json
{
  "status": "success",
  "file_name": "voice_20260127_072606_295b10fe.mp3",
  "access_url": "https://multiplewords.nyc3.cdn.digitaloceanspaces.com/text_to_voice/voice_20260127_072606_295b10fe.mp3",
  "voice_used": "en-AU-WilliamNeural",
  "details": {
    "id": 328186,
    "video_url": "https://multiplewords.nyc3.cdn.digitaloceanspaces.com/text_to_voice/voice_20260127_072606_295b10fe.mp3",
    "source_video_url": "",
    "video_description": "Technology that thinks with you, builds for you, and moves you forward.\nWelcome to the future—simple, smart, and powered by AI.",
    "video_name": "Technology that thinks with you, builds for you, and moves you forward.\nWelcome to the future—simple, smart, and powered by AI.",
    "video_description_to": "",
    "fps": 10,
    "video_length": 5,
    "creativity": 8.5,
    "isMusic": true,
    "isPro": false,
    "video_thumbnail": "https://multiplewords.nyc3.digitaloceanspaces.com/mw_assets/mw_logo_square_.jpg",
    "video_created_at": "2026-01-27T07:26:07.665739Z",
    "video_updated_at": "2026-01-27T07:26:07.665767Z",
    "engine": 35,
    "url_slug": "",
    "job_key": "0",
    "job_status": 1,
    "rating": 0,
    "feedback": "",
    "extra_1": null,
    "extra_2": null,
    "extra_3": null,
    "extra_4": null,
    "extra_5": null,
    "extra_6": null,
    "attempts": 3,
    "is_public": true,
    "isIndexed": false,
    "is_active": true,
    "number_of_times_played": 1,
    "user_id": 663569,
    "video_category_id": 1,
    "language_id": 49
  }
}
```

#### Output Fields Explained

- **status**: Success indicator ("success" = successful conversion)
- **file\_name**: Name of the generated audio file
- **access\_url**: Direct URL to download the generated audio file (MP3 format)
- **voice\_used**: The specific voice model used for synthesis (e.g., "en-AU-WilliamNeural")
- **details**: Complete metadata about the audio generation
  - **id**: Unique identifier for the generated audio
  - **video\_url**: URL to the audio file (same as access\_url)
  - **video\_length**: Duration of the audio in seconds
  - **video\_created\_at**: Timestamp when the audio was created
  - **job\_status**: Status of the generation job
  - **user\_id**: User identifier used for the request
  - **language\_id**: Language identifier used

### How to Use

#### Running Locally

1. **Install dependencies:**

```bash
npm install
```

2. **Run the Actor:**

```bash
apify run
```

3. **Provide input when prompted, or create an input file in `storage/key_value_stores/default/INPUT.json`:**

```json
{
  "language_id": "en",
  "voice_id": "male",
  "user_id": 663569,
  "isPro": 0,
  "text": "Technology that thinks with you, builds for you, and moves you forward. Welcome to the future—simple, smart, and powered by AI."
}
```

#### Deploy to Apify Platform

1. **Login to Apify:**

```bash
apify login
```

2. **Deploy the Actor:**

```bash
apify push
```

3. **Run on Apify Console:**

   - Go to **Actors -> My Actors**
   - Select your **Text to Speech Actor**
   - Enter your text and configuration in the input form
   - Click **"Start"** to generate your audio file

#### Using via API

Once deployed, you can call the Actor via Apify API:

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~text-to-speech/run-sync" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language_id": "en",
    "voice_id": "male",
    "user_id": 663569,
    "isPro": 0,
    "text": "Create a professional voiceover for a tech product launch announcement"
  }'
```

### Integration Examples

#### With Make (Integromat)

- Connect the Actor to your Make workflows
- Automatically generate voiceovers when new content is created
- Send generated audio files to storage services or email
- Create automated content pipelines with text-to-speech

#### With Zapier

- Trigger audio generation from form submissions
- Automatically add audio files to Google Drive or Dropbox
- Send audio notifications via Slack or email
- Convert blog posts to audio automatically

#### With Custom Applications

- Integrate via Apify API into your web applications
- Batch convert multiple text documents to audio
- Create automated voiceover workflows
- Build custom text-to-speech services

### Technical Details

- **Runtime:** Node.js 18+
- **Dependencies:** Apify SDK v3.5.2+
- **API Endpoint:** `https://shorts.multiplewords.com/mwvideos/api/voice_from_text`
- **Request Method:** POST
- **Content Type:** multipart/form-data
- **Response Format:** JSON
- **Audio Format:** MP3

### Error Handling

The Actor includes comprehensive error handling:

- Validates all required input parameters before processing
- Handles API errors gracefully with detailed error messages
- Provides informative error messages in logs
- Returns appropriate exit codes for debugging
- Validates API response status and structure

### Resources

- [Apify SDK Documentation](https://docs.apify.com/sdk/js)
- [Apify Platform Documentation](https://docs.apify.com/platform)
- [Apify Academy - Node.js Tutorials](https://docs.apify.com/academy/node-js)
- [Join Apify Developer Community](https://discord.com/invite/jyEM2PRvMU)

### Support

For issues, questions, or feature requests, please refer to the Apify documentation or community forums.

***

**Built with ❤️ using Apify SDK**

# Actor input Schema

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

Text to convert to speech

## Actor input object example

```json
{
  "text": "Technology that thinks with you, builds for you, and moves you forward.\nWelcome to the future—simple, smart, and powered by AI."
}
```

# 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": `Technology that thinks with you, builds for you, and moves you forward.
Welcome to the future—simple, smart, and powered by AI.`
};

// Run the Actor and wait for it to finish
const run = await client.actor("calm_necessity/text-to-speech").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": """Technology that thinks with you, builds for you, and moves you forward.
Welcome to the future—simple, smart, and powered by AI.""" }

# Run the Actor and wait for it to finish
run = client.actor("calm_necessity/text-to-speech").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": "Technology that thinks with you, builds for you, and moves you forward.\\nWelcome to the future—simple, smart, and powered by AI."
}' |
apify call calm_necessity/text-to-speech --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=calm_necessity/text-to-speech",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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