---
title: "视频号号内搜索/Search Videos Within a WeChat Channel"
method: POST
path: "/api/v1/wechat_channels/v2/fetch_search_channel_videos"
tags: ["WeChat-Channels-V2-API"]
---

# 视频号号内搜索/Search Videos Within a WeChat Channel

`POST /api/v1/wechat_channels/v2/fetch_search_channel_videos`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/wechat_channels/v2/fetch_search_channel_videos`
- Auth: HTTP bearer

# [中文]
### 用途:
- 号内搜：在指定创作者的视频号内，按关键词搜索其发布的视频（只在**该号内部**检索）。
- **单页返回**：一次调用取一页。`continue_flag=1` 且 `next_cursor` 非空时，把 `next_cursor` **原样回传** `cursor` 参数取下一页。
- ⚠️ `next_cursor` 是**不透明字符串**，请勿解析或拼接 —— 上游已将其密封（旧版明文里带有检索会话等内部状态）。
- 价格：0.01$/次
- ⏱️ 由于微信服务器原因，本接口响应较慢，请将客户端请求超时（timeout）设置为 30 秒；timeout 设置过小会造成已扣费但收不到响应的情况。
- ⚠️ 大整数 ID 精度：响应中的 `doc_id` 等为 64 位大整数，超出 JavaScript 安全整数范围（2^53-1）。请始终以**字符串**方式接收 / 传递这类 ID（解析 JSON 用 json-bigint 或按文本取值），勿让其经过 JS `Number`。Swagger UI 文档页对超大整数会末位舍入显示，属正常现象，不影响接口实际返回的数据。
### 参数:
- cursor: 可选。翻页游标，首页留空；翻页时原样回传上一页响应的 `next_cursor`。
- username: 创作者 finder username（`v2_…@finder` 格式）。示例 `v2_060000231003b20faec8c6e4811dc1d4c602ee30b0771bbcf220c67926bb76ab7702ac335a53@finder`（人民日报）。
- keyword: 在该号内搜索的关键词（去空白后 1-100 字）。示例 `新闻`。
- raw: 可选，默认 True。True=原始搜索响应；False=精简解析结构。
### 返回:
- 号内搜索命中列表

### 响应结构与 JSON Path:
#### `raw=false`（精简，snake_case）:
- `$.data.username` / `$.data.keyword` —— 回显入参
- `$.data.count` —— 本页命中数（示例 20）
- `$.data.items[]` —— 命中数组，逐个（N 为下标）:
    - `$.data.items[N].type` —— 结果类型（如 `video`）
    - `$.data.items[N].doc_id` —— 文档 id
    - `$.data.items[N].title` —— 标题（已去搜索高亮标记）
    - `$.data.items[N].desc` / `.thumb_url` / `.username` / `.nickname` —— 简介 / 缩略图 / 作者（**部分项可能为 null**）
- `$.data.continue_flag` —— 是否还有更多（1=有）
- `$.data.next_cursor` —— 翻页游标（不透明字符串，原样回传 `cursor` 参数取下一页；没有下一页时为 `null`）
#### `raw=true`（完整原始响应，camelCase）:
- `$.data.query` → `keyword`；`$.data.offset` —— 下一页偏移（示例 20）
- `$.data.data[]` —— 结果分组数组；命中项嵌在 `$.data.data[N].subBoxes[M].items[]`（亦可能在 `$.data.data[N].items[]`），由精简层拍平成 `items[]`
- `$.data.continueFlag` → `continue_flag`
- `$.data.next_cursor` —— 同 `raw=false`：不透明翻页游标（顶层注入）。旧版这里是明文的 `searchID` 等检索上下文，上游密封后已不再下发

### 提示:
- 命中视频要拿媒体（下载地址 / decode_key）：本接口不直接给 `media`，请用命中项走 `fetch_video_detail` 取 `media`（`url` / `url_token` / `decode_key`），链路与解密说明见 `fetch_video_detail` 文档。

# [English]
### Purpose:
- In-channel search: search a creator's published videos by keyword **within that channel only**.
- **Single page per call.** When `continue_flag=1` and `next_cursor` is non-empty, pass `next_cursor` back verbatim as the `cursor` parameter to get the next page.
- `next_cursor` is an **opaque string** — do not parse or concatenate it. Upstream seals it (older versions leaked search-session state in plaintext).
- Price: $0.01 per request
- ⏱️ Due to WeChat server latency, this endpoint responds slowly; please set your client request timeout to 30 seconds — a timeout that is too small may result in being billed without receiving the response.
- ⚠️ Large-integer ID precision: IDs such as `doc_id` in the response are 64-bit big integers beyond JavaScript's safe-integer range (2^53-1). Always receive / pass such IDs as **strings** (parse JSON with json-bigint or read them as text), never through JS `Number`. Swagger UI rounds the trailing digits of huge integers in its docs view — this is expected and does not affect the actual data returned by the API.
### Parameters:
- username: Creator finder username (`v2_…@finder` format). E.g. `v2_060000231003b20faec8c6e4811dc1d4c602ee30b0771bbcf220c67926bb76ab7702ac335a53@finder` (People's Daily).
- keyword: Keyword to search within the channel (1-100 chars after trimming). E.g. `新闻`.
- raw: Optional, default True. True=raw search response; False=simplified parsed structure.
### Return:
- In-channel search hit list

### Response structure & JSON Path:
#### `raw=false` (simplified, snake_case):
- `$.data.username` / `$.data.keyword` — input echo
- `$.data.count` — hits on this page (e.g. 20)
- `$.data.items[]` — hit array, per item (N is the index):
    - `$.data.items[N].type` — result type (e.g. `video`)
    - `$.data.items[N].doc_id` — document id
    - `$.data.items[N].title` — title (search highlight markers stripped)
    - `$.data.items[N].desc` / `.thumb_url` / `.username` / `.nickname` — description / thumbnail / author (**may be null for some items**)
- `$.data.continue_flag` — has more (1=yes)
- `$.data.next_cursor` — pagination cursor (opaque string; pass it back as `cursor` for the next page, `null` when there is no next page)
#### `raw=true` (full raw response, camelCase):
- `$.data.query` → `keyword`; `$.data.offset` — next page offset (e.g. 20)
- `$.data.data[]` — result group array; hit items are nested at `$.data.data[N].subBoxes[M].items[]` (or possibly `$.data.data[N].items[]`), flattened into `items[]` by the simplified layer
- `$.data.continueFlag` → `continue_flag`
- `$.data.next_cursor` — same as `raw=false`: opaque pagination cursor (injected at top level). Older versions exposed `searchID` and other search context in plaintext; upstream no longer returns it

### Tip:
- To get media (download address / decode_key) of a hit video: this endpoint does not return `media` directly; feed the hit into `fetch_video_detail` to get `media` (`url` / `url_token` / `decode_key`). See `fetch_video_detail` docs for the chain and decryption notes.

## Request body

- FetchSearchChannelVideosRequest
  - `username` string, required: 创作者 finder username（v2_…@finder 格式）/Creator finder username (v2_…@finder format)
  - `keyword` string, required: 在该号内搜索的关键词（1-100 字）/Keyword to search within this channel (1-100 chars)
  - `cursor` string, nullable: 翻页游标：首页留空；翻页时原样回传上一页响应的 next_cursor（不透明字符串，勿解析或拼接）/Pagination cursor: leave empty for the first page; pass back the previous response's next_cursor verbatim (opaque string, do not parse or concatenate)
  - `raw` boolean: True=原始响应；False=精简解析结构/True=raw response; False=simplified parsed structure

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-08** `485e774cb449`: 1 info
  - added the new optional request property `cursor`
- **2026-09-01** `50f9ec6e1cd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/wechat_channels/v2/fetch_search_channel_videos/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)