# Twitch 热门直播 API (twitch.top_streams)

- Canonical page: [https://everyinfra.com/twitch-api/top_streams](https://everyinfra.com/twitch-api/top_streams?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "twitch", "action": "top_streams", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 10, max 30 per call
- Mode: sync; add "mode": "async" for slow tasks

Twitch 热门直播不需要参数，返回全站当前的热门直播，每场带直播 ID、主播、粉丝数、标题、正在播的游戏或分类 `game`、观看人数 `viewer_count` 和开播时间。它回答「Twitch 上现在最火的直播是什么」，适合行业报道、品牌观察流量风向，以及发现正在升温的游戏。

想看某个游戏或分类下有谁在播，用直播列表并指定分类名；这里给的是跨分类的总榜。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| limit | integer (1–30) | no | 10 | 这次调用最多返回的条数，整数，1–30；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| stream_id | 本场直播 ID。 |
| username | 用户名（@handle）。 |
| display_name | 显示名，可能与 username 不同。 |
| follower_count | 粉丝数。null 表示不公开，不等于 0。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| viewer_count | 观看人数。 |
| game | 游戏名。 |
| started_at | 开始时间。 |
| url | 该记录在原平台上的可访问链接。 |
| avatar_url | 头像图片链接。部分平台给的是带尺寸参数的 CDN 链接，可能有时效。 |
| 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": "twitch",
  "action": "top_streams",
  "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": "twitch",
        "action": "top_streams",
        "params": {},
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

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

```text
{
  "id": "req_…",
  "platform": "twitch",
  "action": "top_streams",
  "results": [
    {
      "stream_id": "•••",
      "username": "•••",
      "display_name": "•••",
      "follower_count": 580684,
      "title": "EG FNS | GE vs VIT - VCT Champions Group Stage #VCTWatchparty | !vote !inzone !voice",
      "viewer_count": 32957,
      "game": "VALORANT",
      "started_at": "2026-09-26T08:16:56+00:00",
      "url": "https://www.twitch.tv/gofns",
      "avatar_url": "https://static-cdn.jtvnw.net/•••",
      "platform": "twitch"
    },
    {
      "stream_id": "•••",
      "username": "•••",
      "display_name": "•••",
      "follower_count": 4879882,
      "title": "GE vs. VIT — VALORANT Champions Shanghai — Group Stage",
      "viewer_count": 29113,
      "game": "VALORANT",
      "started_at": "2026-09-26T08:29:35+00:00",
      "url": "https://www.twitch.tv/valorant",
      "avatar_url": "https://static-cdn.jtvnw.net/•••",
      "platform": "twitch"
    }
  ],
  "count": 10,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 怎么发现正在升温的游戏？

定时读热门直播，按 `game` 统计每个分类占了几个席位、观看人数合计多少。某个游戏的席位和观看数在几天内持续增加，就是正在升温的信号，再去查原因。

### 热门直播和直播列表有什么不同？

热门直播不用传参，看的是全站；直播列表要传分类名，只看这个分类下的直播。先用热门直播从 `game` 里找到热门分类，再用直播列表深入其中，是常见的用法。

### `started_at` 有什么用？

它是这场直播的开播时间。用读取时间减去 `started_at`，就是已经播了多久；结合 `viewer_count`，可以看出一场直播是刚开播就冲上来，还是播了很久才积累起人气。

## Also

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