Skip to content
Back to search

Douyin_TikTok_Download_API

๐Ÿš€ ๆŠ–้Ÿณใ€TikTok ๆ•ฐๆฎ้‡‡้›†ไธŽๆ— ๆฐดๅฐ่ง†้ข‘ไธ‹่ฝฝ API๏ผŒ่‡ชๆ‰˜็ฎก๏ผŒๆ”ฏๆŒ MCP ่ฐƒ็”จไธŽ Docker ไธ€้”ฎ้ƒจ็ฝฒใ€‚| Self-hosted TikTok & Douyin scraper and no-watermark video downloader โ€” async REST API, MCP server, CLI and web console for posts, profiles, comments and playlists. Self-healing identity pool, PostgreSQL archive, one docker compose up.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Evil0ctal/Douyin_TikTok_Download_API with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Evil0ctal/Douyin_TikTok_Download_API'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/evil0ctal--douyin-tiktok-download-api/badge.svg)](/listings/evil0ctal--douyin-tiktok-download-api)

HTML

<a href="/listings/evil0ctal--douyin-tiktok-download-api"><img src="/api/listings/evil0ctal--douyin-tiktok-download-api/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

If you would rather not think about it, the guided script asks a few questions and brings the stack up โ€” it works out your distribution, checks for Docker, and scales the resource limits to the machine:

curl -fsSL https://raw.githubusercontent.com/Evil0ctal/Douyin_TikTok_Download_API/main/install/install.sh -o install.sh
less install.sh    # reading it first is a good habit
bash install.sh

**Afterwards the same script is the operations tool.** Run it again and it finds the install and opens a menu: status, upgrade (compared against the latest GitHub release), passwords, an extra administrator, backup and restore, runtime settings, disk cleanup, stop or uninstall. `--manage` goes straight there.

Details in [install/README.md](./install/README.md). The manual route follows.

