数据检索2.0 API

认证

如果 `.env` 未设置 OWN_API_TOKEN，本地 API 不需要认证；如果设置了，则请求需携带：

Authorization: Bearer <OWN_API_TOKEN>
# 或
x-api-key: <OWN_API_TOKEN>

GET /api/v1/douyin/web/get_sec_user_id

从抖音公开主页链接、短链或包含 sec_user_id 的文本里解析用户 sec_user_id。

curl 'http://localhost:4177/api/v1/douyin/web/get_sec_user_id?url=https://www.douyin.com/user/YOUR_SEC_USER_ID'

GET /api/v1/douyin/app/v3/handler_user_profile

获取指定用户的信息。

curl 'http://localhost:4177/api/v1/douyin/app/v3/handler_user_profile?sec_user_id=YOUR_SEC_USER_ID'

GET /api/v1/douyin/app/v3/fetch_user_post_videos

获取用户主页作品数据。

curl 'http://localhost:4177/api/v1/douyin/app/v3/fetch_user_post_videos?sec_user_id=YOUR_SEC_USER_ID&max_cursor=0&count=20&sort_type=0'

GET /api/v1/douyin/app/v3/fetch_user_metrics

获取达人统计数据：粉丝、总获赞、近 N 天均赞、近 N 天最高点赞作品。

curl 'http://localhost:4177/api/v1/douyin/app/v3/fetch_user_metrics?sec_user_id=YOUR_SEC_USER_ID&days=10&count=20'

POST /api/v1/douyin/web/fetch_multi_video

按 TikHub Web 版契约接收顶层作品 ID 字符串数组，最多 50 个；并发读取移动公开视频 SSR 详情和本地缓存。

curl -X POST 'http://localhost:4177/api/v1/douyin/web/fetch_multi_video' \
  -H 'Content-Type: application/json' \
  -d '["AWEME_ID_1","AWEME_ID_2"]'

• data.aweme_list 返回成功详情；每条包含点赞、评论、收藏、分享和 statistics_complete。
• data.filter_list 返回无法读取的 ID 和公开页面错误，不会用假数据补齐。
• data.tikhub_called=false、android_emulator_used=false、signing_generated=false。
• App V3 兼容路径为 POST /api/v1/douyin/app/v3/fetch_multi_video，请求体相同，最多 10 个。

GET /api/v1/douyin/app/v3/fetch_music_video_list

读取指定 music_id 单次最多 20 条的真实公开作品首屏，并保存历次公开快照并集；本地 cursor 在观测并集内分页。

curl 'http://localhost:4177/api/v1/douyin/app/v3/fetch_music_video_list?music_id=YOUR_MUSIC_ID&cursor=0&count=10'

• public_first_screen_count 是最新一次公开快照数量，public_observed_union_count 是历次快照去重并集。
• observation_history.snapshot_count 和 distinct_snapshot_count 分别表示刷新次数和内容不同的快照数。
• 歌曲图谱任务的 discovery.confirmed_graph_observation_history 保存历次已确认同曲作品并集，可查看累计确认数和本次新增数。
• 时间序列并集可以扩大长期覆盖，但平台没有提供可终止的游客深分页，所以 coverage_complete=false。

pagination_mode=public_first_screen_local_cursor。platform_has_more 只记录平台信号，不代表本接口已取得受保护深分页。

GET /api/v1/douyin/app/v3/fetch_hashtag_video_list

读取指定话题的真实公开作品首屏；sort_type=0 保留公开顺序，1 按点赞排序，2 按发布时间排序。

curl 'http://localhost:4177/api/v1/douyin/app/v3/fetch_hashtag_video_list?ch_id=YOUR_CHALLENGE_ID&cursor=0&sort_type=0&count=10'

关键词搜索兼容契约

以下 TikHub 风格 JSON 搜索路径仍要求受保护平台验证，因此返回 501。歌曲图谱任务不调用这些路径，而是从抖音官方游客 SEO 首屏取得 search_id、cursor 和 backtrace，再使用官方匿名游客状态分页补充候选；不生成签名、不绕验证、不返回模拟结果。

POST /api/v1/douyin/search/fetch_music_search
POST /api/v1/douyin/search/fetch_video_search_v1

{"keyword":"歌曲名","cursor":0,"sort_type":"0","publish_time":"0","filter_duration":"0","content_type":"0","search_id":"","backtrace":""}

GET /api/v1/douyin/app/v3/fetch_music_hot_videos

用公开音乐、话题和作者首屏扩展候选池，读取公开视频 SSR 详情，验证其他 music_id 后在本地计算爆款排行。public-graph 返回异步任务。

