# TikTok Video Downloader (`dead00/tiktok-video-downloader`) Actor

A simple and efficient actor that downloads TikTok videos in HD quality and stores them in organized Apify key-value stores for easy access and management.

- **URL**: https://apify.com/dead00/tiktok-video-downloader.md
- **Developed by:** [Dead](https://apify.com/dead00) (community)
- **Categories:** Videos, Social media, Developer tools
- **Stats:** 7 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 1.00 out of 5 stars

## Pricing

$23.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

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

## 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

## TikTok Video Downloader

A simple and efficient actor that downloads TikTok videos in HD quality and stores them in organized Apify key-value stores for easy access and management.

### 🌟 Features

- **🎬 HD Quality Downloads** - Automatically downloads videos in highest quality available
- **📦 Organized Storage** - Save videos to custom-named storage for better organization
- **🔗 Multiple URL Formats** - Supports all TikTok URL formats (full URLs, short links, etc.)
- **📊 Rich Metadata** - Extracts video info, author details, and engagement statistics
- **⚡ Batch Processing** - Download multiple videos in one run
- **💾 Easy Access** - Videos stored in Apify key-value store, ready to download
- **🎯 Simple Setup** - Just paste URLs and run!

### 🚀 Quick Start

1. **Paste TikTok video URLs** you want to download
2. **Name your storage** (optional) - keeps videos organized
3. **Choose quality** - HD (recommended) or Standard
4. **Run the actor** and download videos from Storage tab!

### 📥 Input Configuration

#### Required Settings

| Field | Type | Description |
|-------|------|-------------|
| **Video URLs** | Array | List of TikTok video URLs to download |

#### Optional Settings

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| **Storage Name** | String | `tiktok-videos` | Custom name for the key-value store (keeps videos organized) |
| **Download Quality** | String | `hd` | Video quality: `hd` or `standard` |

#### Example Input

```json
{
  "videoUrls": [
    "https://www.tiktok.com/@username/video/1234567890",
    "https://vm.tiktok.com/ZMhQxYz12/",
    "https://www.tiktok.com/@anotheruser/video/9876543210"
  ],
  "storageName": "client-campaign-videos",
  "downloadQuality": "hd"
}
````

### 📤 Output Format

Each downloaded video produces a dataset entry:

```json
{
  "videoUrl": "https://www.tiktok.com/@username/video/1234567890",
  "videoId": "1234567890",
  "title": "Amazing video title #viral #fyp",
  "author": "Creator Name",
  "authorUsername": "username",
  "thumbnail": "https://...",
  "duration": 15,
  
  "stats": {
    "views": 1250000,
    "likes": 185000,
    "comments": 2340,
    "shares": 8920
  },
  
  "quality": "HD",
  
  "downloadInfo": {
    "success": true,
    "storage_key": "1234567890",
    "storage_name": "client-campaign-videos",
    "quality": "HD",
    "file_size": 2458932,
    "file_size_mb": 2.35
  },
  
  "processedAt": "2024-12-18T10:30:45.123456"
}
```

### 💾 Accessing Downloaded Videos

#### Method 1: Via Apify Console (Easiest)

1. Go to your actor run page
2. Click on **Storage** tab
3. Click on **Key-Value Stores**
4. Find your storage (e.g., "client-campaign-videos")
5. Click on any video file to view or download
6. Videos are named by their video ID (e.g., `1234567890`)

#### Method 2: Via Apify API

```javascript
// Get storage
const store = await Actor.openKeyValueStore('your-storage-name');

// Get video
const video = await store.getValue('video-id');

// Download via API
const url = `https://api.apify.com/v2/key-value-stores/${storeId}/records/${videoId}?token=${apiToken}`;
```

### 📦 Custom Storage Names

#### Why Use Custom Storage Names?

- **Organization**: Keep different projects/campaigns separate
- **Easy Access**: Quickly find specific video collections
- **Clean Workflow**: Avoid mixing videos from different runs
- **Team Collaboration**: Share specific storages with team members

#### Naming Best Practices

✅ **Good Names:**

- `project-alpha-videos`
- `client-nike-campaign`
- `viral-trends-dec-2024`
- `competitor-analysis`

❌ **Avoid:**

- Names with spaces (use hyphens instead)
- Special characters (only letters, numbers, and hyphens)
- Very long names (keep under 63 characters)

#### Storage Name Rules

- Must start with a letter or number
- Can contain letters, numbers, and hyphens
- Cannot contain spaces or special characters
- Maximum 63 characters
- Must be unique within your account

### 🎬 Supported URL Formats

The actor supports all TikTok URL formats:

- Full URLs: `https://www.tiktok.com/@username/video/1234567890`
- Short links: `https://vm.tiktok.com/ZMhQxYz12/`
- Mobile links: `https://vt.tiktok.com/ZSjQxYz12/`
- Direct video: `https://www.tiktok.com/v/1234567890`

### 📊 Quality Options

#### HD Quality (Recommended)

- **Resolution**: Up to 1080p
- **File Size**: 2-10 MB per video (varies by duration)
- **Speed**: Slightly slower download
- **Best For**: Professional use, content analysis, archiving

#### Standard Quality

- **Resolution**: 720p or lower
- **File Size**: 1-5 MB per video
- **Speed**: Faster download
- **Best For**: Quick previews, bandwidth-limited environments

### 🎯 Use Cases

- **📱 Social Media Management** - Archive client's viral videos
- **📊 Content Research** - Download trending videos for analysis
- **🎬 Content Creation** - Collect inspiration and references
- **📈 Competitor Analysis** - Archive competitor content
- **🎓 Education** - Save educational TikToks for offline viewing
- **💼 Marketing Campaigns** - Backup campaign videos
- **🔍 Trend Analysis** - Collect videos from specific trends
- **🎨 Portfolio Building** - Save work samples

### ⚠️ Limitations

- Videos must be publicly accessible (not private accounts)
- Some region-restricted videos may not download
- Deleted or removed videos cannot be downloaded
- Maximum file size: Videos under 100 MB recommended
- Rate limits: Process videos sequentially to avoid blocks

### 🔧 Troubleshooting

#### "Failed to get video info"

**Possible causes**:

- Video is private or deleted
- URL format is incorrect
- Video is region-restricted

**Solutions**:

- Verify the video is publicly accessible
- Check URL is complete and correct

#### "Video download timeout"

**Possible causes**:

- Large video file
- Slow network connection
- Server temporarily busy

**Solutions**:

- Retry the download
- Try standard quality instead of HD
- Split large batches into smaller runs

#### "Storage name invalid"

**Cause**: Storage name doesn't meet requirements

**Solution**: Use only letters, numbers, and hyphens. Start with letter/number.

#### Downloads succeed but can't find videos

**Solution**:

1. Check the storage name you used
2. Go to Storage → Key-Value Stores
3. Look for your custom storage name
4. Videos are inside that store

### 📝 Best Practices

1. **Test First**: Start with 2-3 videos to verify everything works
2. **Use Descriptive Names**: Name your storage based on project/purpose
3. **Organize by Project**: Create separate storages for different projects
4. **Check Video Status**: Verify videos are public before downloading
5. **Monitor Costs**: Keep track of storage usage in Apify Console
6. **Batch Wisely**: Download 10-50 videos per run for optimal performance
7. **Clean Up**: Delete old storages you no longer need to save costs
8. **Backup Important Videos**: Download critical videos to local storage too

### 🔐 Legal & Ethics

- ✅ Only download videos for personal/research use
- ✅ Respect creator copyright and intellectual property
- ✅ Do not redistribute downloaded videos without permission
- ✅ Follow TikTok's Terms of Service
- ✅ Use downloads for legitimate purposes only
- ✅ Give credit to original creators when using content
- ✅ Respect privacy - don't download private/sensitive content

**Disclaimer**: Users are responsible for ensuring their use of downloaded videos complies with TikTok's Terms of Service, copyright laws, and applicable regulations.

### 🆘 Support

- **Issues**: Report bugs in Apify Console feedback
- **Documentation**: [Apify Documentation](https://docs.apify.com)
- **Community**: [Apify Discord](https://discord.gg/jyEM2PRvMU)
- **Storage Help**: [Key-Value Store Docs](https://docs.apify.com/storage/key-value-store)

### 💡 Tips & Tricks

#### Organizing Multiple Collections

Create different storages for different purposes:

```json
{
  "videoUrls": ["..."],
  "storageName": "project-alpha-week1"
}
```

Then for week 2:

```json
{
  "videoUrls": ["..."],
  "storageName": "project-alpha-week2"
}
```

#### Sharing Videos with Team

1. Download videos to custom storage
2. Go to Storage → Key-Value Stores → Your Storage
3. Share storage access with team members
4. Everyone can access videos from same storage

### 🏆 Why Choose This Actor?

- 🎯 **Simple**: Just paste URLs and run
- 📦 **Organized**: Custom storage keeps everything neat
- ⚡ **Fast**: Efficient batch downloading
- 💾 **Accessible**: Easy access via Apify Console or API
- 🎬 **Quality**: HD downloads when available
- 📊 **Complete**: Includes video metadata and stats
- 💰 **Affordable**: Optimized for minimal costs
- 🔧 **Reliable**: Error handling and retry logic

# Actor input Schema

## `videoUrls` (type: `array`):

List of TikTok video URLs to download. Supports various TikTok URL formats (full URLs, short links, etc.)

## `downloadQuality` (type: `string`):

Preferred video quality. HD downloads higher resolution when available (recommended). Standard is faster but lower quality.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.tiktok.com/@username/video/1234567890",
    "https://vm.tiktok.com/ZMhQxYz12/"
  ],
  "downloadQuality": "hd"
}
```

# Actor output Schema

## `overview` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("dead00/tiktok-video-downloader").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("dead00/tiktok-video-downloader").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 '{}' |
apify call dead00/tiktok-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dead00/tiktok-video-downloader",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TikTok Video Downloader",
        "description": "A simple and efficient actor that downloads TikTok videos in HD quality and stores them in organized Apify key-value stores for easy access and management.",
        "version": "0.0",
        "x-build-id": "7nnCfIYC8BGlKekzo"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/dead00~tiktok-video-downloader/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-dead00-tiktok-video-downloader",
                "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/dead00~tiktok-video-downloader/runs": {
            "post": {
                "operationId": "runs-sync-dead00-tiktok-video-downloader",
                "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/dead00~tiktok-video-downloader/run-sync": {
            "post": {
                "operationId": "run-sync-dead00-tiktok-video-downloader",
                "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": [
                    "videoUrls"
                ],
                "properties": {
                    "videoUrls": {
                        "title": "Video URLs",
                        "minItems": 1,
                        "type": "array",
                        "description": "List of TikTok video URLs to download. Supports various TikTok URL formats (full URLs, short links, etc.)",
                        "default": [
                            "https://www.tiktok.com/@mrbeast/video/7582653507375746334"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "downloadQuality": {
                        "title": "Download Quality",
                        "enum": [
                            "hd",
                            "standard"
                        ],
                        "type": "string",
                        "description": "Preferred video quality. HD downloads higher resolution when available (recommended). Standard is faster but lower quality.",
                        "default": "hd"
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```