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)