Douyin_TikTok_Download_API

<div align="center">
<a href="https://douyin.wtf/" alt="logo"><img src="./logo/logo.svg" width="120" alt="Douyin_TikTok_Download_API"/></a>
</div>
<h1 align="center">Douyin_TikTok_Download_API</h1>

<div align="center">

[English](./README.md) | [简体中文](./README.zh-CN.md)

🚀 A self-hosted data API for [Douyin](https://www.douyin.com) and [TikTok](https://www.tiktok.com). One `docker compose up`, an identity pool that maintains itself, and a REST API, MCP server and web console on top.

Open source, free, and it runs on your own machine — no signup, no quota, nobody else in the path. It fetches posts, authors, comments and search, downloads video and image albums **without a watermark** (it picks the clean stream the platform already publishes rather than stripping anything), and keeps what it collects in your own PostgreSQL.

[![GitHub license](https://img.shields.io/github/license/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](LICENSE)
[![Release Version](https://img.shields.io/github/v/release/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/releases/latest)
[![GitHub Star](https://img.shields.io/github/stars/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/forks)
[![GitHub issues](https://img.shields.io/github/issues/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/issues)
<br>
[![CI](https://img.shields.io/github/actions/workflow/status/Evil0ctal/Douyin_TikTok_Download_API/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/actions/workflows/ci.yml)
[![CodeQL](https://img.shields.io/github/actions/workflow/status/Evil0ctal/Douyin_TikTok_Download_API/codeql.yml?branch=main&style=flat-square&label=CodeQL)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/actions/workflows/codeql.yml)
[![Last commit](https://img.shields.io/github/last-commit/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square&label=last%20commit)](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/commits/main)
<br>
[![Website](https://img.shields.io/badge/docs-douyin.wtf-2f6feb?style=flat-square&logo=readthedocs&logoColor=white)](https://douyin.wtf)
[![Live demo](https://img.shields.io/badge/demo-demo.douyin.wtf-22c55e?style=flat-square&logo=rocket&logoColor=white)](https://demo.douyin.wtf)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white)](./pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-ready-8A63D2?style=flat-square)](./documents/en/12-mcp.md)
[![Docker Pulls](https://img.shields.io/docker/pulls/evil0ctal/douyin_tiktok_download_api?style=flat-square&logo=docker&color=2496ed)](https://hub.docker.com/r/evil0ctal/douyin_tiktok_download_api)
[![Docker Image Size](https://img.shields.io/docker/image-size/evil0ctal/douyin_tiktok_download_api/latest?style=flat-square&logo=docker&color=2496ed)](https://hub.docker.com/r/evil0ctal/douyin_tiktok_download_api/tags)

</div>

## 💖 Sponsors

These sponsors paid to be here, and **Douyin_TikTok_Download_API** stays free and open because of it. To sponsor the project, see my [GitHub Sponsors page](https://github.com/sponsors/evil0ctal).

<div align="center">
    <a href="https://www.tikhub.io/?utm_source=douyin_tiktok_download_api&amp;utm_medium=referral&amp;utm_campaign=sponsor&amp;utm_content=readme_logo" target="_blank" rel="sponsored noopener">
        <img src="https://tikhub.io/logo.jpeg" width="100" alt="TikHub.io - Global Social Data & API Marketplace">
    </a>
    <h2>
        <a href="https://www.tikhub.io/?utm_source=douyin_tiktok_download_api&amp;utm_medium=referral&amp;utm_campaign=sponsor&amp;utm_content=readme_name" target="_blank" rel="sponsored noopener"><b>TikHub.io</b></a>
    </h2>
    <p>Your Ultimate Social Media Data &amp; API Marketplace</p>
    <p>
        Professional data solutions for Douyin, Xiaohongshu, TikTok, Instagram, YouTube,
        Twitter, and more.<br>
        Real-time Data | Flexible APIs | Seamless Integration | Competitive Pricing with Discounts
    </p>
    <p>
        Buy and sell custom APIs, services, and social media solutions on the<br>
        TikHub.io Marketplace, alongside developers, businesses and content creators.
    </p>
    <p><em>Trusted by leading global influencer marketing and social media intelligence platforms</em></p>
    <p>
        <a href="https://www.tikhub.io/?utm_source=douyin_tiktok_download_api&amp;utm_medium=referral&amp;utm_campaign=sponsor&amp;utm_content=readme_cta" target="_blank" rel="sponsored noopener"><b>→ Visit TikHub.io</b></a>
        &nbsp;·&nbsp;
        <a href="https://api.tikhub.io/?utm_source=douyin_tiktok_download_api&amp;utm_medium=referral&amp;utm_campaign=sponsor&amp;utm_content=readme_docs" target="_blank" rel="sponsored noopener">API docs</a>
    </p>
</div>

## 🧩 REER — a forum for reverse engineering

<div align="center">
    <a href="https://reer.dev" target="_blank" rel="noopener">
        <img src="./logo/reer.png" width="88" alt="REER">
    </a>
    <h3><a href="https://reer.dev" target="_blank" rel="noopener"><b>reer.dev</b></a></h3>
</div>

Somewhere to put what you work out. This project exists because people wrote down
how a signature was built; the forum is for the next round of that — signatures,
protocols, packers, anything taken apart.

Free, no advertising, and close to no rules beyond the obvious. Bilingual, English
and Chinese. Register and post; nothing is gated.

## 🎬 What it looks like

<div align="center">
    <img src="./screenshots/console-en.gif" width="900" alt="The DTK console: overview, identities, scheduler, playground, library, downloads, API docs and MCP"/>
</div>

One real call: paste a link, send it, get the normalised result back. The identity pool, the
scheduler and the API reference it passed through on the way are all in the same console.
The interface follows the browser's language, and both are written by hand rather than
machine-translated. [中文界面](./screenshots/console-zh.gif)

### Try it without installing anything

**<https://demo.douyin.wtf>** is a live instance, open to everyone. Sign in — the login page
fills the demo account in for you — and use the console: the playground, the scheduler,
the library, the API reference. The same account comes with an API key you can call the
scraping endpoints with, shown in plaintext on the API keys page.

It is read-only. Demo requests are not written to the request log or the archive, so the
database of a public instance cannot be filled by strangers, and switching demo mode off
ends every demo session and kills the key immediately.

**Rate limit: 30 requests per 10 seconds.** Go over it and you are cooled down for 10
seconds, during which every request is refused. It is a shared instance, and the identity
pool behind it is the ceiling for everybody using it at once.

What the demo is for is deciding whether to run your own. It is not a service to build
on — it can go down, be reset, or be switched off, and none of that will be announced.

## 🚀 v4 vs v5

v5 is a rewrite. It started from an empty branch and inherits no v4 code.

v4's real problem was never a shortage of features — it was that **the API would die
quietly and nobody would know**. A cookie expires, a signature algorithm changes, an
endpoint gets rate-limited, and you find out when someone files an issue. v5 puts
"you can see it" and "it heals itself" ahead of features.

| | v4 | v5 |
|---|---|---|
| Where identities come from | You copy cookies out of a browser into `config.yaml` | A headless browser mints guest identities, and the pool tops itself up when usable ones run low |
| How requests go out | Straight out, as they arrive | Health tiers, quantised LRU rotation, one in-flight lock per identity, a token bucket per (identity, endpoint), a circuit breaker per endpoint |
| When something breaks | You wait for a bug report | One structured record per request, live health for every identity and endpoint, visible in the console |
| Call style | Synchronous — send and wait | Asynchronous by default (`202` + `task_id`); add `?wait=` to go back to synchronous |
| What is kept | Nothing; parsed and discarded | PostgreSQL + Redis. Everything parsed is archived, so a post deleted upstream is still here |
| Access control | None; anyone can call it | API keys with scopes and roles, managed in the console |
| Interface | A single PyWebIO page | A React console: identity pool, scheduler, library, downloads, logs, diagnostics |
| Ways in | REST | REST, MCP and a CLI, all over the same service layer |
| Signing | X-Bogus, A_Bogus | a_bogus, X-Bogus, X-Gnarly, X-Dynosaur in pure Python, with a browser fallback |
| Deployment | `pip install -r requirements.txt` + `python start.py` | `docker compose up`, three images |
| Platforms | Douyin, TikTok, Bilibili | Douyin, TikTok |

Bilibili is the one thing that went backwards: v5 does not have it yet. It shares
neither the signing nor the identity machinery with Douyin and TikTok, so the rewrite
left it out for now.

### Still on v4?

v4's code stays on the [`v4` branch](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/tree/v4),
the image is still published, and one command brings it up:

```bash
docker run -d --name dtk-v4 --restart unless-stopped \
  -p 8080:80 evil0ctal/douyin_tiktok_download_api:V4.1.2
```

Then open <http://localhost:8080>; the API reference is at `/docs`. Port 8080 is
deliberate — v5 binds 8000, so the two versions can run side by side on one machine.

**Replace the Douyin cookie before you use it.** v4 has no identity pool, and the cookie
baked into the image expired long ago, so Douyin endpo