抖音星图 API:搜索候选或读取已知达人资料

用一次星图搜索或已知 kolId 资料请求验证状态与身份,区分 API 费用、达人价格和历史商业评估记录。

带受众、表现和价格符号的星图达人概念卡片

搜到一个达人候选,不等于确认了身份、档期和合作报价。接星图 API 时,先决定是用关键词找候选,还是读取一个已经选定的 kolId。把这两件事分开,可以避免身份和预算尚未明确,就自动串起画像、表现、报价等一整套付费查询。

2026 年 11 月 8 日这次修订核对当前公开契约,并用保存响应做离线回放,没有执行新的业务请求。文后保留 10 月 1 日三品牌实验及原始观察、代码归档;新增搜索和资料参考不是那次实验的产物,也没有证明本轮跑通了搜索到资料的连续链路。

先说结论

  • 关键词搜索返回 authors 候选;已知 kolId 的基础资料是另一种平面对象,要检查 id 完全一致。
  • 当前资料输入是字符串 kolId 和 platformChannel;_1 表示抖音视频,_10 表示抖音直播,本例只选 _1。
  • 只读 completed 的 outputs[0].data,并要求严格整数 base_resp.status_code 为 0,缺状态不能当成功。
  • 两接口当前每次 0.02 美元,inspect 都没有 free_quota;响应里的达人任务价不是 API 调用费或已确认报价。

原封面的三张资料卡、受众图、上升柱形图和价格符号均为概念表达,不衡量真实达人适配度,也不代表本轮执行了商业评估。

星图 API 首次接入怎么选

手上有什么当前接口选定请求体
想搜索的话题星图候选搜索{"keyword":"人工智能"}
已选定的星图 ID星图基础资料{"kolId":"7038603512770461703","platformChannel":"_1"}

教学搜索沿用 schema 的“人工智能”,完整保存搜索实际用的是 example,两者不能混写。不要自动挑第一名。star_id 被描述为可用作 kolId 的星图创作者标识,但昵称、抖音 UID、sec_user_id、unique_id、整条 URL 都不是它的替代物。读取资料是另一次主动选择,也多一次费用。

可选 contentTag 和 followerRange 都是字符串。后者示例 10-100 表示十万至一百万粉丝档,不是让你把返回的粉丝数字乘一万。当前没有 page、limit、cursor、offset 输入,响应带 pagination 也不能自行添加翻页参数。本例不猜标签值,不附加筛选。

资料 schema 现在明确写出 _1、_10。旧实验中字符串“1”返回相同资料,只能保留为当时观察,不能替代现行带下划线的参数。返回的数值数组 platform_channel=[1,10] 也不是请求格式。本次没有执行直播渠道查询。

凭据和费用先说清

已有 key,就复用本地 SANDBASE_API_KEY 或项目密钥管理,按需安装 requests。agent 已连接时,只需交代选定任务、关键词或 ID,不必新建凭据。新项目可把 setup skill 和 Markdown quickstart 交给 agent,先实现并测试,再执行。

可以这样描述:“用本地 key 实现一次星图关键词搜索,返回原始候选标识并保留未知值,然后停止。不要自动选人、查报价、解析 ID、提取联系人、翻页或建定时任务。”已有 kolId 时另选一次基础资料读取。不要把 key 粘进提示词,也不要为排错把它打印出来。

11 月 8 日 inspect 中,两端点均为每次 0.02 美元,都没有 free_quota。组织其他合资格 API 的每日 100 次额度,不能直接套到这里。选一次标价 0.02 美元,明确各选一次则合计 0.04 美元,其他商业调整须另行确认。这是接口访问费,和达人任务价是两层;任务价格的货币、单位、税费、结算含义本轮未重新确认。

当前单次 Python 示例

使用 Model API 的 POST /v1/api 路由,不是目录 GET。函数验证所选结构后返回原始业务对象,不兼容顶层 output,不把缺失业务状态默认成 0,也不会自动重试。

Python
import os
import re
import requests

API = "https://api.sandbase.ai/v1/api/douyin/xingtu"


