🎬 Transcript Downloader - Youtube Video Scraper & Downloader

Convert YouTube videos into downloadable MP4 files using the Transcript Downloader API. Ideal for offline viewing, content archiving, and video repurposing. Works in bulk, with optional storage to Apify key-value store.

---

✨ Features

• 📁 Bulk processing of multiple YouTube video IDs
• 🕒 Polling logic with automatic retries
• 🧠 Progress tracking and run logs
• 🗂️ Optional Apify file storage to key-value store
• 🔔 Webhook support: Receive results via webhook instead of polling
• 🔐 Secure API token-based authentication

---

🔧 Input Parameters

Parameter	Type	Required	Default	Description
videoIds	array	✅ Yes	–	List of YouTube video IDs to process
apiToken	string	✅ Yes	–	Bearer token for Transcript Downloader API
downloadToApify	boolean	No	true	Whether to download MP4 files to Apify key-value store
maxWaitTime	number	No	15	Max time to wait for video processing (in minutes, range: 1–30)
pollingInterval	number	No	60	Interval between polling status (in seconds, range: 30–300)
includeWebhook	string	No	–	Webhook URL to receive results when video processing completes. Must be publicly reachable and accept POST requests

📥 Example Input

{
  "videoIds": ["Fqdz6A-5d04"],
  "apiToken": "your-api-token",
  "downloadToApify": true,
  "maxWaitTime": 15,
  "pollingInterval": 60
}

---

📤 Output Format

Each video generates an output record with metadata and processing info:

{
  "youtube_id": "Fqdz6A-5d04",
  "id": "01JW72M0AGW3M6R3QDCS30RD2P",
  "media_id": "abc123",
  "type": "youtube_video",
  "duration": "01:47:55",
  "cost": "1.079",
  "status": "success",
  "file_urls": ["https://drive.transcriptdownloader.com/videos/youtube-Fqdz6A-5d04.mp4?Expires=..."],
  "created_at": "2025-01-23T00:30:50.000Z",
  "storage_key": "video-Fqdz6A-5d04.mp4"
}

---

🚀 How to Use

1. Get your API token from Transcript Downloader
2. Add one or more YouTube video IDs (11-character alphanumeric IDs, e.g. Fqdz6A-5d04)
3. Set downloadToApify to true if you want MP4 files saved to Apify key-value store
4. Run the actor and access results in the dataset or key-value store

Supported Video ID Format

YouTube video IDs are exactly 11 characters long and contain only letters, numbers, hyphens, and underscores (e.g. Fqdz6A-5d04). You can find the ID in any YouTube URL after ?v= or /shorts/.

---

❌ Error Handling

This actor includes robust handling for common issues:

Status Code	Description
401	Invalid API key – check or regenerate your token
422	Video unavailable or cannot be processed
429	Too many requests – reduce polling frequency
503	Transcript Downloader API under maintenance
Custom	"You already have a pending download for this video"

If a video is already being processed, its ID will be extracted from the error response and polling will continue automatically.

---

⚠️ Rate Limiting & Performance

API Rate Limits

Scope	Limit	Window
Per User (API Token)	90 requests	1 minute
Per IP (unauthenticated)	90 requests	1 minute

When rate limits are exceeded, the API returns 429 Too Many Requests. The actor handles this automatically with built-in retry logic.

Video Download Cooldown

Endpoint	Limit	Cooldown Period	Scope
Single Video Download	1 request	5 minutes	Per video

If you request video for the same video within the 5-minute cooldown, the API returns a pending download response. The actor handles duplicate requests gracefully by extracting the existing download ID and continuing to poll.

Processing Times

Scenario	Typical Duration	Maximum Wait
Short videos (< 10 min)	< 1 minute	30 minutes
Medium videos (10-60 min)	1-5 minutes	30 minutes
Long videos (60+ min)	5-20 minutes	30 minutes

Retry Behavior

The actor automatically retries on transient errors (429, 500, 503) with exponential backoff (base delay 2s, up to 3 attempts). It does not retry on client errors (401, 403, 422) since those require user action.

Response Headers

The API returns rate limit headers you can monitor in logs:

Header	Description
X-RateLimit-Limit	Max requests allowed in window
X-RateLimit-Remaining	Requests remaining in current window
Retry-After	Seconds to wait before retrying (on 429)

---

🔔 Webhook Support

Instead of polling, you can receive results automatically via webhook. Pass a publicly reachable URL in the includeWebhook field, and the API will POST the results directly to your server when video processing completes.

How It Works

1. The webhook URL is sent with the initial API request only (not during polling)
2. One webhook is fired per video when processing completes or fails
3. The webhook payload is the exact same JSON the API endpoint would return
4. Failed deliveries are retried up to 3 times (at 10s, 30s, and 60s intervals)

Webhook Headers

Each delivery includes these custom headers to identify the event:

Header	Description
X-Webhook-Endpoint	downloads/video
X-Webhook-Original-Status	HTTP status code of the result (e.g. 200)
X-Webhook-Download-Id	The download record ID

Example with Webhook

{
  "videoIds": ["Fqdz6A-5d04"],
  "apiToken": "your-token",
  "includeWebhook": "https://your-domain.com/webhook"
}

Important Notes

• The URL must be publicly reachable (no localhost or private IPs)
• Your endpoint must accept POST requests and return a 2xx status
• Test your webhook URL first using the API test endpoint
• The webhook is registered once at request time — it cannot be added after a job has started

---

💡 Best Practices

• ✅ Respect rate limits to avoid 429 errors
• ⏳ Use polling wisely — longer intervals for large queues
• ⏳ Avoid re-requesting the same video within the 5-minute cooldown
• 🔐 Keep your apiToken secret (never log it)
• 🧠 Monitor output for incomplete or failed downloads
• 🗂️ Store large video files in Apify only when needed — allocate at least 2GB memory for long videos

---

📈 Monitoring

Track performance and usage with Apify tools:

• Run history
• Success/failure rates
• Storage and resource usage
• Output file availability

---

💳 Pricing & Billing

The Transcript Downloader API used by this actor requires a valid API token. API usage is billed separately and is based on processing time and file size.

📊 We charge per minute of video. Visit our site to checkout pricing. View full details and subscription plans on our pricing page

---

🙋 Support

Need help? Visit Transcript Downloader Support. We respond within 24 business hours.

---

📄 License

This actor is provided under the ISC License.