# AI Text-to-Speech Voiceover (`dami_studio/ai-tts-voiceover`) Actor Turn text or a script into a natural AI voiceover audio file. Pick from multiple voices, speed, and format (MP3/WAV/Opus/AAC). Handles long scripts automatically. For faceless videos, narration, audiobooks, and podcasts. Bring your own OpenAI API key. - **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:** 3 total users, 0 monthly users, 28.6% 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "AI Text-to-Speech Voiceover", "description": "Turn text or a script into a natural AI voiceover audio file. Pick from multiple voices, speed, and format (MP3/WAV/Opus/AAC). Handles long scripts automatically. For faceless videos, narration, audiobooks, and podcasts. Bring your own OpenAI API key.", "version": "0.1", "x-build-id": "Z9hi0wBTn2xrZjKDJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dami_studio~ai-tts-voiceover/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dami_studio-ai-tts-voiceover", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dami_studio~ai-tts-voiceover/runs": { "post": { "operationId": "runs-sync-dami_studio-ai-tts-voiceover", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dami_studio~ai-tts-voiceover/run-sync": { "post": { "operationId": "run-sync-dami_studio-ai-tts-voiceover", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "text": { "title": "Text / script", "type": "string", "description": "The text to convert to speech. Long scripts are chunked and stitched automatically." }, "texts": { "title": "Texts (batch)", "type": "array", "description": "Array of strings OR objects (uses script/scriptText/text/narration). One audio file per item." }, "voice": { "title": "Voice", "enum": [ "alloy", "echo", "fable", "onyx", "nova", "shimmer" ], "type": "string", "description": "AI voice.", "default": "onyx" }, "model": { "title": "Model", "enum": [ "tts-1", "tts-1-hd" ], "type": "string", "description": "tts-1 (fast) or tts-1-hd (higher quality).", "default": "tts-1" }, "format": { "title": "Audio format", "enum": [ "mp3", "wav", "opus", "aac" ], "type": "string", "description": "Output audio format.", "default": "mp3" }, "speed": { "title": "Speed", "type": "string", "description": "Playback speed 0.25–4.0 (1.0 = normal).", "default": "1.0" }, "openaiApiKey": { "title": "OpenAI API key (BYO)", "type": "string", "description": "Your OpenAI key (TTS). Kept private." }, "baseUrl": { "title": "API base URL (advanced)", "type": "string", "description": "OpenAI-compatible base URL. Default https://api.openai.com/v1." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```