curl 'http://localhost:4177/api/v1/douyin/app/v3/fetch_music_hot_videos?music_id=YOUR_MUSIC_ID&candidate_limit=500&count=30&search_enabled=true&search_keywords=YOUR_SONG_TITLE&search_candidate_limit=300&search_page_limit=30&sort_by=hot_score&viral_threshold=10000&viral_only=false&verify_audio=true'

• hot_score = 点赞 + 评论×4 + 收藏×3 + 分享×8，用于本地综合排序。
• statistics_source=public_video_detail_page 表示数据来自公开视频 SSR 详情；statistics_complete=true 表示四项互动数据完整。
• candidate_pool_size、confirmed_count 和 returned_count 分别表示候选池、确认同曲和最终 Top N 数量。
• unique_account_count 是本次确认同曲样本中的独立账号数；account_count_complete=false 表示它是可验证下界，不是抖音全站总量。
• account_summary.accounts 返回账号粉丝、总获赞、作品数、关联视频数，以及关联视频的赞、评、藏、分享聚合和最高赞作品。
• aweme_list 是按 count 返回的统一 Top N，包含输入音链和音频验证通过的关联音链作品，并按 aweme_id 去重。
• source_channel_zh、source_music_title 和 source_music_url 标明每条榜单视频的实际来源音链。
• search_related.aweme_list 独立返回综合搜索相关视频；每条结果的 search_relevance_level 为 exact_title、music_id_corroborated、conflicting_music_title 或 expanded_candidate。
• high_relevance_count 统计完整歌名直接命中和同音链佐证结果；控制台默认展示高相关，扩展候选可单独切换查看。
• conflicting_music_title_count 统计文案命中但具名音乐标题明确不同的结果；这类视频会降入扩展候选。高相关仍是公开元数据佐证，不等于音频指纹确认。
• visible_ranking_overlap_count 返回与本次严格同曲 Top 榜单的交集数；每条交集视频标记 duplicate_with_returned_ranking=true。
• search_related.pagination 返回抓取页数、分页搜索词数、最后游标、是否遍历完和每个搜索词的停止原因。
• 仅关键词相关结果用于发现音链外爆款，不会计入 confirmed_count、unique_account_count 或严格同曲 Top N。
• requested_count、returned_count、count_satisfied 和 count_note_zh 会明确说明数量是否满足。
• 仅输入歌曲名称无法区分原唱、翻唱、剪辑版等音乐版本，请使用 music_id、音乐链接或样例视频链接。
• public-graph 返回 202、job_id 和 poll_url；任务在后端运行，不使用 Android 模拟器。
• 若歌曲公开作品不足或作品流不再前进，返回 count_satisfied=false 和实际数量；不会重复或生成数据补足。
• exact_music_id 是同 ID，audio_fingerprint_match / verified_music_id_graph 是音频验证通过的其他 music_id。

POST /api/v1/douyin/app/v3/music_collection_jobs

创建纯后端公开数据图谱任务。无需抖音账号、Android 模拟器、用户提供 Cookie 或自生成签名；搜索分页自动使用官方下发的匿名游客状态。

curl -X POST 'http://localhost:4177/api/v1/douyin/app/v3/music_collection_jobs' \
  -H 'Content-Type: application/json' \
  -d '{"input":"YOUR_MUSIC_ID","candidate_limit":500,"count":30,"search_enabled":true,"search_keywords":"YOUR_SONG_TITLE","search_candidate_limit":300,"search_page_limit":30,"sort_by":"hot_score","viral_threshold":10000,"viral_only":false,"verify_audio":true,"account_profile_limit":100}'

查询与取消

curl 'http://localhost:4177/api/v1/douyin/app/v3/music_collection_jobs/YOUR_JOB_ID'
curl -X DELETE 'http://localhost:4177/api/v1/douyin/app/v3/music_collection_jobs/YOUR_JOB_ID'

• 任务状态为 queued、running、completed、failed 或 cancelled；完成后结果位于 data.result。
• progress.candidate_pool_count、confirmed_count 和 detail_checked_count 分别表示候选、确认同曲和详情检查进度。
• 完成结果中的 account_summary 按全部确认同曲作品聚合，不只统计最终 Top N。
• account_summary.video_preview_limit=20；账号的确认作品数可能高于响应中保留的预览数。
• 纯关键词模式使用 keyword + search_only=true；只构造保留完整歌名的场景词，并返回高相关/扩展候选分层和分页状态。
• search_related 返回相关度计数、视频结果和分页状态，discovery.official_comprehensive_search 返回查询词、游标页数与观测并集。
• coverage_complete=false 始终表示结果不是抖音全站全量枚举，即使 count_satisfied=true。