def first_request(task, value):
    if task == "search":
        if not isinstance(value, str) or not value.strip():
            raise ValueError("Provide a selected keyword")
        route, params = "search-kol-v2", {"keyword": value}
    elif task == "profile":
        if not isinstance(value, str) or not re.fullmatch(r"[1-9][0-9]*", value):
            raise ValueError("Provide the selected kolId as a decimal string")
        route = "kol-base-info-v1"
        params = {"kolId": value, "platformChannel": "_1"}
    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(
            f"{API}/{route}",
            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"SandBase HTTP {response.status_code}; request stopped")
        body = response.json()
    except requests.RequestException:
        raise RuntimeError("Network request failed; no automatic retry made") from None
    except ValueError:
        raise RuntimeError("SandBase returned invalid 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]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing documented outputs[0].data object")
    status = payload.get("base_resp")
    if (not isinstance(status, dict)
            or type(status.get("status_code")) is not int or status["status_code"] != 0):
        raise RuntimeError("Xingtu business status is not integer zero")
    if task == "search":
        authors = payload.get("authors")
        if not isinstance(authors, list) or any(not isinstance(a, dict) for a in authors):
            raise RuntimeError("Missing or malformed authors array")
        for author in authors:
            if (not isinstance(author.get("star_id"), str)
                    or not re.fullmatch(r"[1-9][0-9]*", author["star_id"])
                    or not isinstance(author.get("attribute_datas"), dict)):
                raise RuntimeError("Missing candidate identity or attribute object")
    elif not isinstance(payload.get("id"), str) or payload["id"] != value:
        raise RuntimeError("Profile identity does not match the selected kolId")
    return payload


if __name__ == "__main__":
    result = first_request("search", "人工智能")
    print("Returned candidates:", len(result["authors"]))

要查资料,把 main 两行替换为 result = first_request("profile", "7038603512770461703") 和 print("Matched kolId:", result["id"])。不要追加在搜索后面。十进制字符串检查是本地身份约束,保留大数字精度,不代表所有可能 ID 格式都支持。

明确为空的 authors 可以有效,缺少数组或业务失败不能当空结果。保存搜索的成功 message 为空,因此不强制字面 Success。HTTP、重定向、JSON、超时、非完成态或身份错误都停止,不回显响应正文和密钥;资料检查也不要求猜测的粉丝数或可联系标记。

新增参考:两个候选和独立宠物账号

完整搜索保存样本 cea216f6-ecfc-4299-8a6b-62320dca7d07 创建于 2026 年 8 月 20 日 09:45:41.219 UTC,输入 example。共有两个作者,pagination 为 page=1、limit=20、total_count=2、has_more=false。以下原样截取首个候选的属性字段:

JSON
{
  "id": "6629665048593694723",
  "core_user_id": "88710789301",
  "follower": "63858"
}

star_id 与属性 id 一致,core_user_id 则是另一种身份字段。首个候选 items 为空,一个任务含两个数值为零的 price;零不能证明免费合作或真实报价。第二个候选 follower 是字符串“11148”,有一条 item、task_infos 为空,不能据此断言没档期或没有费用。

两个完整候选都没有 README 中的 assign_task_price_list、assign_cpm_suggest_price。last_10_items 为未解析的捕获引用 $1d、$1e,不是可用的视频数组,不能 eval、访问或补造解码内容。属性里的数字、标记可能仍是字符串,字符串“0”按普通真假判断反而为真;应保留原类型,缺失项不能补零。

搜索 README 是另一个“人工智能”参考:只展示一名作者,limit=20、total_count=100、has_more=true,有价格字段。它不是完整两候选捕获,也不是本次验证过续页的证据。

独立宠物内容资料 dea68eaf-4e63-4305-8657-b82f484796fe 保存于 2026 年 10 月 7 日 17:37:17.241 UTC,输入 kolId=7038603512770461703、_1,不是上述搜索挑出的结果。以下平面字段保持原值:

JSON
{
  "id": "7038603512770461703",
  "follower": 886798,
  "avg_play": 0,
  "platform_channel": [
    1,
    10
  ],
  "has_phone": true,
  "is_online": true
}

