TikTok WebSocket API quick start

# pip install "websockets>=13"   (Python 3.9+)
import asyncio, json, os
from websockets.asyncio.client import connect

# Path: GET /v1/ws/status -> "path". Key: the WebSocket key, NOT the API key.
WS_URL = "wss://tiktok.1322.io/" + os.environ["TIKTOK_WS_PATH"].strip("/")
HEADERS = {"X-WS-Key": os.environ["TIKTOK_WS_KEY"]}

def handle(event):
    kind = event.get("type") or ""
    obj = event.get("object") or {}
    if kind == "tiktok.media.ready":
        # Same event_id as an earlier upload: attach the file, do not post again.
        print("media ready", event.get("event_id"), obj.get("media_url"))
        return
    account = event.get("account") or {}
    print(kind, account.get("username"), obj.get("kind"), obj.get("url"))

async def main():
    backoff = 1
    while True:
        try:
            async with connect(WS_URL, additional_headers=HEADERS) as ws:
                backoff = 1
                async for raw in ws:
                    try:
                        event = json.loads(raw)
                    except ValueError:
                        continue
                    if isinstance(event, dict):
                        handle(event)
        except Exception as exc:
            print("disconnected:", exc)
        await asyncio.sleep(backoff)
        backoff = min(backoff * 2, 30)

asyncio.run(main())

// npm install ws, save as consumer.mjs, run: node consumer.mjs   (Node 18+)
import WebSocket from "ws"

// Path: GET /v1/ws/status -> "path". Key: the WebSocket key, NOT the API key.
const WS_PATH = (process.env.TIKTOK_WS_PATH ?? "").split("/").filter(Boolean).join("/")
const WS_KEY = process.env.TIKTOK_WS_KEY
if (!WS_PATH || !WS_KEY) throw new Error("Set TIKTOK_WS_PATH and TIKTOK_WS_KEY")
const WS_URL = "wss://tiktok.1322.io/" + WS_PATH

function handle(event) {
  if (event.type === "tiktok.media.ready") {
    // Same event_id as an earlier upload: attach the file, do not post again.
    console.log("media ready", event.event_id, event.object?.media_url)
    return
  }
  console.log(event.type, event.account?.username, event.object?.kind, event.object?.url)
}

let backoff = 1000

function connect() {
  const ws = new WebSocket(WS_URL, { headers: { "X-WS-Key": WS_KEY } })
  ws.on("open", () => { backoff = 1000 })
  ws.on("message", (raw) => {
    let event
    try { event = JSON.parse(raw.toString()) } catch { return }
    if (event && typeof event === "object" && !Array.isArray(event)) handle(event)
  })
  ws.on("error", (err) => console.error("socket error:", err.message))
  ws.on("close", () => {
    setTimeout(connect, backoff)
    backoff = Math.min(backoff * 2, 30000)
  })
}

connect()

{
  "schema": "1322.tiktok.event.v1",
  "event_id": "01J9Z8QX4T7C2V1M0K3R5B6N7P",
  "sequence": 4821,
  "type": "tiktok.upload.created",
  "platform": "tiktok",
  "account": {
    "username": "examplecreator",
    "display_name": "Example Creator",
    "sec_uid": "MS4wLjABAAAA-example"
  },
  "object": {
    "video_id": "7300000000000000000",
    "url": "https://www.tiktok.com/@examplecreator/video/7300000000000000000",
    "kind": "video",
    "description": "studio day @friendcreator #launch",
    "hashtags": [
      "launch"
    ],
    "mentions": [
      "friendcreator"
    ],
    "duration": 27
  },
  "occurred_at": "2026-10-15T14:03:11Z",
  "observed_at": "2026-10-15T14:03:12Z",
  "delivery": {
    "mode": "live_only"
  }
}

curl "https://tiktok.1322.io/v1/ws/status" \
  -H "X-API-Key: $TIKTOK_API_KEY"

curl "https://tiktok.1322.io/v1/list" \
  -H "X-API-Key: $TIKTOK_API_KEY"

curl -X POST "https://tiktok.1322.io/v1/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TIKTOK_API_KEY" \
  -d '{ "username": "examplecreator" }'

curl -X POST "https://tiktok.1322.io/v1/untrack" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TIKTOK_API_KEY" \
  -d '{ "username": "examplecreator" }'

curl "https://tiktok.1322.io/v1/limits" \
  -H "X-API-Key: $TIKTOK_API_KEY"