快手达人研究 API 教程 | SandBase

从一个关键词候选页或已知账号资料开始接入快手,逐层验证状态与字段,保留未知计数,不自动遍历达人。

深色电影质感画面:快手用户搜索化为一张达人资料卡,汇入 Agent 内核

搜达人和查一个已知账号,是两种不同的任务。关键词给出候选;明确的账号 ID 才能直接查询某个人的资料。如果第一次接入就把搜索结果全部送进资料查询,遇到错人、缺字段或费用问题时,很难知道是哪一步出了偏差。

本文在 2026-11-08 根据免费 inspect 与公开参考完成修订,没有发起新的业务请求。原来 2026-09-28 UTC 的实验仍保留为历史观察。先从下面两个任务中选一个,完整目录见快手公开数据 API 汇总。

先说结论

  • 搜索第一页传 keyword 和明确的空字符串 pcursor,先看候选,不自动选中第一人。
  • 已知数字 user_id 时直接查资料。昵称、快手号、账号 ID 不能未经核对就互换。
  • 从 completed 的 outputs[0].data 读业务对象:搜索检查整数 responseCode: 0,资料检查整数 result: 1 和对应嵌套结构。
  • 两个端点当前均标价每次 $0.01,并具备共享每日额度资格;资格不等于你的剩余额度。

沿用封面是概念插画:展示的账号名、1.28M 粉丝、46.7M 获赞和视频数字都是虚构示意标签,不是接口测量或认证达人,也不代表 Agent 会自动选人。

先确定手上是什么输入

你已掌握的信息选择的接口本文发送的参数
想调查的话题或名称用户搜索 V2keyword、pcursor: ""
确定的数字账号 ID单用户资料 V2字符串 user_id

搜索 schema 还列出 fans_sort、user_gender、user_relation,包括粉丝排序、性别和关系筛选。入门代码不发送这些选项,也不推断未声明的默认值;这些组合没有在本轮逐个复测。认证筛选只是查询条件,不能替你证明账号身份、受众质量或商业合作价值。

本文使用 SandBase 读取公开数据,需要 SandBase Key,但不要求你登录快手。发帖、以用户身份操作、合作伙伴接口或账号授权内容应走快手官方渠道。公开资料里的某些计数,不意味着能够访问私密作品或用户消息。

历史 SandBase 快手目录 保留的原目录截图仅作导航背景,不能证明当前端点总数、剩余免费额度或一次新请求成功。图中热榜 From $0.001 标签不是本轮两个达人端点当前的 $0.01 单价。

已有 Key、已连接 Agent,还是新项目

已经有 Key,就把 SANDBASE_API_KEY 配置到项目真正运行的本地环境或密钥管理工具里。不要贴进聊天、代码提交、文章或截图。鉴权失败先检查运行环境读到了哪个配置,不要让 Agent 自动另建账号。

Agent 已经接入时,给它明确任务和端点,让它复用现有凭据,只调用一次、验证返回、列出实际存在的字段。第一次先别交给它“研究全部达人”这种开放任务,否则请求数量会随着候选数量增长。

新项目可以把 SKILL.md 与 quickstart.md 一起交给 Agent,再写上:“查这个关键词的第一页,不查候选资料、不翻页。”已知 ID 则改成“读取这个 user_id 一次”。人工快速入门介绍环境配置。请在实际运行脚本的 Python 环境安装 requests。

一次请求,逐层检查

下面两个分支只能择一执行。缺少业务对象会明确报错,不会变成一个看似正常的空列表。

Python
import os
import re
import requests