There are two ways to install this; below is the recommended one. For the by-hand route, see [Without Docker](#without-docker).

| How | Who for | Full steps | |---|---|---| | **Docker Compose** (recommended) | Almost everyone, production included | [Installation ยท First install](./documents/en/02-installation.md#first-install) | | By hand | Docker is not an option, or you are changing the code | [For development](./documents/en/02-installation.md#running-without-docker) ยท [On bare metal](./documents/en/02-installation.md#a-production-install-without-docker) |

> **Installing from mainland China?** Switch your mirrors before you start, or the pull will > most likely time out: > [Network preparation in mainland China](./documents/en/02-installation.md#network-preparation-in-mainland-china).

You need Docker and Docker Compose. Start by cloning the repository โ€” the compose file, the Dockerfiles and the migrations all live in it, and the default branch is v5:

git clone https://github.com/Evil0ctal/Douyin_TikTok_Download_API.git
cd Douyin_TikTok_Download_API

Nothing in the repository ships a default password or key, so write `.env` next:

POSTGRES_PASSWORD=$(openssl rand -hex 24)
REDIS_PASSWORD=$(openssl rand -hex 24)
cat > .env <<EOF
DTK_SECRET_KEY=$(openssl rand -base64 48)
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
REDIS_PASSWORD=${REDIS_PASSWORD}
DTK_DATABASE_URL=postgresql+asyncpg://dtk:${POSTGRES_PASSWORD}@postgres:5432/dtk
DTK_REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0
EOF
docker compose -p dtk -f docker/compose.yml up -d
docker compose -p dtk -f docker/compose.yml logs api   # prints the setup token

Open <http://127.0.0.1:8000> and use the token from the log to create the first administrator.

Where the image comes from

By default it is built locally: the first `up` compiles the application image from the Dockerfile in this repository, which takes a few minutes. To skip that, point compose at the published image instead:

export DTK_IMAGE=evil0ctal/douyin_tiktok_download_api
export DTK_IMAGE_TAG=latest
docker compose -p dtk -f docker/compose.yml pull
docker compose -p dtk -f docker/compose.yml up -d

The `pull` is not optional: these services declare both `image` and `build`, so compose builds from the local Dockerfile whenever the image is not already on the machine rather than reaching for a registry.

Images are published for `linux/amd64` and `linux/arm64`, so Apple Silicon and a Raspberry Pi both run natively. The browser container is not published: it installs CloakBrowser from a pinned commit, and that pin is a security control that should be yours to choose, so it stays a local build.

Without Docker

Supported, and it is how the project itself is developed. You provide PostgreSQL 17 (**with the TimescaleDB extension** โ€” a plain `postgres:17` will not do), Redis 8, Python 3.12 and uv, plus Node 22 if you build the console. Two sets of steps:

- [Running without Docker](./documents/en/02-installation.md#running-without-docker) โ€” for development; Postgres and Redis still come from containers

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 701 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <a href="https://douyin.wtf/" alt="logo"><img src="./logo/logo.svg" width="120" alt="Douyin_TikTok_Download_API"/></a>
  3. </div>
  4. <h1 align="center">Douyin_TikTok_Download_API</h1>
  5. <div align="center">
  6. [English](./README.md) | [็ฎ€ไฝ“ไธญๆ–‡](./README.zh-CN.md)
  7. ๐Ÿš€ A self-hosted data API for [Douyin](https://www.douyin.com), [TikTok](https://www.tiktok.com) and [Bilibili](https://www.bilibili.com). One `docker compose up`, an identity pool that maintains itself, and a REST API, MCP server and web console on top.
  8. Open source, free, and it runs on your own machine โ€” no signup, no quota, nobody else in the path. It fetches posts, authors and comments, sounds, hashtags, live rooms, trending boards and search results, 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. A video it has downloaded can be turned into text on the same machine, offline, and an AI agent can drive all of it over MCP.
  9. [![GitHub license](https://img.shields.io/github/license/Evil0ctal/Douyin_TikTok_Download_API?style=flat-square)](LICENSE)
  10. [![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)
  11. [![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)
  12. [![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)
  13. [![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)
  14. <br>
  15. [![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)
  16. [![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)
  17. [![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)
  18. <br>
  19. [![Website](https://img.shields.io/badge/docs-douyin.wtf-2f6feb?style=flat-square&logo=readthedocs&logoColor=white)](https://douyin.wtf)
  20. [![Live demo](https://img.shields.io/badge/demo-demo.douyin.wtf-22c55e?style=flat-square&logo=rocket&logoColor=white)](https://demo.douyin.wtf)
  21. [![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white)](./pyproject.toml)
  22. [![MCP](https://img.shields.io/badge/MCP-ready-8A63D2?style=flat-square)](./documents/en/12-mcp.md)
  23. [![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)
  24. [![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)
  25. </div>
  26. ## ๐Ÿ’– Sponsors
  27. 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).
  28. <div align="center">
  29. <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">
  30. <img src="https://tikhub.io/logo.jpeg" width="100" alt="TikHub.io - Global Social Data & API Marketplace">
  31. </a>
  32. <h2>
  33. <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>
  34. </h2>
  35. <p>Your Ultimate Social Media Data &amp; API Marketplace</p>
  36. <p>
  37. Professional data solutions for Douyin, Xiaohongshu, TikTok, Instagram, YouTube,
  38. Twitter, and more.<br>
  39. Real-time Data | Flexible APIs | Seamless Integration | Competitive Pricing with Discounts
  40. </p>
  41. <p>
  42. Buy and sell custom APIs, services, and social media solutions on the<br>
  43. TikHub.io Marketplace, alongside developers, businesses and content creators.
  44. </p>
  45. <p><em>Trusted by leading global influencer marketing and social media intelligence platforms</em></p>
  46. <p>
  47. <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>
  48. &nbsp;ยท&nbsp;
  49. <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>
  50. </p>
  51. </div>
  52. ## ๐Ÿงฉ REER โ€” a forum for reverse engineering
  53. <div align="center">
  54. <a href="https://reer.dev" target="_blank" rel="noopener">
  55. <img src="./logo/reer.png" width="88" alt="REER">
  56. </a>
  57. <h3><a href="https://reer.dev" target="_blank" rel="noopener"><b>reer.dev</b></a></h3>
  58. </div>
  59. Somewhere to put what you work out. This project exists because people wrote down
  60. how a signature was built; the forum is for the next round of that โ€” signatures,
  61. protocols, packers, anything taken apart.
  62. Free, no advertising, and close to no rules beyond the obvious. Bilingual, English
  63. and Chinese. Register and post; nothing is gated.
  64. ## ๐ŸŽฌ What it looks like
  65. <div align="center">
  66. <img src="./screenshots/console-en.gif" width="900" alt="The DTK console: overview, identities, scheduler, playground, library, downloads, API docs and MCP"/>
  67. </div>
  68. One real call: paste a link, send it, get the normalised result back. The identity pool, the
  69. scheduler and the API reference it passed through on the way are all in the same console.
  70. The interface follows the browser's language, and both are written by hand rather than
  71. machine-translated. [ไธญๆ–‡็•Œ้ข](./screenshots/console-zh.gif)
  72. ### Try it without installing anything
  73. **<https://demo.douyin.wtf>** is a live instance, open to everyone. Sign in โ€” the login page
  74. fills the demo account in for you โ€” and use the console: the playground, the scheduler,
  75. the library, the API reference. The same account comes with an API key you can call the
  76. scraping endpoints with, shown in plaintext on the API keys page.
  77. It is read-only. Demo requests are not written to the request log or the archive, so the
  78. database of a public instance cannot be filled by strangers, and switching demo mode off
  79. ends every demo session and kills the key immediately.
  80. **Rate limit: 30 requests per 10 seconds.** Go over it and you are cooled down for 10
  81. seconds, during which every request is refused. It is a shared instance, and the identity
  82. pool behind it is the ceiling for everybody using it at once.
  83. What the demo is for is deciding whether to run your own. It is not a service to build
  84. on โ€” it can go down, be reset, or be switched off, and none of that will be announced.
  85. ## ๐Ÿš€ v4 vs v5
  86. v5 is a rewrite. It started from an empty branch and inherits no v4 code.
  87. v4's real problem was never a shortage of features โ€” it was that **the API would die
  88. quietly and nobody would know**. A cookie expires, a signature algorithm changes, an
  89. endpoint gets rate-limited, and you find out when someone files an issue. v5 puts
  90. "you can see it" and "it heals itself" ahead of features.
  91. | | v4 | v5 |
  92. |---|---|---|
  93. | 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 |
  94. | 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 |
  95. | 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 |
  96. | Call style | Synchronous โ€” send and wait | Asynchronous by default (`202` + `task_id`); add `?wait=` to go back to synchronous |
  97. | What is kept | Nothing; parsed and discarded | PostgreSQL + Redis. Everything parsed is archived, so a post deleted upstream is still here |
  98. | Access control | None; anyone can call it | API keys with scopes and roles, managed in the console |
  99. | Interface | A single PyWebIO page | A React console: identity pool, scheduler, library, downloads, logs, diagnostics |
  100. | Ways in | REST | REST, MCP and a CLI, all over the same service layer |
  101. | Signing | X-Bogus, A_Bogus | a_bogus, X-Bogus, X-Gnarly, X-Dynosaur and Bilibili's WBI in pure Python, with a browser fallback |
  102. | Deployment | `pip install -r requirements.txt` + `python start.py` | `docker compose up`, three images |
  103. | Platforms | Douyin, TikTok, Bilibili | Douyin, TikTok, Bilibili |
  104. Bilibili was the one thing that went backwards in 5.0, because it shares neither the
  105. signing nor the identity machinery with Douyin and TikTok. It is back in 5.1.6, with
  106. the two pieces of its own that needed writing: its WBI signature in pure Python, and
  107. guest identities minted over plain HTTP, so a Bilibili pool needs no browser container.
  108. ### Still on v4?
  109. v4's code stays on the [`v4` branch](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/tree/v4),
  110. the image is still published, and one command brings it up:
  111. ```bash
  112. docker run -d --name dtk-v4 --restart unless-stopped \
  113. -p 8080:80 evil0ctal/douyin_tiktok_download_api:V4.1.2
  114. ```
  115. Then open <http://localhost:8080>; the API reference is at `/docs`. Port 8080 is
  116. deliberate โ€” v5 binds 8000, so the two versions can run side by side on one machine.
  117. **Replace the Douyin cookie before you use it.** v4 has no identity pool, and the cookie
  118. baked into the image expired long ago, so Douyin endpoints answer `400` until you put
  119. your own in:
  120. ```bash
  121. docker cp dtk-v4:/app/crawlers/douyin/web/config.yaml ./douyin-web.yaml
  122. # replace the Cookie line with one from your browser, then save
  123. docker rm -f dtk-v4
  124. docker run -d --name dtk-v4 --restart unless-stopped -p 8080:80 \
  125. -v "$PWD/douyin-web.yaml:/app/crawlers/douyin/web/config.yaml" \
  126. evil0ctal/douyin_tiktok_download_api:V4.1.2
  127. ```
  128. TikTok's two config files are at `/app/crawlers/tiktok/web/config.yaml` and
  129. `/app/crawlers/tiktok/app/config.yaml`, and are mounted the same way.
  130. To keep it under Compose instead, one file is enough โ€” with `douyin-web.yaml` already
  131. copied out next to it, or Docker will create a *directory* under that name and the app
  132. will fail to read its config:
  133. ```yaml
  134. # compose.yml
  135. services:
  136. app:
  137. image: evil0ctal/douyin_tiktok_download_api:V4.1.2
  138. container_name: dtk-v4
  139. restart: unless-stopped
  140. ports:
  141. - "8080:80"
  142. environment:
  143. TZ: Asia/Shanghai
  144. volumes:
  145. - ./douyin-web.yaml:/app/crawlers/douyin/web/config.yaml
  146. ```
  147. ```bash
  148. docker rm -f dtk-v4 # the container from the run above holds the name
  149. docker compose -p dtk-v4 up -d
  150. ```
  151. `main` is v5 now and `latest` is the newest v5 release โ€” it moves when a release is cut, never
  152. on a push to `main` โ€” so **pin the tag to stay on v4**. `V4.1.2` is the last v4 release; the
  153. branch merged a few PRs after it (Bilibili downloads, cookie hot-reload), and that code is
  154. published under the commit tag `5be4838`.
  155. There is no guided installer for v4 โ€” the script in Quick start below installs v5. What
  156. is above is all v4 gets: the branch still takes PRs, but nothing new is built on it, and
  157. a fresh install should start on v5.
  158. ### Building this together
  159. There are a few group chats around my open-source projects. If you want to work
  160. on this one, or just talk shop, add me on WeChat at **`Evil0ctal`** with the note
  161. **github ไบคๆต** and I will add you.
  162. The groups are for learning from each other. **No advertising and nothing
  163. illegal** โ€” they are for making friends and talking about the work.
  164. ## ๐Ÿ“ฆ What it can fetch
  165. | Capability | Douyin | TikTok | Bilibili |
  166. |---|:---:|:---:|:---:|
  167. | One post (video or image album) | โœ… | โœ… | โœ… |
  168. | Author profile | โœ… | โœ… | โœ… |
  169. | An author's posts | โœ… | โœ… | โœ… |
  170. | An author's liked posts | โœ… | โœ… | โŒ |
  171. | Mixes / playlists / seasons, and an author's list of them | โœ… | โœ… | โœ… |
  172. | Comments | โœ… | โœ… | โœ… |
  173. | Comment replies | โœ… | โœ… | โœ… |
  174. | Public folders and what is in them | โŒ | โœ… | โœ… |
  175. | A video's parts, for one uploaded in several | โ€” | โ€” | โœ… |
  176. | The site's popular boards: hot, weekly, all-time picks, top 100 | โŒ | โŒ | โœ… |
  177. | Followers | โŒ | โœ… | โŒ |
  178. | Following | โŒ | โœ… | โŒ |
  179. | Posts recommended beside a post | โœ… | โœ… | โœ… |
  180. | A sound, and the posts that use it | โœ… | โœ… | โ€” |
  181. | A hashtag | โœ… | โœ… | โ€” |
  182. | The posts under a hashtag | โŒ | โœ… | โ€” |
  183. | Keyword search: posts and accounts | โŒ | โœ… | โœ… |
  184. | A live room: whether it is on, and its pull URLs | โœ… | โœ… | โœ… |
  185. | A live room by its broadcast's own id, and Douyin app share links | โœ… | โœ… | โ€” |
  186. | Whether many live rooms are on air, in one call | โœ… | โœ… | โŒ |
  187. | A live room's audience ranking | โœ… | โŒ | โŒ |
  188. | Trending boards | โœ… | โŒ | โœ… |
  189. Douyin serves its follower and following lists only to a signed-in session, so those
  190. two endpoints are not registered at all: an endpoint that always returns an empty page
  191. is worth nothing. Search and the posts under a hashtag are the same story: Douyin refuses
  192. both to a guest, and no signed-in answer has been measured yet, so neither is offered there.
  193. On TikTok the account search answers a guest, while the post search refuses one outright
  194. (measured 2026-11-02), so an imported login is what it takes.
  195. Importing your own logged-in cookies widens what the rest can see, too.
  196. On Bilibili that matters most for comments: a guest is shown the three hottest and no
  197. more, so an imported login is what turns that into the full thread. On Douyin it decides
  198. an author's liked posts outright: a guest is shown none, public or not, so that list
  199. needs a logged-in identity in the pool. An imported login is used at your own risk:
  200. platforms rarely ban an account for reading data with it, but a ban cannot be ruled out
  201. ([what to know before importing one](documents/en/06-identities-and-proxies.md#a-logged-in-jar-is-not-a-guest-identity)).
  202. The dashes are not gaps: a Douyin or TikTok post is never more than one video, so it has no
  203. parts to list, and a Bilibili live room has one number for good rather than an id per
  204. broadcast.
  205. Media downloads, the content archive, counter snapshots, collections and a watchlist
  206. are built in; none of them needs another service.
  207. ## ๐Ÿค– Let an AI agent use it: MCP
  208. Point Claude Code, Claude Desktop, Codex CLI, Cherry Studio or any other MCP client at `/mcp` on
  209. your own instance, and the agent can read posts, authors and comments, store a post's media and
  210. transcribe it. It goes through the same service layer, identity pool and scheduler as the REST API,
  211. and an API key's scopes bound what it may do.
  212. ```bash
  213. claude mcp add --transport http dtk http://127.0.0.1:8000/mcp/ \
  214. --header "Authorization: Bearer dtk_YOUR_API_KEY"
  215. ```
  216. | Tool | What it does |
  217. |---|---|
  218. | `parse_url` | Fetch whatever a link points at โ€” a post, an author, a short link, pasted share text |
  219. | `get_video` ยท `get_user` | One post, or one author profile, by id |
  220. | `list_user_posts` ยท `list_comments` | An author's posts or a post's comments, a page at a time |
  221. | `get_content_history` | The recorded counter history of a post or an author, from the local database |
  222. | `pool_status` | Identity-pool and endpoint health, so an agent can tell "try later" from "broken" |
  223. | `download_media` | Store a post's media on this instance |
  224. | `transcribe_video` | Turn a stored video into text |
  225. | `get_task_result` | Collect a result that did not finish within the call |
  226. Ten tools, and few on purpose: every extra tool makes an agent worse at picking the right one, so a
  227. new capability arrives as an argument to an existing tool. Setup for each client, and what every
  228. tool returns: [MCP and AI agents](./documents/en/12-mcp.md). The console shows the same guide at
  229. `/mcp-guide`.
  230. ## ๐ŸŽ™ Speech to text, on your own machine
  231. A downloaded video can be transcribed where it is stored. FunASR models โ€” Paraformer for the
  232. speech, FSMN-VAD to find where someone is talking, CT-Transformer for punctuation โ€” run in a sidecar
  233. on a network with no route out, so the audio never leaves the host and no API is called.
  234. - **Where:** the **Transcriptions** page in the console, a **Transcribe video** button on every
  235. finished download, the **Library** (one stored post, or a whole selection at once),
  236. `POST /api/v1/transcriptions`, or the `transcribe_video` MCP tool
  237. - **What you get:** one whole text per video, with numbers written as digits, exportable as `.txt`
  238. - **How fast:** a 3 min 13 s clip took 3.7 seconds on two CPU cores; no GPU needed
  239. - **What it is good at:** Mandarin. The models are the general Chinese ones, so other languages
  240. come out poorly
  241. It is off by default. The guided installer asks, then downloads the ~500 MB of models and checks
  242. each file against its SHA-256; by hand, see [Preparing the FunASR ONNX models](./documents/en/18-funasr-models.md)
  243. and [Turning a stored video into text](./documents/en/08-downloads-and-library.md#turning-a-stored-video-into-text).
  244. ## ๐Ÿ”— Which links it accepts
  245. Paste whatever you have โ€” a short link, a post URL, or the whole caption a platform app
  246. puts on your clipboard:
  247. ```
  248. https://v.douyin.com/L4NpDJ6/
  249. https://www.douyin.com/video/7126745726494821640
  250. https://www.douyin.com/jingxuan?modal_id=7660875690212492466
  251. https://www.tiktok.com/@evil0ctal/video/7156033831819037994
  252. https://www.tiktok.com/t/ZTR9nkkmL/
  253. 2.84 nqe:/ <caption> https://v.douyin.com/L4FJNR3/ <sentence telling you to open the app>
  254. https://www.bilibili.com/video/BV1xx411c7mD
  255. https://www.bilibili.com/video/av170001
  256. https://b23.tv/<code>
  257. https://space.bilibili.com/2
  258. ```
  259. Short links are followed and a link buried in a caption is extracted. A post id is also
  260. checked against the platform's own encoding first, so an id that cannot exist is refused
  261. here rather than costing an upstream request. A Bilibili av number is turned into the
  262. bvid it stands for, so either spelling reaches the same post.
  263. ## โš—๏ธ Built with
  264. | | |
  265. |---|---|
  266. | Service | Python 3.12 ยท FastAPI ยท SQLAlchemy 2.0 (async) ยท Alembic ยท Typer ยท structlog |
  267. | Transport | wreq (browser TLS fingerprint emulation) ยท httpx |
  268. | Data | PostgreSQL + TimescaleDB ยท Redis |
  269. | Console | React 19 ยท TypeScript ยท Vite ยท TanStack Query ยท wouter ยท i18next |
  270. | Signing | a_bogus, X-Bogus, X-Gnarly, X-Dynosaur and Bilibili's WBI in pure Python |
  271. | Identity minting | CloakBrowser, headless, in a container of its own, called over HTTP; Bilibili guests over plain HTTP, no browser |
  272. | Downloader | Go 1.23, standard library only, statically linked into a scratch image |
  273. | Transcription | FunASR ONNX (Paraformer, FSMN-VAD, CT-Transformer), offline, in a container with no network route |
  274. | Auth | argon2id password hashing ยท API keys with scopes |
  275. | Protocols | REST (OpenAPI) ยท MCP (streamable-http) ยท CLI |
  276. | Tooling | uv ยท ruff ยท mypy ยท pytest ยท Docker Compose |
  277. Nothing beyond Postgres and Redis is required. No Kafka, no Elasticsearch, no object
  278. store, no Kubernetes.
  279. CloakBrowser is pinned to a specific commit. That pin is a security control โ€” see
  280. [docker/Dockerfile.browser](./docker/Dockerfile.browser).
  281. ## ๐Ÿ—‚ Project layout
  282. **First, what `dtk` is.** `Douyin_TikTok_Download_API` is a mouthful, so the code
  283. says **DTK** instead: **D**ouyin + **T**i**K**Tok. The two platforms, and not the
  284. download or API halves of the name.
  285. It is the Python package (`src/dtk/`), the command (`dtk --help`), the prefix on
  286. every environment variable (`DTK_SECRET_KEY` and friends), the Compose project
  287. name (`-p dtk`), and the three letters in the console's title bar. Where you see
  288. `dtk`, it means `Douyin_TikTok_Download_API`.
  289. ```
  290. Douyin_TikTok_Download_API/
  291. โ”œโ”€โ”€ src/dtk/ the service; all of it lives here
  292. โ”‚ โ”œโ”€โ”€ api/ FastAPI routes, auth, OpenAPI localisation
  293. โ”‚ โ”œโ”€โ”€ platforms/ Douyin, TikTok and Bilibili adapters: endpoints, params, parsers
  294. โ”‚ โ”œโ”€โ”€ signing/ a_bogus / X-Bogus / X-Gnarly / X-Dynosaur / WBI
  295. โ”‚ โ”œโ”€โ”€ transport/ outbound requests, response classification
  296. โ”‚ โ”œโ”€โ”€ identity/ identity minting and health
  297. โ”‚ โ”œโ”€โ”€ scheduler/ identity selection, token buckets, circuit breakers
  298. โ”‚ โ”œโ”€โ”€ services/ the business layer, shared by REST, MCP and the CLI
  299. โ”‚ โ”œโ”€โ”€ worker/ async tasks, callbacks, scheduled collection
  300. โ”‚ โ”œโ”€โ”€ db/ SQLAlchemy models and Alembic migrations
  301. โ”‚ โ”œโ”€โ”€ ops/ diagnostics, backups, health checks, alerting
  302. โ”‚ โ”œโ”€โ”€ media/ downloader client
  303. โ”‚ โ”œโ”€โ”€ models/ one content model across every platform
  304. โ”‚ โ”œโ”€โ”€ urls/ link recognition, short-link expansion, id validation
  305. โ”‚ โ”œโ”€โ”€ mcp/ MCP server
  306. โ”‚ โ”œโ”€โ”€ cli/ the dtk command line
  307. โ”‚ โ”œโ”€โ”€ i18n/ server-side English and Chinese strings
  308. โ”‚ โ””โ”€โ”€ core/ settings, logging, error types
  309. โ”œโ”€โ”€ web/ the React console, built into the app image
  310. โ”‚ โ””โ”€โ”€ src/
  311. โ”‚ โ”œโ”€โ”€ pages/ one file per console page
  312. โ”‚ โ”œโ”€โ”€ components/ design system and shared components
  313. โ”‚ โ””โ”€โ”€ locales/ console English and Chinese strings
  314. โ”œโ”€โ”€ docker/ four Dockerfiles, compose, and three sidecars
  315. โ”‚ โ”œโ”€โ”€ browser_rpc/ Python, wrapping CloakBrowser
  316. โ”‚ โ”œโ”€โ”€ downloader/ Go, the media download sidecar
  317. โ”‚ โ”œโ”€โ”€ transcriber/ Python, offline FunASR transcription
  318. โ”‚ โ””โ”€โ”€ compose.yml
  319. โ”œโ”€โ”€ documents/ user documentation, 18 pages in each language
  320. โ”œโ”€โ”€ tests/ unit / integration / contract / replay
  321. โ”œโ”€โ”€ scripts/ smoke.sh
  322. โ”œโ”€โ”€ .github/workflows/ CI and Docker image publishing
  323. โ”œโ”€โ”€ alembic.ini
  324. โ”œโ”€โ”€ pyproject.toml
  325. โ””โ”€โ”€ Makefile
  326. ```
  327. ## โšก๏ธ Quick start: self-host it with Docker
  328. If you would rather not think about it, the guided script asks a few questions and
  329. brings the stack up โ€” it works out your distribution, checks for Docker, and
  330. scales the resource limits to the machine:
  331. ```bash
  332. curl -fsSL https://raw.githubusercontent.com/Evil0ctal/Douyin_TikTok_Download_API/main/install/install.sh -o install.sh
  333. less install.sh # reading it first is a good habit
  334. bash install.sh
  335. ```
  336. **Afterwards the same script is the operations tool.** Run it again and it finds the install and opens a menu: status, upgrade (compared against the latest GitHub release), passwords, an extra administrator, backup and restore, runtime settings, disk cleanup, stop or uninstall. `--manage` goes straight there.
  337. Details in [install/README.md](./install/README.md). The manual route follows.
  338. There are two ways to install this; below is the recommended one. For the by-hand route, see
  339. [Without Docker](#without-docker).
  340. | How | Who for | Full steps |
  341. |---|---|---|
  342. | **Docker Compose** (recommended) | Almost everyone, production included | [Installation ยท First install](./documents/en/02-installation.md#first-install) |
  343. | By hand | Docker is not an option, or you are changing the code | [For development](./documents/en/02-installation.md#running-without-docker) ยท [On bare metal](./documents/en/02-installation.md#a-production-install-without-docker) |
  344. > **Installing from mainland China?** Switch your mirrors before you start, or the pull will
  345. > most likely time out:
  346. > [Network preparation in mainland China](./documents/en/02-installation.md#network-preparation-in-mainland-china).
  347. You need Docker and Docker Compose. Start by cloning the repository โ€” the compose file,
  348. the Dockerfiles and the migrations all live in it, and the default branch is v5:
  349. ```bash
  350. git clone https://github.com/Evil0ctal/Douyin_TikTok_Download_API.git
  351. cd Douyin_TikTok_Download_API
  352. ```
  353. Nothing in the repository ships a default password or key, so write `.env` next:
  354. ```bash
  355. POSTGRES_PASSWORD=$(openssl rand -hex 24)
  356. REDIS_PASSWORD=$(openssl rand -hex 24)
  357. cat > .env <<EOF
  358. DTK_SECRET_KEY=$(openssl rand -base64 48)
  359. POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
  360. REDIS_PASSWORD=${REDIS_PASSWORD}
  361. DTK_DATABASE_URL=postgresql+asyncpg://dtk:${POSTGRES_PASSWORD}@postgres:5432/dtk
  362. DTK_REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0
  363. EOF
  364. ```
  365. ```bash
  366. docker compose -p dtk -f docker/compose.yml up -d
  367. docker compose -p dtk -f docker/compose.yml logs api # prints the setup token
  368. ```
  369. Open <http://127.0.0.1:8000> and use the token from the log to create the first
  370. administrator.
  371. That starts no browser container, and without it (`--profile browser`, see
  372. [the optional profiles](./documents/en/02-installation.md#the-optional-profiles)) Douyin and
  373. TikTok identities can only be imported, not minted: both hand a visitor its cookies from inside
  374. their page scripts. Bilibili guests are minted over plain HTTP either way.
  375. ### Where the image comes from
  376. By default it is built locally: the first `up` compiles the application image from the
  377. Dockerfile in this repository, which takes a few minutes. To skip that, point compose at
  378. the published image instead, in the same `.env`:
  379. ```bash
  380. cat >> .env <<'EOF'
  381. DTK_IMAGE=evil0ctal/douyin_tiktok_download_api
  382. DTK_IMAGE_TAG=latest
  383. EOF
  384. export COMPOSE_ENV_FILES=.env
  385. docker compose -p dtk -f docker/compose.yml pull
  386. docker compose -p dtk -f docker/compose.yml up -d
  387. ```
  388. These two are read by compose itself rather than by the containers, and compose looks for
  389. them in `docker/.env` unless `COMPOSE_ENV_FILES` says otherwise. Without the export it
  390. finds nothing, falls back to the local names and quietly builds from source again, so it
  391. belongs in every shell you run compose from. The script's `dtkctl` carries it for you.
  392. `latest` is the newest release and moves only when one is cut, so updating later needs
  393. nothing edited here. The `pull` is not optional: these services declare both `image` and
  394. `build`, so compose builds from the local Dockerfile whenever the image is not already on
  395. the machine rather than reaching for a registry.
  396. Images are published for `linux/amd64` and `linux/arm64`, so Apple Silicon and a
  397. Raspberry Pi both run natively. The browser container is not published: it installs
  398. CloakBrowser from a pinned commit, and that pin is a security control that should be
  399. yours to choose, so it stays a local build.
  400. ### Without Docker
  401. Supported, and it is how the project itself is developed. You provide PostgreSQL 17 (**with the
  402. TimescaleDB extension** โ€” a plain `postgres:17` will not do), Redis 8, Python 3.12 and uv, plus
  403. Node 22 if you build the console. Two sets of steps:
  404. - [Running without Docker](./documents/en/02-installation.md#running-without-docker) โ€” for
  405. development; Postgres and Redis still come from containers
  406. - [A production install without Docker](./documents/en/02-installation.md#a-production-install-without-docker)
  407. โ€” all of it by hand, systemd units included, verified on a clean Ubuntu 24.04
  408. What the containers were doing for you โ€” a non-root user, memory and CPU ceilings, a read-only root
  409. filesystem, process supervision โ€” you put back yourself. That section lists them one by one.
  410. ### Where to look next
  411. | What you want to do | Where |
  412. |---|---|
  413. | Size a machine, change the container limits | [Three sizes](./documents/en/02-installation.md#three-sizes) ยท [Changing the limits](./documents/en/02-installation.md#changing-the-limits) |
  414. | Turn on the browser container, the downloader or the transcriber sidecar | [The optional profiles](./documents/en/02-installation.md#the-optional-profiles) |
  415. | Put TLS and a reverse proxy in front | [Behind a reverse proxy](./documents/en/02-installation.md#behind-a-reverse-proxy) |
  416. | Understand how the environment is actually read | [Environment variables](./documents/en/02-installation.md#environment-variables) |
  417. | Confirm an install is genuinely healthy | [Verifying an install](./documents/en/02-installation.md#verifying-an-install) |
  418. | Read the compose file line by line | [docker/README.md](./docker/README.md) |
  419. ## ๐Ÿ–ฅ What you get: console, REST API, MCP and CLI
  420. | Entry point | Where | What it is |
  421. |---|---|---|
  422. | Web console | `/` | Identity pool, scheduler, library, downloads, transcriptions, logs, diagnostics |
  423. | API reference | `/docs` | Swagger UI inside the console, English and Chinese |
  424. | Bare reference | `/swagger`, `/redoc` | No login required |
  425. | REST API | `/api/v1/...` | 128 operations |
  426. | MCP | `/mcp` | Shares the service layer with REST; client setup at `/mcp-guide` in the console |
  427. | CLI | `dtk --help` | Same |
  428. The main capabilities:
  429. - **Parse** a link, share text, short link, or a bare post id
  430. - **Archive** everything parsed, so a post deleted upstream is still here
  431. - **Download** media to your own disk, in bulk by author, skipping what you have,
  432. with duplicate cleanup
  433. - **Transcribe** a stored video to text, offline
  434. - **Watch** an author or a post and re-collect it on a timer
  435. - **iOS Shortcut** support at `/api/v1/ios/shortcut`
  436. ## ๐Ÿ”„ Updating to a new release
  437. The console keeps an eye out for you: `system.check_updates` is on by default,
  438. and if a newer release exists you get one notice after signing in, at most once
  439. a day. That request goes from **your browser** to GitHub โ€” the server never
  440. sends anything outward, so it does not tell anyone this instance exists. Turn it
  441. off in Settings if you would rather it did not.
  442. If you installed with the script, it is one command in the install directory:
  443. ```bash
  444. cd /opt/dtk # or ~/dtk - wherever you installed it
  445. ./dtkctl upgrade # the latest release; ./dtkctl upgrade 5.1.6 for a given one
  446. ```
  447. It moves the checkout to the release's tag, pulls the new images (or rebuilds them, on an
  448. install built from source), rebuilds the browser image, takes a backup, migrates, and only
  449. then writes the version it moved to into `.env` and restarts. Anything that fails before the
  450. restart puts the checkout and `.env` back, and the old version keeps running. There is
  451. nothing to edit by hand. An install from before
  452. 5.1.6 does not have `upgrade` yet; there, once, run `git pull && bash install/install.sh
  453. --upgrade` in the same directory, and from then on it is `./dtkctl upgrade`. Running
  454. `bash install.sh --manage` and picking 2 does the same from the menu.
  455. By hand it is:
  456. ```bash
  457. cd /opt/dtk && git pull
  458. export COMPOSE_ENV_FILES=.env
  459. # Running the published images (recommended). Name the services you run:
  460. # add downloader and transcriber if you enabled them, with the same --profile flags.
  461. docker compose -p dtk -f docker/compose.yml pull api worker
  462. docker compose -p dtk -f docker/compose.yml build browser-rpc # only with --profile browser
  463. docker compose -p dtk -f docker/compose.yml run --rm migrate
  464. docker compose -p dtk -f docker/compose.yml up -d
  465. ```
  466. With `DTK_IMAGE_TAG=latest` there is nothing to change first. A pinned version or
  467. `sha-` build is the one thing a pin costs: move it in `.env` before you pull, which is
  468. the step the script does for you. A checkout the script made sits on a release tag, where
  469. `git pull` has no branch to pull: there, use
  470. `git fetch origin tag v5.1.7 && git checkout --detach v5.1.7`.
  471. Building locally instead? Swap `pull` for `build`.
  472. `migrate` runs on every start and Alembic is idempotent, so running it separately is
  473. only about getting the schema up before the containers switch over.
  474. **Your data stays put.** The named volumes (`postgres-data`, `redis-data`,
  475. `media-data`) survive a rebuild, so the identity pool, the archive, the settings
  476. and the API keys are all where you left them.
  477. The browser image is built from this checkout, never pulled, so rebuild it on every
  478. update: under a tag that stays the same - `latest`, or a local build's `dev` - the old
  479. one keeps running the old code. Cached layers keep it short.
  480. To go back, `./dtkctl upgrade 5.1.5` with the script, or set `DTK_IMAGE_TAG` to the
  481. previous version or `sha-` by hand and `up -d` again. Migrations have no automatic
  482. downgrade, so the script refuses, before pulling anything, a release that lacks the
  483. database's latest migration; past one, the way back is a new install of the old version
  484. with a backup taken on it restored. Back the database up before upgrading โ€” the script
  485. does โ€” which is the only rollback that always works.
  486. ## ๐Ÿ“– Documentation
  487. **Read it online at [douyin.wtf](https://douyin.wtf)** โ€” the same 18 pages, rendered,
  488. searchable and in both languages. The markdown source is in
  489. [`documents/`](./documents/README.md) and is what the site is built from, so the two
  490. never disagree.
  491. **New here:**
  492. [Quick start](./documents/en/01-quickstart.md) ยท
  493. [Concepts](./documents/en/04-concepts.md) ยท
  494. [Console overview](./documents/en/05-console-overview.md)
  495. **Running it:**
  496. [Installation and deployment](./documents/en/02-installation.md) ยท
  497. [Configuration reference](./documents/en/03-configuration.md) ยท
  498. [Operations](./documents/en/10-operations.md) ยท
  499. [Troubleshooting](./documents/en/14-troubleshooting.md) ยท
  500. [Security](./documents/en/15-security.md)
  501. **Building against it:**
  502. [REST API guide](./documents/en/11-api.md) ยท
  503. [MCP and AI agents](./documents/en/12-mcp.md) ยท
  504. [CLI reference](./documents/en/13-cli.md) ยท
  505. [Contributing](./documents/en/16-contributing.md)
  506. The endpoint reference is not in there: it is generated from the code that serves the
  507. requests, so your own instance is the copy that is never out of date. Find it at `/docs`
  508. inside the console, or at `/swagger`, `/redoc` and `/openapi.json` without a login. Both
  509. languages.
  510. ไธญๆ–‡ๆ–‡ๆกฃ๏ผš[`documents/README.zh-CN.md`](./documents/README.zh-CN.md)
  511. **Reading this with an LLM?** [`llms.txt`](./llms.txt) is the whole documentation set
  512. as one annotated index, in the [llmstxt.org](https://llmstxt.org) format.
  513. ## ๐Ÿ“ฎ Contact
  514. | | |
  515. |---|---|
  516. | Issues | [GitHub Issues](https://github.com/Evil0ctal/Douyin_TikTok_Download_API/issues) โ€” public, keeps its history, and anyone who has hit the same thing can answer |
  517. | Email | `Evil0ctal1985@gmail.com` โ€” reaches one person; best for anything that does not belong in public |
  518. | Author | [@Evil0ctal](https://github.com/Evil0ctal) |
  519. Before asking, read [Troubleshooting](./documents/en/14-troubleshooting.md) and include
  520. the output of the Diagnose page or `dtk diagnose`. It answers most of what a maintainer
  521. would otherwise have to ask you.
  522. ## โญ๏ธ Star history
  523. [![Star History Chart](https://api.star-history.com/svg?repos=Evil0ctal/Douyin_TikTok_Download_API&type=Timeline)](https://star-history.com/#Evil0ctal/Douyin_TikTok_Download_API&Timeline)
  524. > Started 2021/11/06 ยท GitHub [@Evil0ctal](https://github.com/Evil0ctal)
  525. ## ๐Ÿ“„ Licence
  526. [Apache License 2.0](./LICENSE).
  527. You may use, modify and distribute this project, **including commercially and inside
  528. closed-source products**. The grant is irrevocable. In return the licence asks you to:
  529. - Keep the licence text and the [NOTICE](./NOTICE) file, which carries the copyright
  530. notice, with any copy you distribute
  531. - State what you changed, in files you modified
  532. - Accept that it comes with no warranty
  533. ### A request from the author
  534. This project is given away, and it stays free because sponsors pay for it rather than
  535. users. **If you are making money from it, please consider sponsoring instead of only
  536. taking.**
  537. This is a request, not a licence condition โ€” Apache 2.0 permits commercial use, and
  538. nothing above takes that back.
  539. ## โ˜•๏ธ Support the author
  540. The sponsors above pay for the **project**. This section is for the **person who
  541. maintains it**, and is entirely optional.
  542. | Network | Address |
  543. |---|---|
  544. | Solana | `HvtkxmDERbNXfCoojpdFAYN5mSWowjpXgedsG9eF7y9z` |
  545. | Tron (TRC20) | `TQwSM2vjcnrdRU7gY7KNp2tCgMnK33azkT` |
  546. | Ethereum (ERC20) | `0x2f210FdfD981B59eC130370E5b1Aa8A6a06fb5Ad` |
  547. | BNB Smart Chain (BEP20) | `0x2f210FdfD981B59eC130370E5b1Aa8A6a06fb5Ad` |
  548. | Bitcoin | `bc1q785j55cxlnjqe8lkwy8cq57t8t9vn3ak9tlsfy` |
  549. These networks carry the usual major tokens. **USDT on Tron (TRC20) or Solana** is the
  550. easiest to receive, and the cheapest to send.
  551. > **Send only on the network an address is listed under.** A transfer on the wrong chain
  552. > cannot be recovered by anybody.
  553. > Ethereum and BNB Smart Chain share one address on purpose: both are EVM chains, and
  554. > the same key controls it.
  555. [GitHub Sponsors](https://github.com/sponsors/evil0ctal) works too.
  556. ### What you are responsible for
  557. This fetches data from platforms that have their own terms, and it runs on your machine
  558. under your control. Respect those terms and applicable law, respect the people whose
  559. content you collect, do not use it to harass anyone, and do not redistribute work that
  560. is not yours. Nobody else can enforce any of that for you.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.