Douyin Works Crawler

抖音作品爬取

输入抖音名称或ID，一键获取账号基础信息 + 近期作品内容

简介

抖音作品爬取是一款专为抖音内容分析打造的智能工具，帮助用户快速获取任意抖音账号的基础信息和近期作品数据。

通过简单的账号名称或抖音号输入，你可以：

• 📊 获取账号基础信息（粉丝数、获赞、作品总数、红狐指数等）
• 📋 查看近期作品列表（最多50条，含互动数据和作品链接）
• 🔍 发现互动TOP3作品，获取值得学习的内容分析

适用于品牌方、MCN机构、内容运营、自媒体从业者等需要分析抖音账号表现的场景。

功能特性

🎯 核心功能

• 📊 账号信息查询：输入抖音昵称或抖音号，一键获取账号基础数据（粉丝数、获赞、作品总数、红狐指数等）
• 📋 近期作品爬取：自动获取近期作品列表（最多50条），包含点赞、评论、分享、互动数及作品链接
• 🔍 数据亮点分析：互动量TOP3作品分析 + 账号特征分析（更新频率、内容方向、互动表现、爆款特征）

✨ 特色亮点

• ⚡ 智能识别：自动判断输入类型（昵称/抖音号），无需手动切换查询模式
• 🔗 直达链接：昵称跳转账号主页，作品列表跳转视频页面
• 🔒 安全可靠：API 接入方式，无需登录抖音账号

一键安装

前置条件

• Python 3.6+
• 红狐数据API密钥（格式 ak_xxx）

安装方式

方式一：直接使用（推荐）

1. 确保项目文件已下载到本地
2. 配置环境变量：

   # macOS/Linux
   export REDFOX_API_KEY=你的API密钥值
   
   # Windows PowerShell
   $env:REDFOX_API_KEY="你的API密钥值"
   

3. 运行查询：

   python scripts/douyin_works_fetcher.py --account "抖音名称或抖音号"
   

方式二：在 Coze/Dify 等平台配置

1. 将技能文件夹上传至平台
2. 在环境变量中配置 REDFOX_API_KEY
3. 配置触发词，即可通过对话调用

环境变量配置

使用指南

基础使用

1. 查询账号作品

告诉助手你想查询的抖音账号：

用户：爬取“周幺姑家常菜”的抖音作品

助手：已为您查询到「周幺姑家常菜」的账号数据，粉丝547.1w，近期47条作品...

2. 精准查询（推荐）

使用抖音号进行精准查询，避免昵称模糊匹配：

用户：帮我查询抖音号 cdjjc028 的作品

助手：已精准匹配到「周幺姑家常菜」的账号数据...

高级使用

3. 导出JSON格式

需要结构化数据时，可指定JSON输出：

python scripts/douyin_works_fetcher.py --account "抖音号" --output json

命令速查

使用场景

场景一：品牌方竞品监测

角色：品牌营销经理

需求：监测竞品抖音账号的内容表现和互动数据

使用方式：

1. 输入竞品账号的抖音号进行查询
2. 查看近期作品列表和互动数据
3. 分析互动TOP3作品的内容特征

预期收益：及时掌握竞品内容动态，优化自身内容策略

场景二：MCN 机构达人评估

角色：MCN 运营人员

需求：评估达人账号的数据表现和内容方向

使用方式：

1. 查询目标达人的账号基础信息（粉丝数、获赞、红狐指数）
2. 分析近期作品的互动表现
3. 查看账号特征分析，了解更新频率和内容方向

预期收益：快速评估达人价值，辅助签约决策

场景三：自媒体内容优化

角色：抖音内容创作者

需求：学习同领域头部账号的爆款内容特征

使用方式：

1. 查询同领域头部账号的作品数据
2. 查看互动TOP3作品的分析
3. 学习爆款内容值得借鉴的点

预期收益：找到内容优化方向，提升账号互动表现

场景四：数据分析报告

角色：数据分析师

需求：批量获取抖音账号的结构化数据用于分析

使用方式：

1. 使用 --output json 参数导出结构化数据
2. 批量查询多个账号
3. 结合其他数据进行综合分析

预期收益：高效获取数据，支撑分析报告输出

项目架构

目录结构

douyin-works-crawler/
├── scripts/
│   └── douyin_works_fetcher.py   # 核心脚本（API调用+数据格式化）
├── references/
│   └── core_workflow.md          # 核心技能逻辑（接口规范、输出模板、处理规则）
├── CONFIG.json                   # 技能配置文件
└── SKILL.md                      # 技能说明文档

技术栈

