SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdouyin-video-downloader

douyin-video-downloader

Design & creation

View repository

Updated 10-16 06:51

About this skill

Douyin Account Video Batch Downloader

Enter Douyin ID → Fetch works list → Parse download links → One-click download to local

Introduction

A batch download tool for videos under a Douyin account homepage. Simply provide a Douyin ID, and it automatically fetches the account's recent works list, parses watermark-free video/image-text direct download links one by one, and supports one-click batch download to local.

Features

Feature Description
📋 Work Fetching Get the account's recent works (title, engagement data, work links) via the Douyin ID
🔗 Link Parsing Call the parsing API one by one to obtain watermark-free direct download links for videos/image-text
📥 Batch Download One-click download of all works (videos + image-text) to the local output/ directory
📊 Data Display Markdown table / JSON dual-format output, including complete engagement data
📄 Pagination Supports pagination to view more works
📅 Date Filtering Can filter by work publish time
⚡ Rate Protection Built-in request interval to avoid triggering frequency limits

API Description

This Skill calls two redfox.hk APIs:

Step API Description
1. Fetch works POST /story/api/dy/data/listWorkByAccount Get the works list based on the Douyin ID
2. Parse download POST /story/api/parseWork/videoDownload/douyin Get watermark-free direct download links based on the work link

Authentication

Go to Redfox Hub to get an API Key.

# 环境变量配置（推荐）
export REDFOX_API_KEY=ak_你的密钥

# Windows PowerShell
$env:REDFOX_API_KEY="ak_你的密钥"

Usage

CLI Command Line

# 基础用法：拉取作品并解析下载链接（不下载文件）
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688"

# 下载视频到本地
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --download

# 指定下载目录
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --download --output-dir ./my_videos

# JSON 格式输出
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --json

# 多账号（逗号分隔）
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --accounts "Fish688688,YuZhouXiaoLi1220" --download

# 指定作品数量（默认10，最多50）
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --count 20 --download

# 翻页查看更多作品
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --page 2

# 按日期范围筛选作品
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --date-start 2026-07-01 --date-end 2026-07-31

# 组合使用：第2页 + 日期过滤 + 下载
python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "Fish688688" --page 2 --count 20 --date-start 2026-06-01 --download

Parameter Description

