simple-tiktok-uploader 0.2.0

Simple TikTok video uploader using Playwright - no API key required

TikTok Uploader

Simple TikTok video uploader using Playwright. No API key required.

Features

• Simple API - Upload videos with one line of code
• CLI Tool - Upload from command line
• Session Management - Easy login flow, reusable sessions
• GitHub Actions Ready - Works in CI/CD pipelines
• Cross-Platform - Windows, macOS, Linux

Installation

pip install tiktok-uploader
playwright install chromium

Quick Start

1. Get Session Token (one-time)

Run this on your local machine (needs a display):

tiktok-upload auth

This opens a browser → you log in → it gives you a session token.

2. Upload Videos

CLI:

export TIKTOK_SESSION="your_token_here"
tiktok-upload video.mp4 --caption "My awesome video #fyp #viral"

Python:

from tiktok_uploader import upload

upload("video.mp4", "My awesome video #fyp #viral")

Usage

Command Line

# Login and get session token
tiktok-upload auth

# Upload a video
tiktok-upload upload video.mp4 --caption "Hello TikTok! #fyp"

# Upload with visibility setting
tiktok-upload upload video.mp4 --caption "Friends only" --visibility friends

# Check if session is valid
tiktok-upload check

Python API

from tiktok_uploader import TikTokUploader, upload

# Simple one-liner (reads TIKTOK_SESSION from env)
upload("video.mp4", "My caption #fyp")

# With more control
uploader = TikTokUploader(
    session="your_session_token",  # or reads from TIKTOK_SESSION env
    headless=True,
)

result = uploader.upload(
    video="video.mp4",
    description="My awesome video #fyp #viral",
    visibility="everyone",  # or "friends", "private"
)

if result.success:
    print("Upload successful!")
else:
    print(f"Upload failed: {result.error}")

Upload Multiple Videos

from tiktok_uploader import TikTokUploader

uploader = TikTokUploader()

videos = [
    {"video": "video1.mp4", "description": "First video #fyp"},
    {"video": "video2.mp4", "description": "Second video #viral"},
]

results = uploader.upload_many(videos)

GitHub Actions

name: Upload to TikTok

on:
  workflow_dispatch:

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install tiktok-uploader
          playwright install chromium --with-deps

      - name: Upload to TikTok
        run: tiktok-upload upload video.mp4 --caption "Automated upload! #fyp"
        env:
          TIKTOK_SESSION: ${{ secrets.TIKTOK_SESSION }}

Session Management

Getting a Session Token

tiktok-upload auth

This opens a browser for you to log in. After login, it outputs a session token.

Using the Session Token

Option 1: Environment Variable

export TIKTOK_SESSION="your_token"

Option 2: GitHub Secrets

1. Go to your repo → Settings → Secrets → New secret
2. Name: TIKTOK_SESSION
3. Value: your token

Option 3: Pass directly

uploader = TikTokUploader(session="your_token")

Session Expiration

Sessions last approximately 30 days. When expired, run tiktok-upload auth again.

Error Handling

from tiktok_uploader import upload, SessionExpiredError, LoginRequiredError

try:
    upload("video.mp4", "My caption")
except LoginRequiredError:
    print("No session found. Run 'tiktok-upload auth' first.")
except SessionExpiredError:
    print("Session expired. Run 'tiktok-upload auth' to refresh.")

Requirements

• Python 3.9+
• Playwright (with Chromium)

Limitations

• TikTok may change their site, which could break uploads
• Sessions expire after ~30 days
• Interactive login requires a display (run locally, use token in CI)

License

MIT