POST /api/v1/douyin/app/v3/fetch_music_hot_videos_batch

批量处理 1-10 个音乐 ID、音乐链接或使用该歌曲的视频链接。公开图谱模式为每首创建独立后端任务。

curl -X POST 'http://localhost:4177/api/v1/douyin/app/v3/fetch_music_hot_videos_batch' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":["MUSIC_ID_1","MUSIC_ID_2"],"candidate_limit":500,"count":30,"viral_threshold":10000,"viral_only":false}'

GET /api/v1/douyin/app/v3/discover_music_related_videos

第一层扫描精确歌曲种子作者的公开作品首屏，第二层在本机用音频特征和 DTW 验证跨 music_id / 原声同曲候选。

curl 'http://localhost:4177/api/v1/douyin/app/v3/discover_music_related_videos?music_id=YOUR_MUSIC_ID&author_limit=5&candidate_limit=20&match_threshold=0.65&verify_audio=true'

• association_type=audio_fingerprint_match 表示跨 music_id 候选已通过本地音频验证；exact_music_id_discovered 表示从作者页额外发现的同 ID 作品。
• 算法为 librosa_chroma_mfcc_multiref_local_dtw_v3。每条候选 music_id 最多选择 2 条代表视频，与最多 3 条目标参考交叉比对并取最可信的一对。
• 整段匹配要求 Chroma≤0.25、MFCC≤0.48、重叠不少于 8 秒；局部片段匹配使用 6 秒窗口，要求 Chroma≤0.65、MFCC≤0.90、重叠不少于 5.5 秒。两种方式都必须达到请求中的综合分阈值。
• candidates 保留所有文本候选及通过/拒绝原因；aweme_list 只返回已验证匹配。
• 每条作品包含真实点赞、评论、收藏、分享，以及源 music_id、参考作品和音频底层距离。
• coverage_complete=false：这是种子作者图扩展，不是抖音全站全量枚举。

GET /api/v1/music/kugou/top500/history

读取酷狗 TOP500 公开历史期次，按日期范围每 10 日选取一个真实榜单节点，每期固定返回前 20 首。

curl 'http://localhost:4177/api/v1/music/kugou/top500/history?start_date=2024-01-01&end_date=2024-03-01'

• snapshots[].target_date 是每 10 日查询节点，chart_date 是实际匹配的历史榜单日期。
• 历史期次的 volid 会作为实际榜单 rankid 查询，并校验歌曲返回日期与期次一致。
• songs 固定为 Top 20，包含排名、歌名、歌手、时长、封面和上期排名。

数据源 Provider

• DATA_PROVIDER=douyin-public：默认。用户资料走不登录的公开端点；作品列表会尝试公开端点，若平台返回空响应/校验要求则返回明确错误。
• DATA_PROVIDER=browser-public：打开本机 Chrome。用户作品读取移动公开分享页自己加载的首屏 JSON；local_cursor_mode=true 时 max_cursor 是本地首屏缓存游标。
• MUSIC_DATA_PROVIDER=public-graph：推荐；纯后端扫描公开音乐/话题/作者首屏和作品 SSR 详情，并在本机验证其他 music_id 的音频。
• MUSIC_DATA_PROVIDER=android-guest：可选慢速兜底；通过可 root 本地模拟器中的官方 Android App 游客态逐条读取。
• MUSIC_DATA_PROVIDER=browser-public：歌曲作品旧模式，仅覆盖移动公开音乐页当前可见范围。
• PUBLIC_FALLBACK_TO_MOCK=true：公开视频列表不可用时返回本地演示数据，便于前端调试。
• DATA_PROVIDER=mock：本地生成演示数据，不请求外部 API。
• DATA_PROVIDER=file：读取 data/douyin-users.json 和 data/douyin-videos.json，用于接你自己的采集/导入数据。
• DATA_PROVIDER=douyin-web：保留实验模式，尝试 Douyin Web 公开端点；可选配置 DOUYIN_COOKIE，不做验证码/风控绕过。

作品列表说明

browser-public 模式会读取移动公开分享页返回的首屏作品 JSON。它不是 TikHub 代理，也不会自己生成 a_bogus / 指纹签名。

• 第一次请求传 max_cursor=0。
• 如果响应 has_more=true，继续传响应里的本地 max_cursor 可取完这次首屏缓存。
• platform_has_more=true 表示抖音侧还有更深分页；当前模式不强拉平台深分页。