整数粉丝量与搜索的字符串类型不同。avg_play=0 不能证明视频没有播放;没有 mcn_id,应保留 MCN 状态未知,不能转成 false。在线和电话标记不是当前有档期、会回复、允许联系或已得到电话号码的证明,不要把 MCN 介绍、二维码或联系方式导入共享报告。

tags、tags_level_two、opened_task_category 可能是 JSON 编码字符串,content_theme_labels 却是真数组。先保留原值;如以后解码,只处理已确认字段并处理失败,不递归解析捕获引用。记录创建修改时间不是本次观察时间或已验证账号年龄。短资料 README 省略身份字段,严格 helper 会拒绝不完整片段,而不是补 ID 使其通过。

10 月 1 日历史实验,单独保留

下列属于原来 2026 年 10 月 1 日实验、10 月 24 日修订的记录。本轮未重新验证其中的解析、受众、表现、服务报价、成本、每日粉丝等其他接口。归档保留十二段原始 Python、完整原文及哈希。它用于审计,不是现行可照抄流程:旧 helper 自动重试、接受未文档化信封,并把缺失状态视为成功。

历史Free Week抖音目录,不是当前星图价格 历史 API Free Week 目录有 262 个端点、GET 路径,选中的综合搜索显示 Free。旧活动与界面不代表当前选定的两个星图接口符合免费额度;两者本次检查都是每次 $0.02。

原粉丝画像请求曾出现“upstream error 400: Request failed. Please retry”,第二次成功记录为 e5c76e47-6ace-47d8-b2ef-317fef873e74。这不为当前 helper 增加自动重试。

身份解析与受众观察

日食记搜索为 2bd433e3-58f2-445c-93e8-9299d9d2071d,解析记录 44a9f085-3832-4b92-a183-d5259d43e059 返回下方原 JSON。中国国家地理和一条的解析记录分别是 a6517c08-7b7d-4c19-b932-f83f4c578a8c、e2c448b7-33ed-49d9-9864-cebad3305633。当时精确昵称筛选缩小了候选,但不等于独立验证身份;搜索“一条”时别的创作者排在前面,也说明不该自动取首项。

JSON
{
  "id": "6677767167234015243",
  "core_user_id": "64117131714",
  "nick_name": "日食记",
  "tag": "美食",
  "base_resp": {"status_code": 0, "status_message": "Success"}
}

历史星图sec_user_id解析参数参考 历史 sec_user_id 转 kolId 参数页展示空生成响应和旧按次价格。该解析器不在当前两个核对端点中,图片不证明新身份链路成功。

当时渠道说明没有列完整,_1 与字符串“1”返回相同记录;现行基础资料 schema 已明确 _1/_10,应按当前文档接入。旧 MCN 布尔化写法也只留归档,mcn_id 缺失不能变成“无 MCN”。

日食记粉丝画像 e5c76e47-6ace-47d8-b2ef-317fef873e74 的取整描述保持原样:

JSON
{
  "distributions": [
    {"type_display": "年龄分布", "description": "24到30岁居多,占比30%"},
    {"type_display": "城市等级分布", "description": "一线居多,占比37%"},
    {"type_display": "八大人群分布", "description": "新锐白领居多,占比26%"},
    {"type_display": "性别分布", "description": "男性居多,占比50%"}
  ]
}

独立粉丝分布记录 82bcca0d-4e4b-4b8f-9ca8-75ca62aabdad 是男性 6,169,425、女性 6,155,171,基本均衡,不宜只读“男性居多、50%”。观众画像 1d0456b8-5e68-48ce-9a45-0aac0f434471 中,18~23 岁占 32%、Z 世代为首;粉丝则偏 24~30 岁、新锐白领。这是不同历史分布,不是新测量。

表现、报价和三品牌表

日食记表现 c6d7e6f1-8615-406c-a776-98266ecf1111 的汇总播放中位数约 179 万,enrollment 汇总约 38.6 万。原响应有 15 条 latest_item_info,以及单独的 latest_star_item_info;不能把前者全部命名为自然视频,也不能推导商单导致播放折损。中国国家地理 c4a11532-3bcb-4fe9-a4f7-e448172bb999 汇总为空但视频仍在,旧计算中位数是另一种回退口径,不是把空汇总当零。

