# Twitch 主页或对象详情 API (twitch.profile)

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

Twitch 主页或对象详情按 `username` 读取一个频道：显示名、简介、粉丝数和创建时间，是否 Partner 或 Affiliate，在播状态及当前标题、游戏、观看人数和开播时间，以及最近一次直播的标题、游戏和时间，默认还附带近期录像和精选短片。它回答「这个主播是谁、还播不播、分量如何」，适合品牌赞助方、经纪机构和电竞战队在合作前筛选主播。

直播字段只反映读取那一刻，判断停更看 `last_broadcast_at`。不需要录像或短片时，把 `include_videos` 或 `include_clips` 设为布尔值 false，不能写成字符串。附带短片的时间窗和 Twitch 直播切片不同，后者可以自选时段。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| username | not declared | yes | not declared | profile / clips 的 Twitch 频道登录短名，可带 @，不解析完整 twitch.tv URL。 |
| include_clips | not declared | no | not declared | profile 是否附带精选短片信息，布尔值，默认 true；与独立 clips 接口的时间窗不同。 |
| include_videos | not declared | no | not declared | profile 是否附带近期录像信息，布尔值，默认 true；设 false 可不读取此部分，不能传字符串 "false"。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| user_id | 用户在原平台的唯一 ID。 |
| username | 用户名（@handle）。 |
| display_name | 显示名，可能与 username 不同。 |
| bio | 个人简介，账号自己填写的文本。可能含换行和 emoji。 |
| url | 该记录在原平台上的可访问链接。 |
| avatar_url | 头像图片链接。部分平台给的是带尺寸参数的 CDN 链接，可能有时效。 |
| banner_url | 频道横幅。 |
| follower_count | 粉丝数。null 表示不公开，不等于 0。 |
| is_partner | 是否为 Twitch 合作伙伴（最高档认证）。 |
| is_affiliate | 是否为 Affiliate（初级变现资格，低于 Partner 一档）。 |
| is_live | 当前是否在播。 |
| current_viewers | 当前观看人数。 |
| stream_title | 直播标题。 |
| current_game | 当前直播的游戏。 |
| stream_started_at | 本场开播时间。 |
| last_broadcast_title | 最近直播标题。 |
| last_broadcast_game | 最近直播的游戏。 |
| last_broadcast_at | 最近一次开播时间。判断主播是否活跃/停更的关键字段。 |
| created_at | 创建时间，格式同 posted_at。 |
| recent_videos | 最近发布的视频列表，每项是一个视频（标题、链接、播放数、时长等）；没有时不出现这个字段。 |
| top_clips | 频道的热门剪辑，每项含标题、链接、播放数、时长、游戏和剪辑者；没有时不出现这个字段。 |
| 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": "profile",
  "params": {
    "username": "shroud"
  }
}'
```

```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": "profile",
        "params": {
            "username": "shroud",
        },
    },
    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. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "twitch",
  "action": "profile",
  "results": {
    "user_id": "•••",
    "username": "shroud",
    "display_name": "shroud",
    "bio": "I'm back baby",
    "url": "https://www.twitch.tv/shroud",
    "avatar_url": "https://static-cdn.jtvnw.net/•••",
    "banner_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dbee25e8-55b7-4565-87f0-e9d4661dcc66-profile_banner-480.jpeg",
    "follower_count": 11293129,
    "is_partner": true,
    "is_affiliate": false,
    "is_live": false,
    "last_broadcast_title": "we are SAVED!",
    "last_broadcast_game": "WARDOGS",
    "last_broadcast_at": "2026-09-26T04:34:47.953850+00:00",
    "created_at": "2012-11-03T15:50:32.878470+00:00",
    "recent_videos": [
      {
        "id": "•••",
        "title": "we are SAVED!",
        "url": "https://www.twitch.tv/videos/2883804788",
        "view_count": 2687,
        "duration_seconds": 35971,
        "game": "WARDOGS",
        "created_at": "2026-09-25T18:35:12+00:00"
      },
      {
        "id": "•••",
        "title": "surely were saved..?",
        "url": "https://www.twitch.tv/videos/2882888067",
        "view_count": 252586,
        "duration_seconds": 28465,
        "game": "WARDOGS",
        "created_at": "2026-09-24T17:23:48+00:00"
      },
      {
        "id": "•••",
        "title": "playing till we get ddosed",
        "url": "https://www.twitch.tv/videos/2882056326",
        "view_count": 194144,
        "duration_seconds": 21413,
        "game": "WARDOGS",
        "created_at": "2026-09-23T17:50:24+00:00"
      }
    ],
    "top_clips": [
      {
        "id": "•••",
        "title": "wtf !!",
        "url": "https://www.twitch.tv/shroud/clip/SeductiveFurryPotCmonBruh--v2IUlxXQxpw8YUZ",
        "view_count": 2230,
        "duration_seconds": 39,
        "game": "Active Matter",
        "curator_username": "•••",
        "curator_name": "Taisseeer",
        "thumbnail_url": "https://static-cdn.jtvnw.net/twitch-video-assets/twitch-vap-video-assets-prod-us-west-2/f4e752a4-c4c1-42b9-a4a1-a7a28106a717/landscape/thumb/thumb-0000000000-1920x1080.jpg",
        "created_at": "2026-09-19T22:08:27+00:00"
      },
      {
        "id": "•••",
        "title": "Pilot Kill",
        "url": "https://www.twitch.tv/shroud/clip/BreakableAssiduousBulgogiUnSane-oAR-wxU-JuRMLxdl",
        "view_count": 1042,
        "duration_seconds": 21,
        "game": "WARDOGS",
        "curator_username": "•••",
        "curator_name": "primo11119",
        "thumbnail_url": "https://static-cdn.jtvnw.net/twitch-video-assets/twitch-vap-video-assets-prod-us-west-2/f45445b1-9e8c-4cfd-88b0-d6cbe5d00b61/landscape/thumb/thumb-0000000000-1920x1080.jpg",
        "created_at": "2026-09-21T18:00:52+00:00"
      },
      {
        "id": "•••",
        "title": "next level bush camper",
        "url": "https://www.twitch.tv/shroud/clip/VainCloudyHawkRiPepperonis-imxaRCvFhJlfVtvo",
        "view_count": 784,
        "duration_seconds": 60,
        "game": "WARDOGS",
        "curator_username": "•••",
        "curator_name": "Plot_C4",
        "thumbnail_url": "https://static-cdn.jtvnw.net/twitch-video-assets/twitch-vap-video-assets-prod-us-west-2/84be87c7-bea1-4ed5-b709-8fdcc5482baa/landscape/thumb/thumb-0000000000-1920x1080.jpg",
        "created_at": "2026-09-20T17:44:19+00:00"
      }
    ],
    "platform": "twitch"
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `username` 填什么？

填频道的登录名，也就是 twitch.tv/ 后面那一段，例如 shroud，开头可以带 @；完整的 twitch.tv 链接不会被解析，只传名字。频道上显示的名字可能和登录名不同：`username` 是登录名，`display_name` 是显示名。

### Partner 和 Affiliate 有什么区别？

两者都是 Twitch 的变现资格。`is_affiliate` 标出初级的 Affiliate，`is_partner` 标出 Twitch 合作伙伴，比 Affiliate 高一档，是最高一级。洽谈赞助前，可以用它快速判断一个频道的成熟程度。

### 怎么判断主播是不是还在活跃？

看 `last_broadcast_at`，它是最近一次开播的时间，再结合 `last_broadcast_title` 和 `last_broadcast_game`。`is_live`、`current_viewers` 和 `stream_title` 只反映读取那一刻，现在没在播的频道也可能一直规律直播。

## 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