def first_request(task, value):
    if task not in ("search", "profile"):
        raise ValueError("Choose search or profile")
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Supply a nonempty string")
    if task == "profile" and not re.fullmatch(r"[0-9]+", value):
        raise ValueError("user_id must be a numeric string, not a handle or URL")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    path = "search-user-v2" if task == "search" else "one-user-v2"
    params = {"keyword": value, "pcursor": ""} if task == "search" else {"user_id": value}
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/kuaishou/app/{path}",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"HTTP {response.status_code}; inspect access and budget before retrying")
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Network request failed; no automatic retry") 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 outputs[0]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing business object at outputs[0].data")
    if task == "search":
        if type(payload.get("responseCode")) is not int or payload["responseCode"] != 0:
            raise RuntimeError("Search business status was not responseCode 0")
        feeds = payload.get("mixFeeds")
        if not isinstance(feeds, list) or any(
            not isinstance(feed, dict) or not isinstance(feed.get("user"), dict)
            for feed in feeds
        ):
            raise RuntimeError("Expected mixFeeds array with user objects")
    else:
        if type(payload.get("result")) is not int or payload["result"] != 1:
            raise RuntimeError("Profile business status was not result 1")
        profile = payload.get("userProfile")
        if not isinstance(profile, dict) or not isinstance(profile.get("profile"), dict):
            raise RuntimeError("Expected userProfile.profile object")
        if not isinstance(profile.get("ownerCount"), dict):
            raise RuntimeError("Expected userProfile.ownerCount object")
    return payload


if __name__ == "__main__":
    result = first_request("search", "人工智能")
    print("Returned fields:", sorted(result))

如果查已知账号,把最后一行调用的赋值替换为 result = first_request("profile", "3795214411"),保留后面的字段列表输出。不要追加成第二次自动请求。此 ID 来自已有公开 schema 示例,本轮没有重新调用它。

函数返回原始业务对象,不扁平化资料、不自动排名、不下载头像、不打开商店入口,也不抓作品。搜索返回空数组和根本缺少数组是两回事:前者可以是没有候选,后者可能是接入契约发生变化。

资料分支要求参考结构中的 userProfile.profile 和 userProfile.ownerCount 都是对象。遇到别的账号状态时,应停下来检查,而不是声称所有账号必定满足这个结构。对象里的某个计数缺失,仍然保留缺失状态,不默认补零。

搜索候选不是身份确认

公开参考把候选放在 mixFeeds,每个条目里有 user 对象。排在前面不等于最权威,也不等于最适合投放;同名账号还可能对应完全不同的人。请先看明确的身份字段与研究目标,再决定是否另查一个资料。

原 2026-09-28 UTC 搜索实验的 run ID 为 760a7ea6-b480-40c2-8a91-fb551a2df9c1,记录了 mixFeeds、pcursor,以及观察到的 user_id、kwaiId、fansCount、following。这是旧样本字段清单,不保证以后每次都出现。找不到账号 ID 时应保留未知,不要从追踪字符串解码出一个猜测值。

另一个 2026-10-07 保存的公开示例包含下面这段业务数据。这里只保留第一个候选的粉丝计数,省去身份文本、头像地址和追踪信息。这不是十一月的新业务测试:

JSON
{
  "responseCode": 0,
  "mixFeeds": [{"user": {"fansCount": 89774}}],
  "pcursor": "1",
  "recoPcursor": "no_more"
}

pcursor 与 recoPcursor 是两个字段。schema 说明第一页用空 pcursor,后续页从上次响应取得 pcursor;推荐流的游标不能拿来替代它。本轮只做第一页的离线验证,没有确认续页、结束条件或重复请求的稳定性,所以代码不自增游标、不猜测何时停止,也不自动请求第二页。

历史快手用户搜索参数参考 原 search-user-v2 参数截图。当前代码显式请求第一页,图片不代表本次已测试翻页。

资料应从正确的层级读取

原 2026-09-28 UTC 资料实验 run ID 为 142efb32-7caf-47e1-a45e-37cf01c721e2,观察到了 authorInfo、userProfile 和 totalPhotoLike。旧代码曾把 authorInfo 当成 userProfile 的替代,这是不合适的:当前参考里它们承担不同用途。

账号记录在 userProfile.profile;计数在 userProfile.ownerCount。authorInfo 包含认证、商业状态等旗标,并不是同一份基础资料。顶层 totalPhotoLike 可能是入口和链接对象,不能直接当作累计获赞数字;参考中的数值字段是 userProfile.ownerCount.total_photo_like。

公开的完整保存示例日期为 2026-10-07,以下只摘出计数,和九月原实验、本轮离线测试分别标识:

