TikTok Video Uploader
Upload, schedule, and batch-manage TikTok videos using the tiktok-uploader Python library (Playwright-based browser automation wrapping TikTok's web upload page).
Setup
pip install tiktok-uploader
playwright install
Authentication
The user must provide one of these. Ask if not yet configured:
| Method | How to get it |
|---|
| Cookie file (recommended) | Export cookies.txt from browser using the "Get cookies.txt LOCALLY" extension. |
| Session ID | DevTools → Application → Cookies → .tiktok.com → copy sessionid value. |
| Cookie list | List of dicts: [{name, value, domain, path}]. |
Session cookies expire — if uploads fail with auth errors, the user needs fresh cookies.
Operations
Upload a single video
from tiktok_uploader.upload import TikTokUploader
with TikTokUploader(cookies="cookies.txt", headless=True) as uploader:
success = uploader.upload_video(
filename="video.mp4",
description="Check this out #fyp #viral @friend ",
visibility="everyone", # "everyone" | "friends" | "only_you"
comment=True,
stitch=True,
duet=True,
cover="thumbnail.png", # optional
)
print("Uploaded!" if success else "Failed.")
Schedule a video
from datetime import datetime, timezone
with TikTokUploader(sessionid="abc123...", headless=True) as uploader:
uploader.upload_video(
filename="video.mp4",
description="Dropping soon! #scheduled ",
schedule=datetime(2026, 3, 10, 14, 30, tzinfo=timezone.utc),
)
Rules: must be 20 min – 10 days in the future; minutes are rounded to nearest 5.
Batch upload
videos = [
{"path": "vid1.mp4", "description": "First #batch "},
{"path": "vid2.mp4", "description": "Second", "schedule": datetime(2026, 3, 10, 15, 0, tzinfo=timezone.utc)},
{"path": "vid3.mp4", "description": "Third", "visibility": "friends"},
]
with TikTokUploader(cookies="cookies.txt", headless=True) as uploader:
failed = uploader.upload_videos(videos)
if failed:
print(f"{len(failed)} videos failed")
Using the wrapper module
This skill ships a convenience wrapper at scripts/tiktok_manager.py:
from scripts.tiktok_manager import TikTokManager
mgr = TikTokManager(cookies="~/cookies.txt")
# Upload
mgr.upload("video.mp4", description="Hello TikTok! #fyp ")
# Schedule
mgr.upload("video.mp4", description="Scheduled!", schedule="2026-03-10T14:30")
# Batch
mgr.upload_batch([
{"path": "v1.mp4", "description": "First"},
{"path": "v2.mp4", "description": "Second", "schedule": "2026-03-10T15:00"},
])
# Scan directory for uploadable videos
videos = TikTokManager.scan_videos("~/Videos/tiktok", recursive=True)
Important Notes
- Hashtags & @mentions: Include in description, each tag followed by a space. Verify they exist.
- Description limit: ~150 characters.
- Rate limiting: TikTok throttles after many uploads. Space them out; wait hours if throttled.
- Headless mode: Set
headless=False to watch the browser for debugging.
- Proxy: Pass
proxy={"host": "...", "port": "..."} — Chrome only.
- Supported formats: .mp4, .mov, .avi, .wmv, .flv, .webm, .mkv, .m4v, .3gp, .3g2, .gif
- Fragility: Browser automation, not an official API. TikTok UI changes can break it.
Troubleshooting
| Problem | Fix |
|---|
| Auth/login error | Cookies expired → export fresh cookies.txt |
| Upload hangs | Try headless=False to see what's happening |
| Throttled/rate limited | Wait a few hours between batches |
| Selector errors | tiktok-uploader may need an update (pip install -U tiktok-uploader) |
