Overview
Short Drama - Douyin Information Source is a Douyin viral content tracking tool designed specifically for short drama creators and MCN operations staff. It automatically scans Douyin short drama creative content daily, filters viral works by like count, intelligently clusters themes, and then generates an HTML visual daily report.
Through simple natural language instructions, you can:
- 📊 Get the daily Douyin short drama viral rankings and theme distribution
- 🏷️ Automatically cluster theme directions such as time travel/domineering CEO/rebirth/suspense
- 📈 Generate creative trend analysis reports (viral title characteristics, core creator rankings, emerging growth signals)
- 🔔 Enable daily subscription, and the daily report is automatically produced
Applicable toshort drama creator topic selection, MCN agency operations, theme trend researchand other scenarios that require daily tracking of Douyin short drama hotspots.
Important: Data is updated daily at 15:00 with the previous day's data (actual updates may be delayed; refer to the script's real liveness check). Before querying, the script first performs input validation: keywords must match the short drama theme lexicon (
topic_keywordsas specified intheme names + all related words, e.g. "face-slapping" matches related words for the counterattack theme),if matched, use that keyword directly to query data; if not satisfied, remind "keyword does not meet query conditions" and recommend related words,do not initiate an API request。No-data confirmation rule: When a query has no matching data or the full dataset is insufficient, it is prohibited to automatically initiate any additional queries (automatic fallback to the full dataset is prohibited, and automatic theme expansion is prohibited). First display recommended theme keywords and ask the user; only after user confirmation may a query be initiated; when the date exceeds the valid query range, remind and automatically fall back to the most recent date with data, without requiring user confirmation.
Features
🎯 Core Features
| Feature Module | Capability Description | Core Value |
|---|---|---|
| Viral Discovery | Filter popular content from Douyin short dramas by like count | Precisely locate high-heat short drama works |
| Theme Clustering | Automatically identify theme directions (time travel/domineering CEO/rebirth/suspense, etc.) | Daily theme classification is dynamically determined by content |
| Smart Query | By default, query all short dramas; if keywords match the lexicon (theme names + related words), query directly; when data is insufficient, prompt recommended themes and wait for confirmation | Save API quota and obtain data efficiently |
| Custom Query | Users can specify any theme/creator/keyword for targeted queries | Flexibly cover any short drama niche direction |
| Creative Insights | Analyze viral title characteristics, theme trends, and creator performance | Deeply uncover creative patterns |
| Visual Daily Report | Dark-themed HTML, cover image + engagement data + direct work links | Intuitively display daily short drama hotspots |
| One-click Subscription | --subscribe Enable daily automatic generation |
Daily reports are automatically saved in a local folder |
✨ Key Features
- ⚡ Liveness-based date pre-check: Before calling, use a lightweight request (no keyword, pageSize=1) to actually probe whether the target date has data, replacing pure local clock inference, automatically intercepting invalid queries and avoiding wasted API quota
- 🧭 Pre-input validation: Before querying, first determine whether the user's category/keyword matches the short drama genre lexicon (genre name + all related words; on a match,directly use that keyword to query data), and whether the date is within the valid query range;if not satisfied, remind "keyword does not meet query conditions" and recommend related categories and keywords, without initiating an API request
- 🔄 Automatic fallback：
--latestAutomatically fall back up to 7 days forward to find the most recent date with data before generating the daily report, completely saying goodbye to "error when query returns empty" - ⏸️ No-data confirmation mechanism: When the query has no matching data or the full dataset is insufficient,do not automatically expand genres, do not automatically downgrade to the full dataset, prompt recommended genre keywords and wait for user confirmation before querying
- 🧠 Structured empty reason: On empty results, clearly output the reason (no data in data source/no keyword match/API exception) and give next-step suggestions
- 🏷️ Intelligent genre clustering: Built-in keyword library for 9 major genres (time travel/domineering CEO/rebirth/suspense/sweet romance/counterattack/period drama/war god/costume drama), with automatic identification and classification
- 📊 Creative trend report: Automatically analyzes emerging growth signals, hit title characteristics, and core creator rankings
- 🎨 HTML dark-theme daily report: Cover image + engagement data + direct work links, beautiful and intuitive, automatically opened in browser
- 💰 API credit optimization: Batch queries + 1-hour cache + liveness interception, saving API call quota
One-click installation
Prerequisites
- Python 3 runtime environment installed
- Obtain a Red Fox Hub API Key
API Key acquisition
The data query API authenticates via the request header X-API-KEY , and the Key is obtained from the environment variable REDFOX_API_KEY .
Go to Red Fox Hub official website to register. After logging in, obtain it in the personal center. The format is ak_xxxxxxxx. Newly registered users receive free credits.
Environment variable configuration
| Variable name | Required | Description |
|---|---|---|
REDFOX_API_KEY |
Yes | Red Fox Hub API access key, format ak_xxxxxxxx |
Configuration method:
- macOS/Linux: Append
export REDFOX_API_KEY=<值>to~/.zshrcor~/.bashrc, thensourceto make it take effect - Windows:
[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<值>", "User")(terminal restart required) - Verify after configuration:
echo $REDFOX_API_KEY(macOS/Linux) orecho %REDFOX_API_KEY%(Windows)
Usage Guide
Basic usage
1. Query the daily short drama hit report
Directly tell the assistant which daily report you want to view:
User: Query today's short drama Douyin daily report
Assistant: (executes
--latest, the script automatically falls back to locate the most recent date with data, and outputs the daily report + genre overview + creative trend analysis)
Date pre-check rules: Perform preliminary validation before querying—when the category/keywords do not match the short-drama genre lexicon, remind the user that "the keywords do not meet the query conditions" and recommend related terms,do not initiate an API request; when the date exceeds the valid query range or has not been updated, the script automatically falls back to obtain the most recent time-range data, and clearly informs the user that "the current query time has not been updated or exceeds the query time range, and the most recent time-range data has been automatically obtained for you."
2. Targeted query by genre
Specify the genre direction you care about:
User: Query short dramas in the time-travel genre
Assistant: (Generate a targeted daily report for the time-travel genre + trend analysis)
3. Query a historical date
User: Query the short-drama daily report for June 10
Assistant: (Data already exists for the historical date; generate the daily report directly)
Advanced Usage
4. Multi-genre combined query
python3 scripts/playlet_douyin_daily.py --topics "穿越,霸总,重生" --latest
5. Query by time range
python3 scripts/playlet_douyin_daily.py \
--start-time "2026-06-01 00:00:00" \
--end-time "2026-06-30 23:59:59"
6. Enable daily subscription
python3 scripts/playlet_douyin_daily.py --subscribe
7. Use cached data
python3 scripts/playlet_douyin_daily.py --from-cache
Common Commands Quick Reference
| Command | Function |
|---|---|
--latest |
Generate the latest daily report (automatically falls back up to 7 days to locate the most recent date with data) |
--date YYYY-MM-DD |
Generate the daily report for a specified date (automatically falls back to the most recent date with data when not updated) |
--topics "关键词" |
Custom genre query (comma-separated; when short-drama genre terms are not met, remind + recommend, and do not request the API) |
--count N |
Number of works to scan (default 200) |
--subscribe |
Enable daily subscription |
--unsubscribe |
Disable daily subscription |
--from-cache |
Use cached data (valid within 1 hour) |
--output-dir |
Custom output directory |
Complete Parameter Description
| Parameter | Description | Default Value |
|---|---|---|
--topics |
Custom genre keywords, comma-separated. Before querying, first validate whether they match the short-drama genre lexicon (genre name + all related terms; once matched, directly use that keyword for the query); when not satisfied, remind + recommend related terms anddo not request the API. By default, query all short dramas; when data is insufficient, prompt recommended genres and wait for confirmation (no automatic expansion); all genres are queried through the batch API | 短剧 |
--count |
Number of works to scan; stop once satisfied | 200 |
--date |
Specify date YYYY-MM-DD (automatically falls back to the most recent date with data when not updated or out of range) | Today |
--start-time |
Custom start time YYYY-MM-DD HH:MM:SS (overrides --date inference) | — |
--end-time |
Custom end time YYYY-MM-DD HH:MM:SS (overrides --date inference) | — |
--latest |
Automatically falls back up to 7 days to locate the most recent date with data, skipping intervals without data, without deducting credits | — |
--output-dir |
Output directory | ~/Downloads/QoderReports |
--api-key |
Specify API Key | — |
--subscribe |
Enable daily subscription | — |
--unsubscribe |
Disable daily subscription | — |
Workflow
For the detailed execution process (date pre-check rules, script invocation, mandatory output format template, genre clustering rules, and creative trend analysis logic), please refer to core_workflow.md
The workflow is divided into three steps:
- Step Zero — Input and Date Pre-check: Preliminary validation of whether the keywords match the short-drama genre lexicon (genre name + all related terms; once matched, query directly; when not satisfied, remind + recommend,do not request the API); after estimating the starting point for the date according to the 15:00 rule, use a lightweight requestfor real liveness probingWhether the target date has data; when there is no data, automatically fall back to the most recent date that has data.When the query has no matching data or insufficient data, first display recommended genre keywords and ask the user; only after the user confirms may the query be initiated (no-data confirmation rule)
- Step 1 — Generate the hit daily report: Execute the
playlet_douyin_daily.pyscript, supporting parameters such as--latest、--date、--topicsand other parameters - Step 2 — Run creative trend analysis: Based on the clustering results, automatically analyze the TOP 5 genres, hit title characteristics, and core creator rankings, and output a structured trend report
Custom genre query
In addition to the default short drama daily report, users can specify any combination of genres for targeted queries:
# 查询穿越题材热门短剧
python3 scripts/playlet_douyin_daily.py --topics "穿越,时空,重生"
# 查询霸总/甜宠题材
python3 scripts/playlet_douyin_daily.py --topics "霸总,甜宠,总裁,虐恋"
# 查询悬疑/反转题材
python3 scripts/playlet_douyin_daily.py --topics "悬疑,推理,反转,惊悚"
Custom query logic:
- Pre-validation (v2.3): Before querying, first determine whether the keyword hits the short drama genre lexicon (
topic_keywordsthegenre names + all related wordsspecified in , e.g. "face-slapping" hits related words for the counterattack genre, and "CEO" hits related words for the domineering CEO genre).After a hit, directly use that keyword to query data; if not satisfied, clearly remind the user that "the keyword does not meet the short drama query conditions," andrecommend related categories and keywords(prioritize extracting genre words from invalid words, then supplement with popular genres), anddo not initiate API requests, guiding the user to query with the recommended words instead - Invalid words automatically ignored: In mixed-word scenarios, retain valid keywords to continue the query; invalid keywords are automatically ignored and prompted; when all are invalid,do not request the API, stop directly and recommend related words
- No-data confirmation rule (v2.3): When the keyword/genre specified by the user has no matching data,it is prohibited to automatically downgrade to a full query, and it is prohibited to automatically expand genres; first prompt with recommended genre keywords and ask the user; only after the user confirms may the query be initiated
- All genres provided by the user are queried at once via the batch interface, with no need to call them one by one
- Query results are automatically deduplicated; genre clustering and trend analysis are both generated based on the query results, strongly correlated with the user's areas of interest
Genre keyword quick reference:
| Genre type | Typical keywords |
|---|---|
| Time travel | time travel, time and space, ancient, modern, return to |
| Domineering CEO | domineering CEO, CEO, wealthy family, cold and ruthless |
| Rebirth | rebirth, counterattack, return to, turnaround |
| Suspense | suspense,推理, reversal, thriller, mystery case |
| Sweet romance | sweet romance, love, sugar, sweetness, doting |
| Counterattack | counterattack, turn things around, face-slapping, rise |
Use cases
Use case 1: Topic reference for short drama creators
Role: Short drama screenwriter/director
Need: To understand which genres and title patterns are currently most likely to produce hits
How to use:
- Query the short drama hit daily report daily to view the genre overview
- Focus on "emerging volume signals" and "hit title characteristics"
- Choose a genre direction based on your own strengths
Expected benefits:Precisely seize traffic trends and increase the probability of works becoming hits
Scenario 2: MCN agency operations management
Role:MCN Operations Director
Needs:Track the performance of signed creators and competitors in the Douyin short drama track
How to use:
- Check the "Core Creator Ranking" to understand top creator activity
- Query by genre to analyze the competitive landscape of each track
- Enable daily subscription to automatically receive the daily report
Expected benefits:Improve operational decision-making efficiency and capture market changes in a timely manner
Scenario 3: Genre trend research
Role:Content analyst/investment research personnel
Needs:Systematically analyze the genre distribution and trend changes of Douyin short dramas
How to use:
- Query by time range (such as monthly data) to observe changes in genre proportions
- Compare interaction data and growth trends of multiple genres
- Analyze "Cross-genre comparison suggestions" to discover fusion opportunities
Expected benefits:Form data-driven trend judgments to support investment decisions
Scenario 4: Daily content tracking
Role:Short drama enthusiasts/industry followers
Needs:Quickly learn about Douyin short drama hot topics every day without manual analysis
How to use:
- Enable subscription
--subscribe - Automatically generate a daily report every day, saved in
~/Downloads/QoderReports/
Expected benefits:Track industry trends at zero cost, saving time and effort
Project architecture
Directory structure
短剧-抖音信息源/
├── SKILL.md # Skill核心说明文档
├── scripts/
│ └── playlet_douyin_daily.py # 日报生成脚本(含题材聚类+HTML生成)
├── references/
│ ├── core_workflow.md # 核心工作流程+输出格式+聚类规则+趋势分析
│ └── examples.md # 使用示例与常见用法组合
└── assets/
Tech stack
| Component | Technology | Description |
|---|---|---|
| Runtime environment | Python 3 | Script execution environment |
| Data interface | Red Fox Hub API | Douyin short drama creation data, RESTful interface |
| Authentication method | X-API-KEY | Request header authentication, environment variable configuration |
| Output format | HTML (dark theme) | Automatically opens in browser, responsive design |
| Caching strategy | JSON local cache | 1-hour validity period, path ~/.workbuddy/cache/ |
Core modules
- playlet_douyin_daily.py:Main execution script, integrating API calls, genre clustering, HTML daily report generation, and creation trend analysis, supporting intelligent date determination (15:00 rule), batch query deduplication, and automatic browser preview
FAQ
Installation-related
Q: What should I do if it prompts "Missing API Key"?
A: Please confirm that the environment variable has been correctly configured REDFOX_API_KEY:
- Go to Red Fox Hub to register and obtain an API Key (format
ak_xxxxxxxx) - Windows:
[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "ak_xxx", "User") - Restart the terminal and verify:
echo %REDFOX_API_KEY%
Q: API Key invalid or expired?
A: Log in to the Red Fox Hub personal center to check the Key status, and confirm that the Key has not expired and the account has sufficient credits.
Usage-related
Q: When is the data updated?
A: The previous day's data is updated daily at 15:00 (actual delays may occur; refer to the script's actual liveness check). Before 15:00, the latest available data is from the day before yesterday; after 15:00, it is from yesterday.
Q: When querying, it prompts "Data has not been updated yet"?
A: The script will automatically fall back forward to fetch data from the most recent time range, and clearly inform you that "the current query time has not been updated or exceeds the query time range, and the most recent time range data has been automatically fetched for you", so no manual handling is needed.
Q: Which genres are supported for queries?
A: It has 9 built-in genres (time travel/CEO romance/rebirth/suspense/sweet romance/counterattack/period/war god/costume drama), and also supports queries with any custom keyword. However, before querying, it first verifies whether the keyword matches the short drama genre lexicon. If not, it gives a reminder + recommends related words,does not request the API, to avoid wasting API quota.
Q: How can I save API credits?
A: Use --from-cache to reuse the cache within 1 hour; use --latest to automatically fall back to dates with data; proactively pre-check to block dates with no data; when a keyword does not match the genre lexicon, no API request is made.
Troubleshooting
Q: The script reports an error "UnicodeEncodeError: 'gbk' codec"?
A: Windows terminal encoding issue. Set the environment variable before running:$env:PYTHONIOENCODING="utf-8"
Q: The HTML daily report does not open automatically?
A: Confirm that the system default browser is set correctly. The daily report file is always saved in the ~/Downloads/QoderReports/ directory and can be opened manually.
Q: Common API error codes?
| Error Code | Description | Solution |
|---|---|---|
| 1002 | Items per page exceed 200 | The script has automatically limited this; no handling needed |
| 3106 | Missing API Key | Configure the environment variable REDFOX_API_KEY |
| 3107 | Invalid API Key | Check the key format and validity |
| 3108 | Requests are too frequent | Wait and retry |
| 3109 | Daily call limit reached | Try again the next day |
| 3201 | Insufficient credits | Go to Honghu Hub to top up |
Reference Documentation
- core_workflow.md — core execution flow, output format templates, date judgment logic, genre clustering rules, creative trend analysis logic
- examples.md — usage examples and common usage combinations