JSON
{
  "result": 1,
  "userProfile": {
    "ownerCount": {
      "fan": 362287,
      "follow": 2,
      "photo": 674,
      "photo_private": 0,
      "photo_public": 674,
      "total_photo_like": 7199067
    }
  }
}

这不是可直接送入严格校验函数的完整响应:摘录有意省去了资料对象,原保存样本中还有 profile。反过来,README 的短 JSON 在 userProfile 之前就截断了,也不能据此认定接口不返回资料。讨论“缺字段”时,要先区分完整响应、裁剪展示和真正缺失。

photo_private 是计数,不是读取私密作品的权限。商店入口、商品数量或商业标记也不代表销售额或转化效果。IP 归属地标签是平台展示的账号信号,不能当成对某个人精确位置的测量。报告接收者未必会看 JSON,因此这些边界需要写进输出说明。

历史快手单用户资料参考 原 one-user-v2 截图展示 user_id 输入。本文当前字段路径来自公开参考与保存示例,不代表本轮重新执行业务。

哪些数可以比较,哪些应留空

粉丝量没返回,应标为未知;数值零是一个观察值,布尔 false 又是另一种状态。不要统一用零填充,更不要把缺失粉丝量的账号自动排在所有有数字的账号之后,那是代码偷偷加入的排名规则。

搜索的 fansCount 与资料的 ownerCount.fan 来自不同请求和时间,比较前应记录端点与采集时间。累计获赞不等于近期互动率,单个账号也不能代表整个垂类。先做一个人工核对的小名单,再判断另一次资料查询是否真的能回答剩余问题。

原自动研究函数先搜一次,再最多查五位达人,最多六次调用,不是一次。按当前两个端点的单价估算,这种旧模式最多为 $0.06,尚未考虑额度;这是当前价下的请求量估算,不是九月实际扣费记录。新示例只做一次标价 $0.01 的请求;分别选择两个任务才是两次、标价合计 $0.02。

两个端点都有组织共享每日 100 次额度的资格,00:00 UTC 重置,其他合资格接口也会消耗这份额度。本轮没有查询余额或剩余次数,因此不能承诺这次成功调用一定免费。遇到鉴权、额度、限流或计费错误,先检查原因与预算,再决定是否重新发送。

报错需要区分三层

HTTP 成功不等于业务成功。SandBase 运行 completed 之后,还要检查所选接口自己的成功值:搜索是整数 responseCode: 0,资料是整数 result: 1。示例拒绝把布尔值或数字字符串当成这些状态码,也不把另一端点的状态字段搬过来。

代码不跟随重定向、不自动重试,报错不带响应正文、请求头或密钥。超时可能意味着结果未知,立即重发可能多产生一次调用。JSON 无法解析、缺失 outputs[0].data 或运行未完成都会在读字段前停止。离线测试覆盖这些分支,但不能证明此刻在线服务可用。

历史代码与下一步

原代码在历史归档逐字保存,旁边提供分块哈希。它属于旧实现:接受顶层 output 兜底、把缺失数据变成空对象、自动遍历候选查资料。当前接入请使用上面的首请求示例。

可以把快手号直接当 user_id 吗? 本接口需要数字账号 ID 字符串。先核对候选的明确身份字段,昵称、账号展示号和追踪值不能想当然地替代。

Agent 会自动挑出最好的达人吗? 不会。搜索只提供候选;身份、相关性、缺失字段和研究标准都需要判断,之后才决定是否多查一次或进行排序。

能继续翻页或抓作品吗? 那是另一个任务。本轮只验证搜索第一页或一个资料,不执行续页、作品循环、评论采集或模型分析。

交给 Agent 哪些材料就够了? 给 setup 文档、选定任务,以及关键词或已知 ID。凭据留在运行环境,让它先返回一个经过检查的结果并说明缺失字段,再考虑扩大范围。

需要其他能力时回到快手 API 汇总页,分别核对新端点的参数、业务结构与费用,不要把一次接通当成整个工作流都已验证。

觉得有用?分享给更多人