视频号号内搜索 API
在已知的一个视频号里按关键词搜作品,可翻页;每条返回标题和 export_id。不是全站搜索。
在已经知道的一个视频号里面按关键词搜作品。传入 finder username 作为 channel_id,以及 keyword,可用 cursor 翻页;返回 items,每条含标题、export_id、封面、时长和昵称。
这不是搜一搜全站,也不能按昵称搜视频号账号。export_id 会过期,要数字作品 ID 时请马上用视频号作品ID转换,再查标题、互动或评论。
请求地址 POST https://www.xmedi.cn/api/v1/wechat/channels/feeds/search。调用成功才扣费,参数错误、平台侧失败或超时不扣费。
成功响应的 meta 含数据血缘,说明见 鉴权与计费。
适用场景
- 账号内容检索:已知某个视频号,按产品名或话题在它已发布的作品里查找相关视频。
- 竞品内容盘点:对竞品视频号按关键词翻页,整理提到特定产品的作品标题。
- 评论采集前置:搜到作品后把 export_id 转成作品 ID,再拉取一级评论。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
channel_id |
string | 是 | 视频号 finder username,必填,形如 v2_…@finder。sph 开头的视频号 ID 不能直接用,请先用视频号账号解析。 |
cursor |
string | 否 | 翻页游标,取上一页返回的 next_cursor;首页留空。只改页码不会翻到下一页。 |
keyword |
string | 是 | 在该视频号内搜索的关键词,必填,1 到 100 字。 |
page |
integer | 否 | 页码,从 1 起。是否还有下一页以 has_more 和 next_cursor 为准。 |
page_size |
integer | 否 | 每页条数。实际一页大约 20 条,以返回为准。 |
返回 data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
has_more | boolean | 是否还有下一页。为 true 时,把 next_cursor 填回下次请求的 cursor。 |
items | array<object> | 作品列表。每项含 title 标题、export_id、cover_url 封面、duration 时长(秒)和 nickname 昵称。没有相关作品时为空数组。 |
next_cursor | string | 下一页游标。has_more 为 true 时,下次请求把它填回 cursor。 |
page | number | 当前页码,与请求中的 page 对应。 |
page_size | number | 本页的每页条数。 |
total | number | 本次结果条数或总数,以返回为准;是否继续翻页以 has_more 为准。 |
调用示例
curl -X POST https://www.xmedi.cn/api/v1/wechat/channels/feeds/search \
-H "X-XMEDI-Key: xm_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"channel_id":"v2_060000231003b20faec8c6e4811dc1d4c602ee30b0771bbcf220c67926bb76ab7702ac335a53@finder","keyword":"人民日报","page":1}'
返回示例
以下为 data 的字段结构示意,实际取值以调用结果为准。
{
"has_more": false,
"items": [
{
"cover_url": "https://example.com/cover.jpg",
"duration": 15,
"export_id": "export/exampleExportId",
"nickname": "示例视频号",
"title": "示例作品标题"
}
],
"next_cursor": "",
"page": 1,
"page_size": 20,
"total": 1
}
注意事项
- channel_id 必须是 finder username。手里只有 sph 开头的视频号 ID 时,先用视频号账号解析。
- export_id 会过期。需要长期保存或继续查评论时,马上用视频号作品ID转换得到作品 ID。
- 翻页把上一页的 next_cursor 原样填回 cursor,直到 has_more 为 false。
- 本接口只在一个已知视频号内搜索。全站按关键词找作品用搜一搜视频号视频。
常见错误码
| code | error_code | 含义与处理 |
|---|---|---|
| 40001 | VALIDATION_ERROR | 参数校验失败,按返回提示修改请求,不扣费 |
| 40100 | UNAUTHORIZED | API Key 缺失、错误或已吊销,到控制台检查 Key |
| 40200 | INSUFFICIENT_BALANCE | 余额不足,充值后重试 |
| 42900 | RATE_LIMITED | 超过每分钟 60 次上限,稍后重试 |
| 50000 | INTERNAL_ERROR | 服务异常,可稍后重试,不扣费 |
| 50300 | NOT_AVAILABLE | 接口暂不可用,不扣费 |
常见问题
- 和搜一搜视频号视频有什么区别?
- 本接口只搜一个已经知道的视频号,必须传 finder username。搜一搜视频号视频按关键词在全站找作品,不需要先知道是哪个号。
- 能按昵称搜视频号账号吗?
- 不能。本接口搜的是该号里的作品。要先拿到 finder username,可以用视频号账号解析。
- 搜不到作品会扣费吗?
- 调用成功才扣费,参数错误、平台侧失败或超时不扣费;成功但结果为空也算一次成功调用。
相关接口
需要接入这个接口?
免费注册
注册后创建 API Key,或留下联系方式获取方案