{"openapi":"3.1.0","info":{"title":"数据检索2.0 API","version":"2.0.0","description":"本地自有公开数据查询 API。抖音路径兼容常见 TikHub 风格但默认不调用 TikHub；音乐榜单来自公开历史期次。"},"servers":[{"url":"http://localhost:4177","description":"Local development server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"可选。如果 .env 配置 OWN_API_TOKEN，则请求需携带 Authorization: Bearer <OWN_API_TOKEN> 或 x-api-key。"}},"schemas":{"ApiResponse":{"type":"object","properties":{"code":{"type":"integer"},"request_id":{"type":"string"},"message":{"type":"string"},"message_zh":{"type":"string"},"time":{"type":"string"},"time_stamp":{"type":"integer"},"time_zone":{"type":"string"},"docs":{"type":"string"},"router":{"type":"string"},"params":{"type":"object"},"data":{"type":"object"}}}}},"paths":{"/api/v1/douyin/app/v3/handler_user_profile":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"获取指定用户的信息 / Get information of specified user","security":[{"bearerAuth":[]}],"parameters":[{"name":"sec_user_id","in":"query","required":true,"description":"用户 sec_user_id / User sec_user_id","schema":{"type":"string"},"example":"MS4wLjABAAAANXSltcLCzDGmdNFI2Q_QixVTr67NiYzjKOIP5s03CAE"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing parameter"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"}}}},"/api/v1/douyin/app/v3/fetch_user_post_videos":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"获取用户主页作品数据 / Get user homepage video data","security":[{"bearerAuth":[]}],"parameters":[{"name":"sec_user_id","in":"query","required":true,"description":"用户 sec_user_id / User sec_user_id","schema":{"type":"string"}},{"name":"max_cursor","in":"query","required":false,"description":"分页游标 / Maximum cursor","schema":{"type":"integer","default":0}},{"name":"count","in":"query","required":false,"description":"每页数量 / Number per page","schema":{"type":"integer","default":20,"maximum":20,"minimum":1}},{"name":"sort_type","in":"query","required":false,"description":"排序类型：0 最新，1 最热 / Sort type","schema":{"type":"integer","default":0,"enum":[0,1]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing or invalid parameter"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"}}}},"/api/v1/douyin/app/v3/fetch_user_metrics":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"获取达人统计数据 / Get creator metrics","security":[{"bearerAuth":[]}],"parameters":[{"name":"sec_user_id","in":"query","required":true,"description":"用户 sec_user_id / User sec_user_id","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"近 N 天统计窗口 / Recent N-day window","schema":{"type":"integer","default":10,"minimum":1,"maximum":365}},{"name":"count","in":"query","required":false,"description":"用于分析的作品数量 / Number of works to analyze","schema":{"type":"integer","default":20,"maximum":20,"minimum":1}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing or invalid parameter"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"}}}},"/api/v1/douyin/app/v3/fetch_music_hot_videos":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"查找指定歌曲的爆款视频 / Find hot videos using a music track","security":[{"bearerAuth":[]}],"parameters":[{"name":"music_id","in":"query","required":false,"description":"抖音音乐 ID、音乐分享链接或使用该歌曲的视频链接","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"music_id 的别名输入；可传音乐/视频分享链接","schema":{"type":"string"}},{"name":"candidate_limit","in":"query","required":false,"description":"公开候选池目标","schema":{"type":"integer","default":150,"minimum":15,"maximum":2000}},{"name":"count","in":"query","required":false,"description":"最终返回 Top N；public-graph 返回异步任务信息","schema":{"type":"integer","default":30,"minimum":1,"maximum":500}},{"name":"sort_by","in":"query","required":false,"description":"爆款排序方式","schema":{"type":"string","default":"hot_score","enum":["hot_score","digg","comment","collect","share","latest","oldest"]}},{"name":"viral_threshold","in":"query","required":false,"description":"爆款点赞阈值","schema":{"type":"integer","default":10000,"minimum":0}},{"name":"viral_only","in":"query","required":false,"description":"是否仅返回达到点赞阈值的作品","schema":{"type":"boolean","default":false}},{"name":"search_enabled","in":"query","required":false,"description":"是否加入抖音官方游客综合搜索候选并使用官方游标续页","schema":{"type":"boolean","default":true}},{"name":"search_keywords","in":"query","required":false,"description":"可选搜索歌名，多个值用逗号分隔；未传时自动使用音乐标题","schema":{"type":"string"}},{"name":"search_candidate_limit","in":"query","required":false,"description":"综合搜索历次观测并集目标","schema":{"type":"integer","default":150,"minimum":0,"maximum":5000}},{"name":"search_batch_target","in":"query","required":false,"description":"单次任务新快照目标","schema":{"type":"integer","default":150,"minimum":1,"maximum":1000}},{"name":"search_page_limit","in":"query","required":false,"description":"每个综合搜索词最多抓取页数","schema":{"type":"integer","default":30,"minimum":1,"maximum":60}},{"name":"search_request_budget","in":"query","required":false,"description":"单次任务官方搜索页预算","schema":{"type":"integer","default":180,"minimum":10,"maximum":180}},{"name":"verify_audio","in":"query","required":false,"description":"是否验证其他 music_id / 原声候选的音频","schema":{"type":"boolean","default":true}},{"name":"match_threshold","in":"query","required":false,"description":"跨 music_id 音频匹配阈值","schema":{"type":"number","default":0.65,"minimum":0,"maximum":1}},{"name":"account_profile_limit","in":"query","required":false,"description":"补齐账号粉丝、总获赞和作品数的账号上限","schema":{"type":"integer","default":30,"minimum":0,"maximum":500}},{"name":"refresh","in":"query","required":false,"description":"是否忽略仍有效的公开数据缓存","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing or invalid music input"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"},"502":{"description":"Public music page unavailable"}}}},"/api/v1/douyin/app/v3/fetch_music_hot_videos_batch":{"post":{"tags":["Douyin-App-V3-Compatible"],"summary":"批量查找指定歌曲的爆款视频 / Batch find hot videos by music","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inputs"],"properties":{"inputs":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"candidate_limit":{"type":"integer","default":150,"minimum":15,"maximum":2000},"count":{"type":"integer","default":30,"minimum":1,"maximum":500},"sort_by":{"type":"string","default":"hot_score","enum":["hot_score","digg","comment","collect","share","latest","oldest"]},"viral_threshold":{"type":"integer","default":10000,"minimum":0},"viral_only":{"type":"boolean","default":false},"search_enabled":{"type":"boolean","default":true},"search_keywords":{"oneOf":[{"type":"string"},{"type":"array","maxItems":8,"items":{"type":"string"}}]},"search_candidate_limit":{"type":"integer","default":150,"minimum":0,"maximum":5000},"search_batch_target":{"type":"integer","default":150,"minimum":1,"maximum":1000},"search_page_limit":{"type":"integer","default":30,"minimum":1,"maximum":60},"search_request_budget":{"type":"integer","default":180,"minimum":10,"maximum":180},"verify_audio":{"type":"boolean","default":true},"match_threshold":{"type":"number","default":0.65,"minimum":0,"maximum":1},"account_profile_limit":{"type":"integer","default":30,"minimum":0,"maximum":500},"refresh":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Batch completed; inspect each result ok/error field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing or invalid inputs"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"}}}},"/api/v1/douyin/app/v3/music_collection_jobs":{"post":{"tags":["Douyin-Public-Graph"],"summary":"创建后端公开数据音乐扫描任务 / Create public graph job","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"严格同曲任务使用：music_id、音乐链接或使用该歌曲的视频链接"},"keyword":{"type":"string","description":"纯综合搜索使用：歌曲名称或搜索关键词；同时设置 search_only=true"},"candidate_limit":{"type":"integer","default":150,"minimum":15,"maximum":2000},"count":{"type":"integer","default":30,"minimum":1,"maximum":500},"sort_by":{"type":"string","default":"hot_score","enum":["hot_score","digg","comment","collect","share","latest","oldest"]},"viral_threshold":{"type":"integer","default":10000,"minimum":0},"viral_only":{"type":"boolean","default":false},"search_enabled":{"type":"boolean","default":true},"search_keywords":{"oneOf":[{"type":"string"},{"type":"array","maxItems":8,"items":{"type":"string"}}]},"search_candidate_limit":{"type":"integer","default":150,"minimum":0,"maximum":5000},"search_batch_target":{"type":"integer","default":150,"minimum":1,"maximum":1000},"search_page_limit":{"type":"integer","default":30,"minimum":1,"maximum":60},"search_request_budget":{"type":"integer","default":180,"minimum":10,"maximum":180},"verify_audio":{"type":"boolean","default":true},"match_threshold":{"type":"number","default":0.65,"minimum":0,"maximum":1},"account_profile_limit":{"type":"integer","default":30,"minimum":0,"maximum":500},"refresh":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Completed immediately from a real local cache"},"202":{"description":"Job queued or started"},"400":{"description":"Invalid input"}}}},"/api/v1/douyin/app/v3/music_collection_jobs/{job_id}":{"get":{"tags":["Douyin-Public-Graph"],"summary":"查询音乐采集任务 / Get collection job","security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current progress and completed result"},"404":{"description":"Job not found"}}},"delete":{"tags":["Douyin-Public-Graph"],"summary":"取消音乐采集任务 / Cancel collection job","security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancellation requested"},"404":{"description":"Job not found"}}}},"/api/v1/douyin/app/v3/discover_music_related_videos":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"发现跨 music_id / 原声同曲视频 / Discover related videos across music IDs","security":[{"bearerAuth":[]}],"parameters":[{"name":"music_id","in":"query","required":false,"description":"抖音音乐 ID、音乐分享链接或使用该歌曲的视频链接","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"music_id 的别名输入","schema":{"type":"string"}},{"name":"author_limit","in":"query","required":false,"description":"扫描种子作者数量","schema":{"type":"integer","default":5,"minimum":1,"maximum":10}},{"name":"candidate_limit","in":"query","required":false,"description":"文本候选数量上限","schema":{"type":"integer","default":20,"minimum":1,"maximum":30}},{"name":"match_threshold","in":"query","required":false,"description":"音频匹配阈值","schema":{"type":"number","default":0.65,"minimum":0,"maximum":1}},{"name":"verify_audio","in":"query","required":false,"description":"是否验证跨 ID 候选音频","schema":{"type":"boolean","default":true}},{"name":"viral_threshold","in":"query","required":false,"description":"爆款点赞阈值","schema":{"type":"integer","default":10000,"minimum":0}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Missing or invalid music input"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"},"502":{"description":"Public discovery or audio verification unavailable"}}}},"/api/v1/douyin/web/fetch_multi_video":{"post":{"tags":["Douyin-Web-Compatible"],"summary":"批量获取视频信息 / Batch get public video details","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","pattern":"^\\d{5,30}$"}}}}},"responses":{"200":{"description":"Public SSR details and per-ID failures"},"422":{"description":"Body must be a top-level array containing 1-50 numeric IDs"}}}},"/api/v1/douyin/app/v3/fetch_multi_video":{"post":{"tags":["Douyin-App-V3-Compatible"],"summary":"批量获取视频信息 V1 / Batch get public video details V1","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^\\d{5,30}$"}}}}},"responses":{"200":{"description":"Public SSR details and per-ID failures"},"422":{"description":"Body must be a top-level array containing 1-10 numeric IDs"}}}},"/api/v1/douyin/app/v3/fetch_music_video_list":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"获取指定音乐的公开首屏观测并集 / Get observed public music videos","security":[{"bearerAuth":[]}],"parameters":[{"name":"music_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{5,30}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":20}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Real public first-screen data with local cursor metadata"},"502":{"description":"Public endpoint unavailable"}}}},"/api/v1/douyin/app/v3/fetch_hashtag_video_list":{"get":{"tags":["Douyin-App-V3-Compatible"],"summary":"获取指定话题的公开视频首屏 / Get public first-screen hashtag videos","security":[{"bearerAuth":[]}],"parameters":[{"name":"ch_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{5,30}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"sort_type","in":"query","required":false,"schema":{"type":"integer","default":0,"enum":[0,1,2]}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":15}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Real public first-screen data with local cursor metadata"},"502":{"description":"Public endpoint unavailable"}}}},"/api/v1/douyin/search/fetch_music_search":{"post":{"tags":["Douyin-Search-Compatible"],"summary":"音乐关键词搜索请求契约 / Music search request contract","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string"},"cursor":{"type":"integer","default":0},"search_id":{"type":"string","default":""}}}}}},"responses":{"501":{"description":"Protected public search is not available without platform verification"}}}},"/api/v1/douyin/search/fetch_video_search_v1":{"post":{"tags":["Douyin-Search-Compatible"],"summary":"视频关键词搜索请求契约 / Video search request contract","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string"},"cursor":{"type":"integer","default":0},"search_id":{"type":"string","default":""},"backtrace":{"type":"string","default":""}}}}}},"responses":{"501":{"description":"Protected public search is not available without platform verification"}}}},"/api/v1/douyin/web/get_sec_user_id":{"get":{"tags":["Douyin-Web-Compatible"],"summary":"提取单个用户 id / Extract single sec_user_id","security":[{"bearerAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"description":"抖音用户主页链接、短链或包含 sec_user_id 的文本","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Cannot resolve sec_user_id"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"}}}},"/api/v1/music/kugou/top500/history":{"get":{"tags":["Music-Charts"],"summary":"查询酷狗 TOP500 历史榜 Top 20 / Get historical Kugou TOP500 snapshots","security":[{"bearerAuth":[]}],"parameters":[{"name":"start_date","in":"query","required":true,"description":"开始日期，格式 YYYY-MM-DD；公开归档当前最早为 2021-01-01。","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":true,"description":"结束日期，格式 YYYY-MM-DD；超过最新期次时自动截到最新可用日期。","schema":{"type":"string","format":"date"}},{"name":"interval_days","in":"query","required":false,"description":"查询节点间隔，固定为 10 天。","schema":{"type":"integer","default":10,"enum":[10]}},{"name":"limit","in":"query","required":false,"description":"每期返回歌曲数，固定为前 20 首。","schema":{"type":"integer","default":20,"enum":[20]}}],"responses":{"200":{"description":"真实酷狗历史期次及每期 Top 20","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"日期格式或范围无效"},"401":{"description":"Unauthorized when OWN_API_TOKEN is configured"},"502":{"description":"酷狗公开历史榜暂时不可用"}}}}}}