核心模块说明

• DouyinWorksFetcher：核心类，封装查询和数据格式化两大功能
  • query_account()：查询账号信息和作品列表
  • format_markdown() / format_json()：输出格式化

📌 完整的接口规范、输出模板、处理规则等核心逻辑详见 references/core_workflow.md，Agent 执行时必须遵循该文件中的所有规则。

常见问答

安装相关问题

Q1: 运行时提示“未设置环境变量 REDFOX_API_KEY”怎么办？

A: 请先配置环境变量：

# macOS/Linux
export REDFOX_API_KEY=你的API密钥值

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

Q2: 红狐数据API密钥如何获取？

A: 前往红狐平台注册并申请API密钥，格式为 ak_xxx。

使用相关问题

Q3: 为什么不支持中文昵称查询？

A: 中文昵称不唯一（多个账号可能使用相同昵称），且广域库对昵称收录率低。请使用抖音号进行查询，抖音号查看方式：抖音APP → 目标账号主页 → 昵称下方。

Q4: 为什么有些账号查不到？

A: 可能该账号暂无数据记录，建议使用抖音号进行精准查询，或稍后再试。

Q5: 作品列表最多显示多少条？

A: 近期作品数据最多50条，按发布时间倒序排列。awemeCount 字段为账号历史作品总数，作品列表中的数量可能小于该值。

故障排除

Q6: API调用报错“积分不足”怎么办？

A: 红狐API按调用次数计费，请前往红狐平台充值积分。

Q7: 查询超时怎么办？

A: 请检查网络连接是否正常，脚本默认超时时间为30秒。如持续超时，可稍后重试。

📌 触发场景

• "爬取抖音作品"、"抖音作品列表"、"查看抖音视频"
• "抖音内容采集"、"抓取抖音作品"、"导出抖音作品"
• "下载抖音作品数据"、"抖音作品数据导出"
• 直接输入抖音名称/ID + "爬取/采集/导出作品"

🔌 数据来源

唯一数据源：红狐数据API

查询接口

详细的接口参数、响应字段、数据范围说明详见 references/core_workflow.md

🎯 核心功能

功能一：账号基础信息

查询并展示账号的核心基础数据：

功能二：近期作品列表

展示近期作品数据，支持分页（最多50条/页）：

功能三：数据亮点分析

自动分析并输出：

• 互动量TOP3：按互动数排序的前3条作品，含每条作品的互动结构分析（分享率、评论率、粉丝互动比等）和内容特征分析
• 账号特征分析：更新频率、内容方向、互动表现、爆款特征

📝 输出模板

使用说明： 严格按模板输出，不可省略章节。数据来源于API，如实展示。

数字格式规范： ≥1万用 w（如 3.2w），≥1亿用 亿（如 1.5亿），<1万用千分位逗号（如 8,642）。

链接列格式： 有opusUrl时显示 [链接](opusUrl)，无opusUrl时显示 -。