历史星图视频表现参数参考 历史视频表现参考列出必填 kolId/onlyAssign、不完整取值描述、企业账号说明与旧价格。它的空生成响应不能证明其他接口今天仍可用或有某种投放效果。

日食记服务价 8bc1807b-f27a-4cd6-883a-1d66b8ac5b3d 原文节选如下。当时按 enable 与 task_category=1 筛视频服务,其他类别包括象征价格附加项和无价格的自然播放结算项;这些不是当前确认报价。

JSON
{
  "industry_tags": ["食品饮料-水饮冲调", "3C及电器-大家电", "母婴宠物-宠物生活"],
  "price_info": [
    {"desc": "植入视频", "price": 180000, "settlement_desc": "固定价格", "task_category": 1, "enable": true},
    {"desc": "定制视频", "price": 300000, "settlement_desc": "固定价格", "task_category": 1, "enable": true}
  ]
}

成本记录 be7df1c1-692c-427d-9aa9-7ccbd7d26028 含预期播放与 21_60/60 分档。作者当时用植入价除以预期播放再乘 100,000,在三个账号复现 cpm_21_60,推测单位是每千次预期播放的“分”、对应 21~60 秒。60 秒与定制价只在两个账号对上,日食记不一致。这些仍是特定旧样本推断,不是现行权威单位、货币换算或新公式。

历史星图服务价参数参考 历史服务价参考含 kolId/platformChannel、不完整渠道说明、企业账号文字与旧价格。本轮没重新验证这个接口;现行基础资料的渠道定义是另一份契约。

原 evaluate 主流程每个账号七次,三个账号合计 21 次完成调用,加一次重试;不包含文中所有额外的分布、观众、每日粉丝和 v2 实验。原取整表保留如下:

账号粉丝近期播放中位数植入视频报价预期播放粉丝画像
日食记(美食)约 1,254 万约 414 万(15 条)约 18 万元约 311 万24~30 岁,新锐白领
中国国家地理(自然科学)约 564 万约 78 万约 8 千元约 29 万31~40 岁,新锐白领
一条(人文生活)约 666 万约 30 万约 15 万元约 31 万31~40 岁,新锐白领

近期播放列来自各自列出的 15 条视频。日食记约 414 万与汇总约 179 万不同,汇总窗口和算法未给出。那次比较中,中国国家地理按预期播放计算的成本最低;日食记是报告播放/预期播放较高,不是验证了独立触达。一条的预期播放约为日食记十分之一、列示价格接近;家居装修等主题只能补充背景,不能保证投放适配或模型推荐一定有效。

额外历史检查

每日粉丝 f67341bd-80a0-4387-90a5-928d54f669e3 覆盖 2026-09-01 至 09-28,共 28 个 fans_cnt 点,从约 1,259 万到 1,255 万。v2 的基础、分布、传播、成本记录分别为 8cd17f09-cadc-487c-b34d-8a4cf3245497、82bcca0d-4e4b-4b8f-9ca8-75ca62aabdad、59c050f8-3b65-4117-a30d-169c2a6136fa、194b74e9-78f2-4711-9d4e-19bd00b07e51,当时成本值与 v1 一致。这不等于现在应该遍历所有接口。旧新世相对照还发现抖音和星图搜索粉丝数不同,不能静默混用来源。

常见问题

昵称够做商业评估吗? 够开始搜索,不够确认身份、档期、成交价或投放适配。另一次付费资料读取前,应先明确选定哪个 ID。

任务价格零,能当成免费合作吗? 不能。零、缺失、空列表分别保留;真实报价还需要可比较的任务、形式、时间和结算含义,当前证据不提供保证。

可以用每日免费 API 次数吗? 当前选定两接口的 inspect 都没有 free_quota。一次 API 请求按 0.02 美元预算,与达人商业金额分开。

更多入口见 抖音 API 导航;已选定公开账号时,可看独立的 资料与投稿教程。先完成一个可核验的读取,再扩展商业研究流程。

2026 年 SandBase Douyin 枢纽的标价对比,见 2026 年最佳 Douyin API:价格对比。

觉得有用?分享给更多人