Parameter Description
--account Single Douyin ID
--accounts Multiple Douyin IDs, comma-separated
--count Number of works to fetch (default 10, max 50)
--page Page number (default 1)
--date-start Start date YYYY-MM-DD
--date-end End date YYYY-MM-DD
--download Download video files to local
--output-dir Download directory (default output/）
--json JSON format output
--rate-limit Request interval in seconds (default 1.0)
--api-key Specify API Key

Dependencies

Dependency Installation Command
requests pip3 install requests

Douyin ID Requirements

The API queries via uniqueName(Douyin display ID), and the script passes the user-provided Douyin ID uniformly as uniqueName , withuserId and shortId fixed as empty strings.A Douyin ID must be provided。

Important: If the user only enters an account name (such as "Li Jiaqi" or "Lao Gao and Xiao Mo") without providing a Douyin ID, you must prompt:

"There are multiple Douyin accounts with the same name. Please provide the exactDouyin IDfor accurate lookup."

And attach an example image showing how to obtain the Douyin ID for the user's reference:

Example of obtaining the Douyin ID

Douyin IDis the unique ID displayed below the nickname on the target account's homepage in the Douyin APP (such as Fish688688、YuZhouXiaoLi1220), not the Chinese nickname.

Data Rules

Failure Threshold Protection

  • After the same Douyin ID accumulates 5 API call failures within 6 hours, subsequent requests will be rejected

  • When rejected, prompt: "The current account download has exceeded the failure threshold. Please contact customer service email redfoxdata@proton.me for handling"

  • If more than 6 hours have passed since the last failure, the count automatically resets to zero, and normal calls resume

  • If the same account is queried successfully(the API returns normal data), the count resets to zero, and normal calls resume

  • Failure counts are persisted to ~/.qoder/douyin_video_downloader_failures.json

Note: Only call failures caused by network timeouts or API error codes (3108/3106/3107/400, etc.) are recorded; accounts with no work data yet (empty data) are not counted as failures.

Agent Integration Guide

Trigger Words

  • Douyin download / Douyin video download

  • Douyin batch download / Douyin watermark-free download

  • Download Douyin works / Douyin account video extraction

  • Help me download xxx's Douyin videos

Agent Execution Flow

Step 1: 确认用户意图与抖音号
  - 若用户提供了抖音号（如 Fish688688），直接执行
  - 若用户只提供了账号名称（中文昵称，如"李佳琦"），必须提示：
    "抖音账号名称存在多个重名情况，请提供准确的抖音号以便精准查询。"
    并展示获取抖音号的示例图：https://lyy.redfox.hk/page/ljq.png

Step 2: 识别用户输入的时间范围（如有）
  - 若用户提到了作品时间范围，自动识别并转换为 --date-start / --date-end：
    - "7.1~7.20" → --date-start 2026-07-01 --date-end 2026-07-20
    - "7月1日到7月20日" → --date-start 2026-07-01 --date-end 2026-07-20
    - "最近一周" → 当前日期往前推 7 天
    - "上个月" → 上个月 1 日到上个月最后一天
    - "7月份的作品" → --date-start 2026-07-01 --date-end 2026-07-31
  - 日期格式固定为 YYYY-MM-DD，年份默认为当前年份
  - 若用户要求"继续"/"下一页"，添加 --page N

Step 3: 调用脚本拉取作品 + 解析下载链接
  python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "抖音号"

Step 4: 展示结果 + 询问翻页
  - 展示 Markdown 表格，含可点击的作品链接和下载链接
  - 若有失败：提示「可能是用户已删除该视频，如需数据核查可联系工作人员邮箱 redfoxdata@proton.me 处理」
  - 若可翻页：告诉用户「还有更多作品，是否需要翻看下一页？」，输入下一页翻页
  - 提示用户支持按时间范围提取作品

Step 5: 询问用户是否需要批量下载
  - 使用 AskUserQuestion：「是否需要将能下载的视频批量下载到本地？」
  - 选项：「下载到本地」/「只看链接即可」

Step 6: 用户确认后执行下载
  python3 "$SKILL_PATH/scripts/douyin_video_downloader.py" --account "抖音号" --download
  - 告知用户文件保存路径

Agent Output Specification

After parsing is complete, output in the following format (natural language style, aimed at ordinary users).

⛔ Mandatory Rule: Simplified Output Is Prohibited

The Agent must display the complete table returned by the script as-is. The following behaviors are prohibited:

  • ❌ Deleting or merging any column is prohibited (Publish Time, Work, Likes, Comments, Favorites, Shares, Resource Download — none may be missing)
  • ❌ Omitting the pagination prompt line is prohibited ("There are more works. Enter --page 2 to view the next page")
  • ❌ Omitting the time range filter prompt is prohibited ("💡 Supports entering the time range of works you want to extract…")
  • ❌ Omitting the download inquiry prompt is prohibited ("💾 Do you need to batch download these X works locally?")
  • ❌ Replacing the complete table content with "..." or a summary is prohibited
  • ✅ All complete information for every work must be displayed row by row (including resource download links)

Output Template

## 📥 抖音视频下载 — @账号名（粉丝: X）

当前是**第 1 页**，共 10 条作品 | 还有更多作品，输入 `--page 2` 翻看下一页

| #   | 发布时间 | 作品                                       | 赞   | 评论 | 收藏 | 分享 | 资源下载                                      |
| --- | -------- | ------------------------------------------ | ---- | ---- | ---- | ---- | --------------------------------------------- |
| 1   | 07-28    | [作品标题](https://www.iesdouyin.com/...)  | 5.2k | 67   | 689  | 5.8k | [🎬视频](...) · [🖼封面](...) · [🎵音频](...) |
| 2   | 07-24    | [作品标题2](https://www.iesdouyin.com/...) | 3.1k | 22   | 136  | 865  | [🖼封面](...)                                 |
| 3   | …        | …                                          | …    | …    | …    | …    | …                                             |

**合计：** 10 条作品，8 条可下载，2 条下载失败

> ⚠️ 下载失败的视频可能是用户已删除该视频，如需数据核查可联系工作人员邮箱 **redfoxdata@proton.me** 处理。

> 💡 需要提取特定时间范围的作品？直接告诉我时间范围即可，如「7.1~7.20」「最近一周」

> 💾 需要将这 X 条作品批量下载到本地吗？直接告诉我即可。

FAQ

Q: How do I get an API Key? A: Go to redfox.hk to register and obtain one.

Q: Do the downloaded videos have watermarks? A: No watermark. The direct video/image links returned by the API have had the Douyin watermark removed.

Q: Can image-text works be downloaded? A: Yes. Image-text works (slideshows, album-type) automatically download the first watermark-free image, in JPG/PNG/WebP format.

Q: Why does it prompt "Call frequency exceeded"? A: When the API returns code=3108, it means requests were too fast and triggered rate limiting. You can increase --rate-limit 2.0 to extend the interval.

Q: Which Douyin ID formats are supported? A: Supports Douyin display ID (uniqueName), such as Fish688688、YuZhouXiaoLi1