--- name: tiktok-uploader description: "Upload, schedule, and batch-manage TikTok videos via browser automation. Use when: user wants to upload a video to TikTok, schedule a TikTok post, batch upload multiple TikTok videos, or scan a directory for uploadable videos. NOT for: TikTok analytics, downloading videos, or managing comments/followers." homepage: https://github.com/wkaisertexas/tiktok-uploader user-invocable: true metadata: {"openclaw":{"emoji":"🎬","requires":{"bins":["python3","playwright"],"env":[]},"install":[{"id":"pip","kind":"pip","package":"tiktok-uploader","bins":["tiktok-uploader"],"label":"Install tiktok-uploader (pip)"},{"id":"playwright","kind":"pip","package":"playwright","bins":["playwright"],"label":"Install Playwright"}]}} ---

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