昵称链接格式： 昵称字段使用 [nickname](https://www.douyin.com/user/{secUid}) 格式，secUid 为空时显示纯文本。

互动数计算： 新接口无 interactiveCount 字段，需手动计算：点赞+评论+分享+收藏。

## 🎬 [nickname] - 抖音作品数据

### 账号基础信息

| 昵称 | 抖音号 | UID | 粉丝数 | 作品总数 |
|------|--------|-----|--------|---------|
| [nickname](https://www.douyin.com/user/[secUid]) | [accountId] | [uid] | [followerCount] | [total] |

---

### 近期作品（共[N]条）

| # | 发布时间 | 标题 | 点赞 | 评论 | 分享 | 收藏 | 互动 | 链接 |
|---|---------|------|------|------|------|------|------|------|
| 1 | [publishTime] | [content] | [likeCount] | [commentCount] | [shareCount] | [collectCount] | [互动合计] | [链接](opusUrl) / - |

> 作品列表为近期作品数据，支持分页（最多50条/页），账号作品总记录数为 [total] 条。

---

### 数据亮点

#### 互动量TOP3

🥇 **[title]**（互动[interactiveCount]）
> [根据账号数据、作品内容、内容定位等总结该作品值得学习点]

🥈 **[title]**（互动[interactiveCount]）
> [根据账号数据、作品内容、内容定位等总结该作品值得学习点]

🥉 **[title]**（互动[interactiveCount]）
> [根据账号数据、作品内容、内容定位等总结该作品值得学习点]

#### 账号特征分析

- **更新频率：** [基于近期作品发布间隔分析]
- **内容方向：** [基于作品标题关键词归纳内容赛道]
- **互动表现：** [基于互动数据整体趋势分析]
- **爆款特征：** [基于TOP3作品共性总结]

---

### 数据说明

- **数据范围：** 近期作品数据，支持分页（最多50条/页），按发布时间倒序
- **互动数：** 点赞+评论+分享+收藏
- **作品链接：** 接口返回opusUrl字段，提供作品直达链接
- **数据来源：** 红狐数据API（广域库）

*爬取时间：[YYYY-MM-DD HH:mm]*
> 💼 另外红狐配套全量数据库可提供完整详实数据，如需了解采购方案，可前往红狐hub[企业服务](https://redfox.hk/dashboard/enterprise)对接咨询

🔍 查询未命中处理

当查询未找到目标账号时，严禁联网搜索，按以下流程处理：

1. 中文昵称输入 → 直接阻断，输出引导提示（不发起 API 调用），引导用户提供抖音号
2. 匹配到错误账号 → 提示："昵称查询返回的是「[实际匹配的昵称]」，非您要找的账号。请提供目标账号的抖音号进行精准查询。"
3. 未查询到账号 → 输出提示信息：

未查询到当前账号的相关信息，请检查输入的抖音号或昵称是否正确。
建议使用抖音号进行精准查询，或稍后再试。

降级策略

API调用失败（如积分不足、网络异常）时明确告知用户错误原因，严禁联网搜索、严禁从第三方渠道估算或补充API未返回的字段。

🔧 使用方式

脚本调用

查询账号作品：

python3 scripts/douyin_works_fetcher.py --account "抖音名称或抖音号"

参数说明

自动识别逻辑

所有输入统一使用 uniqueName 参数查询。中文昵称为非唯一标识，检测到中文输入时直接阻断并引导用户提供抖音号（支持纯字母、字母+数字、纯数字三种类型）。

⚠️ 注意事项

• 🔌 唯一数据源： 所有数据仅从红狐API获取，不使用第三方渠道补充或估算
• 📊 数据范围： 近期作品数据，支持分页（最多50条/页），广域库仅收录热门数据
• 🔢 数字格式： ≥1万显示为 x.xw（如3.2w），≥1亿显示为 x.x亿，<1万用千分位逗号（如8,642）
• 🔗 作品链接： 接口返回opusUrl字段，表格中显示为 [链接](opusUrl)，无opusUrl时显示 -
• 🧮 互动数： 新接口无 interactiveCount 字段，需手动计算（点赞+评论+分享+收藏）
• 👤 账号信息： 从作品项的 author* 字段提取，无独立账号信息接口
• ❌ 中文昵称查询： 检测到中文输入时直接阻断，不发起 API 调用，引导用户提供抖音号（纯字母/字母+数字/纯数字）
• ❌ 未查询到账号： API返回空数据时，输出提示信息引导用户使用抖音号精准查询，严禁联网搜索、严禁生成无依据报告
• ❌ 昵称匹配到错误账号： 提示用户当前匹配结果非目标账号，引导提供抖音号重新查询，严禁联网搜索
• ✅ 如实输出： 作品数量如实展示

📌 完整的接口规范、输出模板、处理规则等核心逻辑详见 references/core_workflow.md，Agent 执行时必须遵循该文件中的所有规则。

🛠️ 版本信息

• 版本号： v3.0
• v3.0更新： 切换至 /story/api/dy/data/listWorkByAccount 广域库接口；请求参数统一使用 uniqueName（抖音号/昵称均走此参数，不再区分userId）；响应结构变更（作品在data.list，账号信息从author*字段提取）；新增收藏数(collectCount)字段；互动数改为手动计算（点赞+评论+分享+收藏）；作品链接字段改为opusUrl；支持分页（pageNum/pageSize）；新增时间范围筛选（startDate/endDate）；移除地域/获赞/红狐指数字段（新接口不返回）
• v2.3更新： 未查询到账号时输出友好提示信息；账号特征分析增加内容方向维度；增加单次调用原则避免浪费积分
• v2.2更新： 数字格式规范（万→w，≥1亿用亿，<1万千分位）；链接列格式固定为[链接](url)/-
• v2.1更新： 接口新增url字段，支持作品直达链接输出
• v2.0更新： 切换至 /dyData/queryUserWithWorks 接口，支持近期作品数据（最多50条）爬取；请求参数改为单值（accountId/accountName）；成功码改为2000；作品字段更新（workList/likeCount/publishTime）
• v1.0更新： 初始版本，基于红狐API /story/api/dyUser/query 实现账号信息+近7天作品爬取