# 抖音 热榜 API (douyin.trending)

- Canonical page: https://everyinfra.com/douyin-api/trending
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "douyin", "action": "trending", "params": {...}}
- Price: $0.000556 per call ($0.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 60 per call
- Mode: sync; add "mode": "async" for slow tasks

抖音热榜按榜单读取当前的热点词条：排名、热点词、热度值、相关视频数、所属榜单和封面图，抖音给出时还有热点事件时间、历史最高名次、相关图文数和直播间数。它回答「抖音上此刻大家在看什么」，适合做选题、追热点、品牌舆情预警和内容排期。

用 `boards` 选榜单：`hotspot` 热点榜、`seeding` 种草榜、`entertainment` 娱乐榜、`social` 社会榜、`challenge` 挑战榜，可以传一个或多个，不传就是热点榜，不需要关键词。`hot_value` 是抖音自己的热度指标，只在同一榜单里可比，热点榜的行上常常为空；`rank` 是读取那一刻的名次，要看走势请定时调用，按时间把每次结果存下来。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=douyin&action=trending

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| boards | not declared | no | not declared | 热榜类型，可传单个字符串或字符串数组同时查询多个榜单：hotspot 热点榜、seeding 种草榜、entertainment 娱乐榜、social 社会榜、challenge 挑战榜。不传或传空数组时默认查询 hotspot。 |
| limit | integer (1–60) | no | 20 | 这次调用最多返回的条数，整数，1–60；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| rank | 名次（从 1 开始）：trending 是热榜排名，xingtu_creator_rankings 是星图榜单里的名次，billboard_search_hot 是搜索热榜名次，search_suggest 是联想词在抖音搜索框里的顺序；billboard_rise_list、billboard_challenge_hot、billboard_topic_hot 是热点宝榜单名次（翻页接着往下数）。 |
| keyword | 关键词：trending 是热点词，billboard_search_hot 是上榜的搜索词，search_suggest 是抖音给出的联想搜索词。 |
| hot_value | 热度值，抖音自有指标，只在同一榜单、同一时间窗内可比：trending 是热榜热度（热点榜 hotspot 的行上常常为空）；热点宝视频榜（billboard_video_hot 等）是榜单热度分，行按它从高到低排；billboard_search_hot 是这个词在时间窗里的搜索热度；billboard_rise_list、billboard_challenge_hot 是热点热度，billboard_topic_hot 是话题在时间窗里的热度分。 |
| video_count | 视频数：profile、billboard_account_search 是账号的作品数，trending、billboard_rise_list、billboard_challenge_hot 是这个热点下的相关视频数。 |
| board | 所属榜单。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| event_time | 热点事件时间。 |
| sentence_id | 热点词 ID（trending）。 |
| group_id | 热点事件 ID（trending）；部分热点为空。 |
| label | 热榜角标代码（trending，数字，如热、新、爆）；0 表示没有角标。 |
| word_type | 热点词类型代码（trending，数字）。 |
| article_count | 热点下的相关图文数（trending）。 |
| is_pinned | 是否置顶（作品行：作者主页置顶作品；trending：榜单置顶词）。 |
| max_rank | 该热点在榜单上的历史最高名次（trending）。 |
| live_room_count | 热点下的相关直播间数（trending）。 |
| topic_view_count | 热点的浏览量（trending）；与 hot_value 是两个指标。null 表示没给，不等于 0。 |
| sentence_tag | 热点分类代码（trending，数字）；同一代码是同一类热点。 |
| label_icon_url | 热榜角标图链接（trending，如「热」「新」）；文字代码见 label。 |
| related_music_id | 热点关联的背景音乐 ID（trending，部分热点有）。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
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": "trending",
  "params": {}
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "douyin",
        "action": "trending",
        "params": {},
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "douyin",
  "action": "trending",
  "results": [
    {
      "rank": 1,
      "keyword": "渡船之上 信仰如磐",
      "video_count": 1,
      "board": "hotspot",
      "event_time": "2026-10-25 02:34:26",
      "sentence_id": "2711825",
      "label": 0,
      "word_type": 14,
      "is_pinned": true,
      "platform": "douyin"
    },
    {
      "rank": 2,
      "keyword": "中超成都蓉城0:1大连英博",
      "hot_value": 11367047,
      "video_count": 12,
      "board": "hotspot",
      "image_url": "https://p5-ex-gddgtc-sign.douyinpic.com/tos-cn-i-dy/782a03e57ee24eb7b51eac3c0ee20e5e~noop.jpeg?lk3s=bfd515bb&x-expires=1792886400&x-signature=TFoV42oMHa89HkqBwV3AKbDx6sI%3D&from=3218412987",
      "event_time": "2026-10-24T07:01:06.000Z",
      "sentence_id": "2711309",
      "group_id": "7699487992537503010",
      "label": 3,
      "word_type": 1,
      "article_count": 0,
      "is_pinned": false,
      "max_rank": 1,
      "live_room_count": 0,
      "topic_view_count": 59034929,
      "sentence_tag": 5000,
      "label_icon_url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vjl_avo_upfbvk/ljhwZthlaukjlkulzlp/hotspot_detail_page/3.png",
      "platform": "douyin"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 一次能查几个榜单？

`boards` 可以传单个字符串，也可以传数组同时查多个榜单；每一行的 `board` 标明它来自哪个榜单，合并分析前先按它分组。不传或传空数组时只查 `hotspot` 热点榜。

### `hot_value` 能跨榜单比较吗？

不能。它是抖音自有的热度指标，只在同一个榜单内部有比较意义，热点榜的行上还经常为空。跨榜单比较请用 `rank`，或者看 `video_count`、`article_count` 这类相关内容的数量。

### 怎么追踪一个热点的走势？

定时调用，把每次结果连同调用时间存下来，再用 `sentence_id` 把同一个热点词在不同时刻的行串起来，就能画出名次变化。`max_rank` 是它在榜单上到过的最高名次；`is_pinned` 为真表示榜单置顶词，做排名分析时可以单独处理。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=douyin
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md