抖音直播间观众榜 API
按 live_id 读一场抖音直播的观众榜:每行一位观众,带 rank、nickname、douyin_id、user_id 和 is_verified,每千次 $0.56。
- 一次给全,不翻页
rank从 1 开始,按榜单顺序排- 失败和空结果不收费
接口健康状态
- 24h 健康值
- 正常
- 健康 / 正常
- 可用
- 少量可用
- 基本不可用
24 小时趋势
30 天趋势
1请求
POST /api/v1/social { "platform": "douyin", "action": "live_viewers", "params": { "live_id": "7710380709042457398" } }2JSON 响应
{ "results": [ { "user_id": "", "rank": 1, "is_verified": false }, … ], "count": 106 }3行
user_id rank is_verified 1 false 2 false 4CSV
douyin-live_viewers-sample.csv rank,user_id,douyin_id,nickname,avatar_url,is_verified,url,platform
live_id,返回这一场的观众榜,results 里每行是一位观众,列成字段表,也可下载为 CSV。能拿到什么数据
下表取自对 7710380709042457398 的一次真实调用,采集于 2026年11月21日 15:29(UTC),共返回 106 行;灰条是隐去的个人信息(CSV 里是 •••)。你自己调用时,按字段表返回这些字段。
| rank | user_id | douyin_id | nickname | avatar_url | is_verified | url | platform |
|---|---|---|---|---|---|---|---|
1 | 五•••伟 | false | douyin.com/ | douyin | |||
2 | 努••• | false | douyin.com/ | douyin |
用途
看一场直播的主要观众
按
rank读榜单,看排在前面的是哪些账号。认出观众账号
user_id、douyin_id和url指向观众的账号,nickname是他们的昵称。筛认证账号
读
is_verified,找出榜上的认证观众。配合场次详情
同一个
live_id也交给live_session,一起读这一场的标题、主播和点赞数。
限制和注意事项
live_id必填,是纯数字的场次号,取自live_room、user_live返回行的live_id;每开一次播换一个,不是直播间链接里那串数字。- 榜单一次给全,不翻页。
- 这一场结束后,榜单只剩零星几位。
rank从 1 开始,是观众在榜上的名次。user_id、douyin_id、nickname是观众的账号信息,样例里会被隐去。- 一次调用读一场直播的榜单。
价格
每次调用 $0.000556,按次计费,不按条数算;一次调用读完一场的榜单。失败和空结果不收费。
| 调用次数 | 费用 |
|---|---|
| 10,000 | $5.56 |
| 100,000 | $55.56 |
| 1,000,000 | $555.56 |
合计按每次调用的标价算。
代码示例
#curl -X POST 'https://api.everyinfra.com/api/v1/social' \
-H "Authorization: Bearer $EVERYINFRA_API_KEY" \
-H 'Content-Type: application/json' \
--data-raw '{
"platform": "douyin",
"action": "live_viewers",
"params": {
"live_id": "7710380709042457398"
}
}'OpenAPI 定义 (JSON)示例从环境变量 EVERYINFRA_API_KEY 读取 Key,复制出去的代码不含你的 Key。
API 参考
下面是 live_viewers 的参数、响应字段、错误和计费,可以复制整页,或用 Markdown 打开后交给 AI 助手。
AI 提示词
#请帮我用 EveryInfra 的「抖音直播间观众榜」接口(douyin/live_viewers)写一个数据采集脚本。
接口约定:
- 请求:POST https://api.everyinfra.com/api/v1/social,请求头 Authorization: Bearer <API Key>;Key 从环境变量 EVERYINFRA_API_KEY 读取,不要写进代码。
- 请求体里 platform 填 douyin,action 填 live_viewers,参数放在 params 里。
- 必填参数:
- live_id:直播场次 ID,纯数字,取自 live_room、user_live 返回行的 live_id;每开一次播换一个,不是直播间链接里的那串数字。这一场结束后榜单只剩零星几位。
- 可选参数:
- limit:这次调用最多返回的条数,整数,至少为 1;不传按默认值,实际返回可能少于这个数。
- 返回一组记录,每条记录的主要字段:rank(名次(从 1 开始):trendi…)、user_id、douyin_id(抖音号(用户自定义的可搜索 ID))、nickname(昵称)、avatar_url、is_verified、url。
- 示例请求体:
{
"platform": "douyin",
"action": "live_viewers",
"params": {
"live_id": "7710380709042457398"
}
}
- 计费:$0.56 / 千次;失败和空结果不扣费。
- 一次要采几十上百个时,在请求体加 "mode": "async":先拿到 job_id,再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时,按错误信息里的候选参数和允许值修正;返回 429 或 503 时,按 Retry-After 等待后重试。
写代码前,先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式,再把方案和大概花费讲给我确认。请求参数
#| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
Authorization | header | string | 是 | - | Bearer 加你的 API Key。在控制台创建;不要放进网址或代码仓库。 |
platform | body | string | 是 | douyin | 平台标识,固定值。 |
action | body | string | 是 | live_viewers | 能力标识,固定值。 |
live_id | body.params | string | 是 | - | 直播场次 ID,纯数字,取自 live_room、user_live 返回行的 live_id;每开一次播换一个,不是直播间链接里的那串数字。这一场结束后榜单只剩零星几位。 |
limit | body.params | integer (1–) | 否 | - | 这次调用最多返回的条数,整数,至少为 1;不传按默认值,实际返回可能少于这个数。 |
响应示例
#{ "id": "req_…", "platform": "douyin", "action": "live_viewers", "results": [ { "rank": 1, "user_id": "•••", "douyin_id": "•••", "nickname": "五•••伟", "avatar_url": "https://p11.douyinpic.com/•••", "is_verified": false, "url": "https://www.douyin.com/•••", "platform": "douyin" }, { "rank": 2, "user_id": "•••", "douyin_id": "•••", "nickname": "努•••", "avatar_url": "https://p11.douyinpic.com/•••", "is_verified": false, "url": "https://www.douyin.com/•••", "platform": "douyin" } ], "count": 106, "billing": { "charged": …, "charged_usd": …, "balance_after_usd": …, … }, "quota": { … }}
返回字段
#业务数据在 results 里;下表是每条记录可能包含的字段,平台没有提供的值不会被编造。
| 字段 | 含义 |
|---|---|
rank | 名次(从 1 开始):trending 是热榜排名,xingtu_creator_rankings 是星图榜单里的名次,billboard_search_hot 是搜索热榜名次,search_suggest 是联想词在抖音搜索框里的顺序;billboard_rise_list、billboard_challenge_hot、billboard_topic_hot 是热点宝榜单名次(翻页接着往下数)。 |
user_id | 用户在原平台的唯一 ID。 |
douyin_id | 抖音号(用户自定义的可搜索 ID)。 |
nickname | 昵称。 |
avatar_url | 头像图片链接。部分平台给的是带尺寸参数的 CDN 链接,可能有时效。 |
is_verified | 是否为平台认证账号(蓝V等)。null 表示无法判定。 |
url | 该记录在原平台上的可访问链接。 |
platform | 数据来源平台标识,与请求里的 platform 一致(如 xiaohongshu、tiktok)。 |
错误与计费
#- 401
- 缺少 Key 或 Key 无效。
- 402
- 余额不足,先充值。
- 422
- 参数名或取值不对,按错误信息给的候选改;不扣费。
- 429
- 超过每分钟请求上限,按 Retry-After 等待后再试。
- 503
- 暂时无法完成,预扣的费用退回;结果未知时先核对,不要直接重发。
- 200 空结果
- 没有数据,不扣费。
常见问题
观众榜接口返回什么?
每行一位观众:rank、user_id、douyin_id、nickname、avatar_url、is_verified 和 url。
为什么直播结束后榜单变短了?
这一场结束后,榜单只剩零星几位。
live_id 从哪里来?
从 live_room 或 user_live 的返回行里取。它是场次号,每开播一次换一个,不是直播间链接里的数字。
读一场观众榜要多少钱?
每次 $0.000556,每千次 $0.56,按调用次数算,不按条数算。失败和空结果不收费。
相关的 抖音 能力
同一把 Key 还能调用抖音的其他能力。
- 关键词搜索
search每千次 $8.33关键词搜索:返回列表,默认 10 条、单次最多 50 条;主要字段 next_page_token、id、url、text、media_type、video_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 主页或对象详情
profile每千次 $0.56主页或对象详情:返回单个对象;主要字段 user_id、douyin_id、nickname、bio、url、follower_count。 - 用户内容
user_posts每千次 $0.56用户内容:返回列表,默认 20 条、单次最多 100 条;主要字段 next_page_token、id、url、text、media_type、video_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 视频详情
video每千次 $0.56视频详情:返回单个对象;主要字段 id、url、text、media_type、video_url、like_count。 - 评论
comments每千次 $0.56评论:返回列表,默认 20 条、单次最多 150 条;主要字段 next_page_token、id、text、like_count、reply_count、author_name。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页按这一页的条数计费,每 20 条算一次调用。 - 评论回复
comment_replies每千次 $0.56评论回复:返回列表,默认 20 条、单次最多 100 条;主要字段 next_page_token、id、text、like_count、author_name、author_id。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页按这一页的条数计费,每 20 条算一次调用。 - 热榜
trending每千次 $0.56热榜:返回列表,默认 20 条、单次最多 60 条;主要字段 rank、keyword、hot_value、video_count、board、image_url。 - 视频文稿
transcript每千次 $0.56视频文稿:返回单个对象;主要字段 id、url、title、text、posted_at、play_count。 - 达人搜索
creator_search每千次 $0.56达人搜索:返回列表,默认 20 条、单次最多 20 条;主要字段 user_id、douyin_id、nickname、url、avatar_url、follower_count。 - 达人粉丝画像
creator_audience每千次 $0.56达人粉丝画像:返回单个对象;主要字段 user_id、audience_distribution、audience_tgi、dimension_code、platform。 - 达人涨粉趋势
creator_trend每千次 $0.56达人涨粉趋势:返回单个对象;主要字段 user_id、follower_trend、average_follower_count、dimension_code、platform。 - 同类达人对比
creator_benchmark每千次 $0.56同类达人对比:返回单个对象;主要字段 user_id、average_post_count、average_comment_count、average_share_count、average_follower_growth、average_like_count。 - 星图达人搜索
xingtu_creator_search每千次 $0.56星图达人搜索:返回列表,默认 20 条、单次最多 20 条;主要字段 creator_id、user_id、nickname、follower_count、gender、city。 - 星图达人分析
xingtu_creator_analytics每千次 $0.56星图达人分析:返回单个对象;主要字段 creator_id、creator_type、follower_count、average_play_count、city、province。 - 星图达人报价
xingtu_rate_card每千次 $0.56星图达人报价:返回单个对象;主要字段 creator_id、rate_tiers、platform。 - 星图达人榜单
xingtu_creator_rankings每千次 $0.56星图达人榜单:返回列表,默认 5 条、单次最多 5 条;主要字段 creator_id、user_id、url、nickname、avatar_url、gender。 - 商品搜索
product_search每千次 $8商品搜索:返回列表。按关键词搜索抖音商城商品,一页最多 30 条,返回价格、近 30 天销量、好评率、店铺、类目、佣金和合作达人数。目前只出第 1 页,第 2 页起(不管用 page_token 还是 page)暂时回 503、不扣费;每页算一次调用。主来源暂时不可用时改由备用来源返回,这时最多 5 条、没有下一页,且只有 product_id、title、url、image_url、price_cny、price_cny_minor、shop_id、source_keyword 和 search_rank,promotion_id、white_image_url、price_label、monthly_sales、good_review_ratio、sales_trend、category_path、category_ids、category_depth、shop_name、shop_logo_url、shop_score、commission_rate_percent、commission_cny、cooperating_creator_count、tags、recommend_reason 都不出现;标价在一角及以下的是引流起售价,不返回价格。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 店铺商品
shop_products每千次 $8店铺商品:返回列表,每次一页、固定 10 条(最后一页可能更少),要更多就把响应顶层的 next_page_token 作为 page_token 再调;limit 照收但不起作用;主要字段 next_page_token、product_id、promotion_id、title、url、image_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 商品详情
product_detail每千次 $8商品详情:返回单个对象;主要字段 product_id、title、price_cny、discount_price_cny、sales_text、sold_count。 - 直播商品搜索
live_product_search每千次 $0.56直播商品搜索:返回列表,默认 3 条、单次最多 3 条;主要字段 product_id、sku_id、title、image_url、price_cny、shop_id。 - 话题搜索
hashtag_search每千次 $15.56话题搜索:返回列表,默认 20 条、单次最多 200 条;主要字段 hashtag_id、hashtag_name、search_rank、heat_index、period_video_count、period_like_count。 - 话题详情
hashtag_detail每千次 $15.56话题详情:返回单个对象;主要字段 hashtag_id、hashtag_name、total_view_count、participant_count、created_at、url。 - 热点宝视频热榜
billboard_video_hot每千次 $0.81热点宝视频热榜:返回列表,每次一页、每页最多 50 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、image_count、cover_image_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 热点宝低粉爆款榜
billboard_low_fan_explosion每千次 $0.81热点宝低粉爆款榜:返回列表,每次一页、每页最多 50 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、image_count、cover_image_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 热点宝高完播率榜
billboard_high_completion每千次 $0.81热点宝高完播率榜:返回列表,每次一页、每页最多 50 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、image_count、cover_image_url。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 热点宝搜索热榜
billboard_search_hot每千次 $0.81热点宝搜索热榜:返回列表,每次一页、固定 50 条(最后一页可能更少),要更多就把响应顶层的 next_page_token 作为 page_token 再调;limit 照收但不起作用;主要字段 rank、keyword、hot_value、search_trend、platform。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 热点宝账号搜索
billboard_account_search每千次 $0.81热点宝账号搜索:返回列表,每次一页、每页最多 30 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 user_id、nickname、url、avatar_url、follower_count、like_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 音乐搜索
music_search每千次 $8音乐搜索:返回列表,每次一页、固定 10 条(最后一页可能更少),要更多就把响应顶层的 next_page_token 作为 page_token 再调;limit 照收但不起作用;主要字段 id、url、title、author_name、duration_seconds、duration_sec。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 搜索联想词
search_suggest每千次 $8搜索联想词:返回列表,默认 10 条、单次最多 10 条;主要字段 rank、keyword、platform。 - 热点宝上升热点榜
billboard_rise_list每千次 $0.81热点宝上升热点榜:返回列表,每次一页、固定 50 条(最后一页可能更少),要更多就把响应顶层的 next_page_token 作为 page_token 再调;limit 照收但不起作用;主要字段 rank、rank_change、title、topic_id、hot_value、video_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 热点宝挑战热榜
billboard_challenge_hot每千次 $0.81热点宝挑战热榜:返回列表,默认 50 条、单次最多 50 条(传更大的数按 50 条返回);主要字段 rank、title、topic_id、hot_value、video_count、created_at。 - 热点宝话题热榜
billboard_topic_hot每千次 $0.81热点宝话题热榜:返回列表,每次一页、固定 50 条(最后一页可能更少),要更多就把响应顶层的 next_page_token 作为 page_token 再调;limit 照收但不起作用;主要字段 rank、hashtag_id、hashtag_name、hot_value、total_view_count、total_video_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 音乐详情
music_detail每千次 $0.81音乐详情:返回单个对象;主要字段 id、url、title、author_name、duration_seconds、duration_sec。 - 星图达人转化能力
xingtu_conversion_ability每千次 $1.6星图达人转化能力:返回单个对象;主要字段 creator_id、time_window、related_video_count、video_play_median、component_click_count_range、component_click_rate_range。 - 星图达人连接用户结构
xingtu_link_structure每千次 $16星图达人连接用户结构:返回单个对象;主要字段 creator_id、link_type、total_user_count、total_rank_top_percent、levels、platform。 - 星图达人推荐视频
xingtu_recommended_videos每千次 $1.6星图达人推荐视频:返回单个对象;主要字段 creator_id、signature_videos、latest_videos、top_xingtu_order_videos、top_personal_videos、platform。 - 星图达人连接用户来源
xingtu_touch_distribution每千次 $16星图达人连接用户来源:返回单个对象;主要字段 creator_id、categories、platform。 - 星图达人视频表现
xingtu_video_performance每千次 $16星图达人视频表现:返回单个对象;主要字段 creator_id、personal_videos、xingtu_videos、latest_videos、latest_xingtu_videos、platform。 - 批量查作品
posts_batch每千次 $0.56批量查作品:返回列表;主要字段 id、url、text、media_type、video_url、like_count。 - 批量查作者
profiles_batch每千次 $0.56批量查作者:返回列表;主要字段 user_id、douyin_id、nickname、bio、url、follower_count。 - 作品下载链接
media_links每千次 $0.56作品下载链接:返回列表;主要字段 id、url、media_type、video_url、video_url_expires_at、video_width。 - 相关推荐作品
related_posts每千次 $0.56相关推荐作品:返回列表;主要字段 id、url、text、media_type、video_url、like_count。 - 作品数据历史
post_history每千次 $0.79作品数据历史:返回列表;主要字段 video_id、captured_at、like_count、comment_count、share_count、collect_count。 - 用某段音乐的作品
music_posts每千次 $0.79用某段音乐的作品:返回列表;主要字段 id、url、text、media_type、video_url、like_count。 - 链接识别
resolve_links每千次 $0.79链接识别:返回列表;主要字段 matched_text、match_type、resource_type、resource_id、handle、url。 - 热榜历史
trending_history每千次 $0.79热榜历史:返回列表;主要字段 keyword、board、first_seen_at、last_seen_at、snapshot_count、best_rank。 - 作者的合集
user_mixes每千次 $0.79作者的合集:返回列表,每次一页、每页最多 20 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 mix_id、name、description、url、cover_image_url、author_id。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 合集里的作品
mix_posts每千次 $0.79合集里的作品:返回列表,每次一页、每页最多 15 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、video_url、like_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 作者一览
user_overview每千次 $1.6作者一览:返回单个对象;主要字段 user_id、douyin_id、nickname、bio、url、follower_count。 - 直播间
live_room每千次 $0.79直播间:返回单个对象;主要字段 room_id、live_id、title、is_live、url、cover_image_url。 - 推荐流
feed每千次 $0.56推荐流:返回列表,每次一页、每页最多 20 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、video_url、like_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 短剧频道
series_feed每千次 $0.56短剧频道:返回列表,每次一页、每页最多 16 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 series_id、name、description、url、cover_image_url、genres。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 短剧分集
series_posts每千次 $0.79短剧分集:返回列表,每次一页、每页最多 20 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 id、url、text、media_type、video_url、like_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 作者的短剧
user_series每千次 $0.79作者的短剧:返回列表,每次一页、每页最多 20 条,条数不固定(短页不代表到底),要更多就把响应顶层的 next_page_token 作为 page_token 再调,没有 next_page_token 才是到底;limit 照收但不起作用;主要字段 series_id、name、description、url、cover_image_url、genres。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 弹幕
danmaku每千次 $0.56弹幕:返回列表;主要字段 id、text、video_id、video_time、video_time_seconds、like_count。支持翻页:把响应里的 next_page_token 作为 page_token 传回拿下一页,其他参数不变,每页算一次调用。 - 短剧详情
series_detail每千次 $0.79短剧详情:返回单个对象;主要字段 series_id、name、description、url、cover_image_url、genres。 - 合集详情
mix_detail每千次 $0.56合集详情:返回单个对象;主要字段 mix_id、name、description、url、cover_image_url、episode_count。 - 直播场次详情
live_session每千次 $0.79直播场次详情:返回单个对象;主要字段 room_id、live_id、title、is_live、url、cover_image_url。 - 主播直播状态
user_live每千次 $0.79主播直播状态:返回单个对象;主要字段 room_id、live_id、title、is_live、url、cover_image_url。 - 按数字 UID 查主页
profile_by_id每千次 $0.56按数字 UID 查主页:返回单个对象;主要字段 user_id、douyin_id、nickname、bio、url、follower_count。