知乎专家发现 API:搜索候选或读取已知资料
通过一次知乎用户搜索或资料请求获取候选,保留准确 URL token 和未知字段,不把粉丝数量当成专业资格。

搜出二十个名字相近的知乎账号,并没有回答“你要找谁”。做知乎专家发现 API 接入时,先把选择权留下来:这一版只读取一页关键词候选,或者读取你已经选定的资料页。它不会自动挑第一名、拉回答、给专家打分,也不会把粉丝数量当作专业资格。
2026 年 11 月 8 日的修订核对了当前契约,并用公开保存样本做离线回放,没有新增业务调用。9 月 27 日原稿的三步设计已归档;下文 10 月 7 日的搜索和资料样本各自独立,不能拼成一次新验证的链路。其他能力见知乎 API 总览。
先说结论
- 找候选选
zhihu/web/user-search-v3;已有资料页标识选zhihu/web/user-info,每次只执行一个任务。- 搜索的 limit、offset 都是字符串;资料接口需要
object.url_token,不是命中数字 ID、内部哈希或昵称。- 只读完成态信封的
outputs[0].data。搜索里面是 data 数组,资料则是平铺对象。- 计数和徽章是账号观察值,不等于专家认证、实际触达人数或联系许可。
保留的封面表达旧版“搜索→资料→回答→agent”概念。AI_Scholar、数字、徽章和回答卡片均为示意,不是客户案例、实测指标或本例执行四步的证据。
知乎专家发现 API:先选一个任务
| 手里的输入 | 选用接口 | 本例请求 |
|---|---|---|
| 话题或账号关键词 | Web User Search V3 | keyword,显式 limit "5"、offset "0" |
| 已选定的资料页 slug | Web User Info | user_url_token,例如 ming-he-43-93 |
搜索只有 keyword 必填。当前 schema 的 limit 默认是字符串 "25",offset 默认 "0",没有声明数值上下界。这里选五是为了请求较小的第一页,不保证一定返回五个账号。公开保存请求只传了 deepseek 关键词;它的二十条结果不是本例 limit 五已经运行的证据。
资料接口要求一个字符串标识。注意保留路由里的 web/,其他同名接口可能有不同参数和价格。从已知 /people/ 地址取 slug,或由人明确选择搜索里的 token;不要让 agent 为了补参数就自动采用第一个同名账号。
历史 User Search V3 参数页,显示必填 keyword、可选字符串 limit/offset 与 25/0 默认值。右侧是占位响应信封,不是搜索与资料串联执行,也不是二十人结果。
已有 key、已连接 agent、新项目怎么接
已有 key 就复用本地环境或密钥管理器中的 SANDBASE_API_KEY。Agent 已接入时,给它所选端点、关键词或 token,以及“只调用一次”的范围即可,不必重新申请 key。新项目可以把 setup Skill 和 Markdown quickstart 交给 agent;账号操作见快速开始。
可直接描述:“读 setup Skill,使用现有本地 key,获取 deepseek 的一页知乎账号候选,保留准确 token 和实际存在的计数,报告跳过记录数,随后停止,不选人、不拉回答。”若已有资料 token,就明确换成单次资料任务。不要把密钥粘进指令、文章、工单或聊天记录。
本地执行 python3 -m pip install requests,把下面代码存成文件,并在文件外设置环境变量。这里向 SandBase 鉴权;两个所选接口没有要求传知乎密码或 OAuth 凭据,这也不表示能读取私密内容。
一次请求,明确停止
示例调用 Model API 的 POST /v1/api/zhihu/web/<route>,不是目录 GET,也不是 /v1/run。两个业务参考没有 code、status、success 字段,不能套用其他平台的 code 等于零判定。外层 SandBase 完成状态仍然必须检查。
import os
import requests
def first_request(task, value):
if not isinstance(value, str) or not value.strip():
raise ValueError("Supply a nonblank keyword or an explicitly selected token")
if task == "search":
route = "user-search-v3"
params = {"keyword": value, "limit": "5", "offset": "0"}
elif task == "profile":
if any(c.isspace() or c in "/?#" for c in value):
raise ValueError("Use the profile slug, not a URL or display name")
route = "user-info"
params = {"user_url_token": value}
else:
raise ValueError("Choose search or profile")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
"https://api.sandbase.ai/v1/api/zhihu/web/" + route,
headers={"Authorization": "Bearer " + key},
json=params, timeout=(10, 90), allow_redirects=False,
)
except requests.RequestException:
raise RuntimeError("Request failed; no automatic retry was made") from None
if not 200 <= response.status_code < 300:
raise RuntimeError("HTTP request rejected: " + str(response.status_code))
try:
body = response.json()
except ValueError:
raise RuntimeError("Response was not valid JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0].data")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Expected a business object at outputs[0].data")
# These references have no business code/status/success field.
if task == "search":
rows = payload.get("data")
if not isinstance(rows, list):
raise RuntimeError("Search data must be an array")
people, skipped = [], 0
for row in rows:
if not isinstance(row, dict):
raise RuntimeError("Malformed search row")
user = row.get("object")
if user is not None and not isinstance(user, dict):
raise RuntimeError("Malformed search object")
if not user or user.get("type") != "people":
skipped += 1
continue
token = user.get("url_token")
if not isinstance(token, str) or not token.strip():
skipped += 1
continue
people.append(user)
return {"payload": payload, "people": people, "skipped": skipped}
if payload.get("url_token") != value or not isinstance(payload.get("name"), str):
raise RuntimeError("Profile identity or flat reference shape did not match")
if not payload["name"].strip():
raise RuntimeError("Profile name is missing")
return {"payload": payload}
if __name__ == "__main__":
result = first_request("search", "deepseek")
print(len(result["people"]), "usable candidates; skipped", result["skipped"])要改成资料任务,替换末尾两行缩进代码为 result = first_request("profile", "ming-he-43-93") 和 print(result["payload"].get("name"), result["payload"].get("follower_count"))。不要在搜索后再追加调用。token 检查只是防空值和误粘完整 URL 的本地保护,不是所有上游标识符的完整规则。
返回的 people、skipped 是本地整理字段。非用户或无可用 token 的对象计入跳过数;标量行、标量 object 会报错。data 空数组可以正常返回,但不代表世上不存在合适专家。资料必须匹配所选 token 并具有非空名字,缺身份或只有错误信息的对象不能被当成空资料成功。可选字段的缺失、null、零保持原状。
代码不重试、不续页、不拉回答或头像,也不发消息。错误只暴露类别,不打印 key 或整段上游错误。重定向直接拒绝;超时仅表示客户端停止等待,不证明上游什么都没做,再次调用前应先检查账号记录。
读懂保存的搜索页
公开保存记录 3aae9ba3-8312-4f08-819d-2d8841824798 的时间为 2026-10-07T17:36:49.471Z,输入仅 {"keyword":"deepseek"}。完整捕获里有二十条 search_result,object.type 都是 people,且都有字符串 token;未来是否混入别的类型仍需逐行检查。下面只投影第一条的原有字段,省去头像、徽章元数据和不透明上下文:
{
"id": 4029889030,
"type": "search_result",
"hit_labels": null,
"object": {
"type": "people",
"id": "b2be5c4564dd15544180d35da0500188",
"url_token": "deepseek-75",
"name": "<em>DeepSeek</em>",
"headline": "",
"answer_count": 0,
"articles_count": 2,
"creation_count": 2,
"follower_count": 58778,
"follower_count_text": "5.8 万"
}
}一条结果里有三种身份。行 id 是搜索命中编号,object.id 是账号内部哈希,资料请求需要 object.url_token。昵称可能带 <em> 高亮,也可能多人同名。展示时按文本转义,或移除已知高亮格式,不要把任意 HTML 插入页面。
该条 follower_count 为 58778,显示值却是 5.8 万;保留数值与显示串,不用估算值覆盖原数。零回答、空简介、null 标签和缺字段也各有含义。候选表可以显示“未知”,不应默认填零后再排序。
另一份裁剪 README 的首项文章数、创作数为四和四,完整保存样本为二和二;README 的另一组数字是 1147、32、5788,保存的第二人却是 1119、31、5626。这些参考不能拼成增长曲线,creation_count 也不保证等于回答加文章。账号产出多不直接证明内容质量,更不能把粉丝数叫作实际触达人数。
下一页地址为什么不能直接拿来循环
保存页 paging.is_end 为 false,paging.next 指向上游地址,包含 limit=20、offset=20 和额外查询上下文。这与“默认 limit 25,所以总是返回二十五条”的推断不一致;一份样本无法解释省略参数后上游究竟采用了什么。
不能机械加二十或二十五,更不能带 SandBase bearer key 访问那个上游地址。search_hash_id、attached_info_bytes、会话参数,以及完整捕获中未解析的 ab_params: "$1d",都不是这个 schema 的请求字段。以后做续页,需单独确认返回信息如何映射回字符串 limit/offset、怎样保留相同关键词与结束条件,以及丢掉上下文是否改变结果。本轮没有验证续页。
这次保留分页元数据并停止。“观察到一页候选”是准确产物,“找全所有专家”没有证据。
已知资料 token:不要拼接两个独立样本
资料保存记录 efd5baa5-aefb-48e6-9013-9f66dddde8ee 的时间为 2026-10-07T17:36:12.157Z,输入 user_url_token: "ming-he-43-93"。这个 token 不在那二十个搜索候选中。以下原字段投影属于独立资料请求:
{
"url_token": "ming-he-43-93",
"type": "people",
"follower_count": 2830,
"follower_count_text": "2830",
"follower_count_num": "2830",
"follower_count_unit": "",
"answer_count": 9,
"articles_count": 87,
"ip_info": "IP 属地未知",
"allow_message": true,
"is_realname": true,
"is_org": false,
"org_verify_status": null,
"employments": []
}
历史 Web User Info 参数参考,展示 user_url_token 和外层信封。该路由的“User ID”标签实际应按资料 URL slug 使用;空对象示例不证明任何业务计数。
业务对象本身就是资料,不要再找 data.user。样本粉丝数 2830、回答九篇、文章八十七篇;显示串恰好也为 "2830",单位为空,但不能推论所有本地化显示值都可无损转整数。
IP 文本明确表示属地未知。空任职和徽章数组、null 组织认证或助手信息、未解释的性别数字码,都不能补成地区、隶属关系或人口属性。is_realname、is_org、allow_message 是返回标志,既不是独立资格审核,也不授权联系对方。头像和资料地址只是引用,本例不下载媒体或拓展关系图。
实用研究记录应分开保存所选 token、请求目的、观察时间、原有字段与人工相关性判断。想进一步依据回答内容判断专业性,要另选任务、核对回答接口并明确预算,不能把这个资料快照当作答案证据。
9 月原稿保留在哪里
9 月 27 日原稿提出了搜索、资料、回答三步,并附上这段示意信封。它原本就不是带日期的已验证回答调用;其中 ID 不能被拿来证明十月样本或本次执行:
{
"id": "876962b1-9b17-409f-a654-4a5004199e31",
"status": "completed",
"model": "zhihu/web/user-answers",
"outputs": [
{
"data": {
"data": [
{ "answer_type": "…", "content": "…", "comment_count": 0 }
]
}
}
]
}
历史 User Answers 参数页,显示字符串 limit/offset、sort_type 与 user_url_token。空响应并不证明抓到了回答 feed 或成功续页;本轮没有复验该端点。
双语原代码归档 逐字保存八段 Python、原文与哈希,仅供历史核查。旧 helper 会把缺失业务数据变成空对象,再可能把空首项传给资料接口;原文还同时出现“直接增 offset”和“跟随响应 paging”的矛盾建议。现行代码已移除这些行为。
多关键词扩展、粉丝或回答排序、定时重试、“完整 feed”和影响力增长,都是旧设计中的建议,本次不为其参数、费用、覆盖率或成功率背书。以问题为入口的阅读可另看知乎问题与回答教程。
费用与失败处理
11 月 8 日 inspect 列出两个选定 web 端点各 $0.001,具备组织共享的每日 100 次合资格 API 额度,00:00 UTC 重置。这是资格,不是本账号剩余额度,也不保证免费成功。有意选择两个任务的标价合计为 $0.002,额度影响另计;本例只执行一个。本轮没有测量实际扣费,也没有复测失败计费规则。
401/403 先核对 key 和权限,429 先检查额度或限制。JSON 无效、未完成、结构不符或身份不匹配,要记为失败观察,不要保存成空成功结果。HTTP 成功本身不能证明拿到了选定账号。
常见问题
Agent 能自动找到最好的专家吗? 当前产物是一页候选或已选账号的资料快照。专家判断需要上下文证据,不能只凭同名、徽章或大数字。
资料接口传哪个 ID? 传明确选定的 object.url_token 或已知资料页 slug。命中编号、内部哈希、昵称都不能互换。
limit 和 offset 为什么带引号?
当前所选 schema 定义为字符串,默认 "25" 和 "0";保存页二十条不等于固定步长验证。
候选为空是不是没有合适的人? 不是。它仅表示这一页,或者 skipped 非零时的本地可识别子集,需要分别解释。
allow_message 是否代表可以发消息? 不代表。它是返回字段,不是用户对外联操作的授权;本例到读取就停止。
觉得有用?分享给更多人