# Speech-to-Text Transcription (`hgservices/speech-to-text`) Actor Transcribe audio or video from YouTube and 1000+ other platforms, direct media URLs, or Key-Value Store uploads using Deepgram with speaker diarization. - **URL**: https://apify.com/hgservices/speech-to-text.md - **Developed by:** [Harish Garg](https://apify.com/hgservices) (community) - **Categories:** Videos, AI, MCP servers - **Stats:** 5 total users, 4 monthly users, 94.1% runs succeeded, NaN bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ### What does YouTube Speech-to-Text do? YouTube Speech-to-Text extracts audio from any **YouTube video** and converts it into accurate, formatted text using **Deepgram's Nova-3** speech recognition model. The Actor downloads the video's audio, sends it to Deepgram's API, and returns a full transcript with **speaker diarization** (identifying who said what), smart formatting (dates, numbers, punctuation), and language auto-detection. Try it out with any public YouTube URL. Powered by the Apify platform, you get API access, scheduling, webhook integrations, and seamless data export — all without managing infrastructure. ### Why use YouTube Speech-to-Text? - **Content repurposing** — Turn video podcasts, lectures, and interviews into blog posts, articles, or documentation - **Accessibility** — Generate transcripts for hearing-impaired audiences or multilingual translation workflows - **Research & analysis** — Search, index, and analyze spoken content at scale across multiple videos - **SEO** — Create text versions of your video content to improve search engine discoverability - **Compliance** — Maintain text records of meetings, webinars, and public broadcasts ### How to use YouTube Speech-to-Text 1. **Open the Actor** — Click "Try for free" on the Actor's page 2. **Enter the YouTube URL** — Paste the full URL of any public YouTube video 3. **Configure options** (optional) — Choose the transcription model, enable/disable speaker diarization, set a specific language, or adjust the maximum video length 4. **Run the Actor** — Click "Start" and wait for the transcription to complete 5. **Download results** — Get your transcript from the Key-Value Store or Dataset tabs No external API keys required — Deepgram transcription is included in the per-minute price. ### Input The Actor accepts the following input parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | `videoUrl` | string | Yes | URL of the YouTube video to transcribe | | `maxAudioMinutes` | integer | No | Maximum video length in minutes. Videos longer than this fail before any cost is incurred. Default: `240` (4 h). Max: `600` (10 h) | | `model` | enum | No | Deepgram model: `nova-3` (default), `nova-2`, `whisper-large`, `whisper-medium`, `whisper-base` | | `language` | string | No | Language code (e.g., `en`, `es`, `fr`) — leave empty for auto-detection | | `diarize` | boolean | No | Enable speaker diarization (default: `true`) | | `smartFormat` | boolean | No | Apply smart formatting to transcript (default: `true`) | ### Output The Actor stores two files in the Key-Value Store: - **`transcript.txt`** — Formatted transcript with speaker labels and paragraphs - **`transcript.json`** — Raw Deepgram API response with full metadata And pushes a summary to the Dataset (visible in the **Output** tab and via the dataset API): ```json { "videoUrl": "https://www.youtube.com/watch?v=...", "videoId": "dQw4w9WgXcQ", "title": "Example Video Title", "channel": "Example Channel", "channelUrl": "https://www.youtube.com/@example", "uploadDate": "2024-09-12", "viewCount": 1234567, "thumbnail": "https://i.ytimg.com/vi/.../maxresdefault.jpg", "model": "nova-3", "language": "en", "diarize": true, "durationSeconds": 342.5, "transcript": "[Speaker 0] ...", "transcriptLength": 4521, "speakerCount": 3 } ```` Example transcript output: ``` [Speaker 0] Welcome everyone to today's discussion about artificial intelligence. [Speaker 1] Thank you for having me. I think the most exciting development is in natural language processing. [Speaker 0] I completely agree. The advances in transformer models have been remarkable. ``` You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. ### Pricing / Cost estimation This Actor uses **pay-per-event** pricing — you only pay for what you use, with no Apify compute units, proxy bandwidth, or Deepgram fees to track separately. Everything is bundled in: | Event | Price (USD) | When charged | |-------|------------|--------------| | Video processed | $0.02 | Once per video, after audio is successfully downloaded | | Minute of audio transcribed | $0.015 | Per minute of audio (rounded up), only after transcription succeeds | **Example costs:** | Video length | Total cost | |-------------:|-----------:| | 5 min | ~$0.10 | | 30 min | ~$0.47 | | 1 h | ~$0.92 | | 2 h | ~$1.82 | | 4 h (default cap) | ~$3.62 | The default `maxAudioMinutes` cap of 240 minutes (4 hours) protects you from accidentally transcribing a marathon livestream. You can raise it up to 600 minutes (10 hours) if you need to, or lower it for tighter cost control. Videos that exceed the cap fail **before** any charge. ### Tips - **Set `maxAudioMinutes` lower** if you're running this on a schedule or via API to cap worst-case cost per run - **Shorter videos process faster** — Videos under 30 minutes typically transcribe in under a minute - **Use Nova-3 for best accuracy** — It's Deepgram's most advanced model with superior punctuation and speaker detection - **Set the language explicitly** if you know it — this improves accuracy for non-English content - **Disable diarization** for single-speaker videos to slightly reduce transcription time ### FAQ, disclaimers, and support **Is this Actor legal to use?** You are responsible for complying with YouTube's Terms of Service and applicable copyright laws. Only transcribe videos you have rights to or that are publicly available for personal/research use. **What video formats are supported?** Any public YouTube video. The Actor uses yt-dlp to download audio in the best available quality. **Can I transcribe private or unlisted videos?** Not directly through this Actor, as it relies on publicly accessible YouTube URLs. For issues, feature requests, or feedback, please use the **Issues** tab on this Actor's page. For custom solutions or enterprise needs, contact Apify support. # Actor input Schema ## `videoUrl` (type: `string`): URL of the YouTube video to transcribe ## `maxAudioMinutes` (type: `integer`): Maximum length (in minutes) of a video to transcribe. Videos longer than this will fail before any cost is incurred. Default is 240 (4 hours), maximum is 600 (10 hours, Deepgram's per-request ceiling). ## `model` (type: `string`): Deepgram speech recognition model to use ## `language` (type: `string`): Language code for transcription (leave empty for auto-detection) ## `diarize` (type: `boolean`): Identify and label different speakers in the audio ## `smartFormat` (type: `boolean`): Apply formatting to dates, times, numbers, and more ## `proxyConfiguration` (type: `object`): Apify Proxy settings. YouTube blocks Apify datacenter IPs with a bot challenge, so residential proxy is required. ## Actor input object example ```json { "videoUrl": "https://www.youtube.com/watch?v=f60dheI4ARg", "maxAudioMinutes": 240, "model": "nova-3", "language": "", "diarize": true, "smartFormat": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `transcriptFiles` (type: `string`): No description # 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 = { "videoUrl": "https://www.youtube.com/watch?v=f60dheI4ARg", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("hgservices/speech-to-text").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 = { "videoUrl": "https://www.youtube.com/watch?v=f60dheI4ARg", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("hgservices/speech-to-text").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 '{ "videoUrl": "https://www.youtube.com/watch?v=f60dheI4ARg", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call hgservices/speech-to-text --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=hgservices/speech-to-text", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Speech-to-Text Transcription", "description": "Transcribe audio or video from YouTube and 1000+ other platforms, direct media URLs, or Key-Value Store uploads using Deepgram with speaker diarization.", "version": "1.0", "x-build-id": "n5FOYUjT4YcvNNrCz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hgservices~speech-to-text/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hgservices-speech-to-text", "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/hgservices~speech-to-text/runs": { "post": { "operationId": "runs-sync-hgservices-speech-to-text", "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/hgservices~speech-to-text/run-sync": { "post": { "operationId": "run-sync-hgservices-speech-to-text", "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", "required": [ "videoUrl" ], "properties": { "videoUrl": { "title": "Video URL", "type": "string", "description": "URL of the YouTube video to transcribe" }, "maxAudioMinutes": { "title": "Max Audio Minutes", "minimum": 1, "maximum": 600, "type": "integer", "description": "Maximum length (in minutes) of a video to transcribe. Videos longer than this will fail before any cost is incurred. Default is 240 (4 hours), maximum is 600 (10 hours, Deepgram's per-request ceiling).", "default": 240 }, "model": { "title": "Deepgram Model", "enum": [ "nova-3", "nova-2", "whisper-large", "whisper-medium", "whisper-base" ], "type": "string", "description": "Deepgram speech recognition model to use", "default": "nova-3" }, "language": { "title": "Language", "type": "string", "description": "Language code for transcription (leave empty for auto-detection)", "default": "" }, "diarize": { "title": "Speaker Diarization", "type": "boolean", "description": "Identify and label different speakers in the audio", "default": true }, "smartFormat": { "title": "Smart Formatting", "type": "boolean", "description": "Apply formatting to dates, times, numbers, and more", "default": true }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Apify Proxy settings. YouTube blocks Apify datacenter IPs with a bot challenge, so residential proxy is required.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```