知乎专家发现 API:搜索候选或读取已知资料

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

历史知乎专家发现概念图,包含虚构的搜索、资料、回答与 agent 卡片

搜出二十个名字相近的知乎账号,并没有回答“你要找谁”。做知乎专家发现 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 V3keyword,显式 limit "5"、offset "0"
已选定的资料页 slugWeb User Infouser_url_token,例如 ming-he-43-93

搜索只有 keyword 必填。当前 schema 的 limit 默认是字符串 "25",offset 默认 "0",没有声明数值上下界。这里选五是为了请求较小的第一页,不保证一定返回五个账号。公开保存请求只传了 deepseek 关键词;它的二十条结果不是本例 limit 五已经运行的证据。

资料接口要求一个字符串标识。注意保留路由里的 web/,其他同名接口可能有不同参数和价格。从已知 /people/ 地址取 slug,或由人明确选择搜索里的 token;不要让 agent 为了补参数就自动采用第一个同名账号。

历史 User Search V3 关键词与字符串分页参数参考 历史 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 完成状态仍然必须检查。

Python
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;未来是否混入别的类型仍需逐行检查。下面只投影第一条的原有字段,省去头像、徽章元数据和不透明上下文:

JSON
{
  "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 不在那二十个搜索候选中。以下原字段投影属于独立资料请求:

JSON
{
  "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 资料 token 参数参考 历史 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 不能被拿来证明十月样本或本次执行:

JSON
{
  "id": "876962b1-9b17-409f-a654-4a5004199e31",
  "status": "completed",
  "model": "zhihu/web/user-answers",
  "outputs": [
    {
      "data": {
        "data": [
          { "answer_type": "…", "content": "…", "comment_count": 0 }
        ]
      }
    }
  ]
}

历史 User Answers 字符串分页及排序参数参考 历史 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 是否代表可以发消息? 不代表。它是返回字段,不是用户对外联操作的授权;本例到读取就停止。

觉得有用?分享给更多人