今日头条作者研究 API 教程 | SandBase

按已知头条文章 ID 选择一次 app 或 web 请求,校验响应、保留可选作者字段和 HTML,并区分历史研究与当前接入。

暗色电影感渲染:头条文章卡片汇聚成作者资料卡和评论流,流入 Agent 核心

拿到一篇头条文章,可以先问两个不同的问题:这条内容有什么账号和互动信息,或者能读到哪些正文与发布时间信息?头条 app、web 文章接口的输入名称不同。首次接入先选一个接口,看清响应,再决定是否继续查其他文章或评论。

本次 2026-11-08 修订核对免费 inspect 与当前公开参考,没有执行付费业务请求。原文 2026-10-01 UTC 的作者研究实验、run ID 和精简 JSON 仍保留在后半部分。完整目录见头条公开数据 API 总览。

先说结论

  • app 文章记录用 group_id 传已知数字文章 ID。
  • web 文章记录用 aweme_id,不能在这个路由里换成 group_id。
  • 两个选定参考都先读取已完成的 outputs[0].data,再检查 message: "success" 和内层 data 对象。
  • 缺少作者资料不是删除证据;web content 是 HTML,本例不渲染、不下载图片、不查评论。

先选一个文章请求

眼前的任务精确端点请求字段
检查文章可用的账号与互动信息App article info字符串 group_id
检查正文与发布信息Web article info字符串 aweme_id

例如 https://www.toutiao.com/article/7450114952884503059/ 中的长数字是文章 ID,app 参考也描述了 /group/<id>/ 链接。函数只接收已知 ID,不请求分享链接、不跟随跳转、不解析任意网址。web 参数虽叫 aweme_id,这里仍是头条文章接口,不是去另一个平台查询。

两个 schema 都只声明各自的必填字符串字段。不额外加入 offset、作者 ID、语言或搜索关键词。文章与作者研究并不要求先自动调用三次;这里 app 与 web 二选一,评论不属于首次请求。

已有 Key、Agent 或新项目如何接入

已有 Key 的项目,在本地配置 SANDBASE_API_KEY,并在 Python 环境安装 requests。不要把 Key 写进提示词、源码或日志。代码先检查密钥,再请求选定路径。

Agent 已连接 SandBase 时,让它 inspect 所选端点并复用连接,给出已知文章 ID、接口选择和一次请求边界。例如:“只读取一次 web 文章记录,把 HTML 当数据保留,告诉我哪些元数据存在;不下载图片,不查评论。”不用重建项目,也不用枚举所有接口。

新项目可以把 setup skill、Markdown quickstart和任务一起交给 Agent。人工快速入门解释账号和 Key 配置。配置完成不能证明目标文章可访问,也不能证明共享免费额度仍有余额。

一次请求的 Python 示例

输入保护要求 ASCII 数字字符串,防止传错类型或整段 URL,但不保证文章存在。主程序只打印可用字段名,避免把缺失作者或标题补成一条虚构记录。

Python
import os
import re
import requests


def first_request(surface, article_id):
    if surface not in ("app", "web"):
        raise ValueError("Choose app or web")
    if not isinstance(article_id, str) or not re.fullmatch(r"[0-9]+", article_id):
        raise ValueError("article_id must be a numeric string, not a URL")
    field = "group_id" if surface == "app" else "aweme_id"
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise ValueError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/toutiao/{surface}/article-info",
            headers={"Authorization": f"Bearer {key}"},
            json={field: article_id}, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"HTTP {response.status_code}; no retry performed")
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Network request failed; no retry performed") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("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("Missing business payload object")
    if payload.get("message") != "success":
        raise RuntimeError("Article business request did not succeed")
    if not isinstance(payload.get("data"), dict):
        raise RuntimeError("Missing article data object")
    return payload


if __name__ == "__main__":
    result = first_request("app", "7450114952884503059")
    print("Available article fields:", ", ".join(result["data"]))

要选 web,就把最后的调用替换为 result = first_request("web", "7450114952884503059"),保留后面的字段列表输出。不要把它追加成第二个自动请求。ID 来自公开 schema 与旧文,本次没有重新执行。

函数检查 HTTP 状态,拒绝重定向,处理连接、超时和 JSON 错误,并要求 completed。outputs[0].data 缺失或结构错误会报错,不回退为空对象,也不接受历史顶层 output。业务层则按两个当前参考检查精确的 message: "success" 与 data 对象;其他端点的 errno: 0 不能替代这里的契约。

不会自动重试、翻页、读取评论、查作者、下载素材或调用模型。错误信息不带 Key 和原始响应正文。内层空对象即使结构合法,也仍是空数据,不代表完整作者卡片;先看返回字段,再决定它能否回答问题或是否值得再查一次。

可选作者字段不能变成过度结论

app 参考描述了 data.user_info、互动计数、分享信息等字段,但短 JSON 是裁剪过的。节选里没有 user_info,不能证明完整响应也没有;原文的真实样本包含它,也不能保证今天每个作者的资料都齐全。

实际记录缺少 user_info 时,应把发布者信息保留为未知,不直接标记文章已删除。旧实验另行观察到明确的 delete: 1,那和单纯缺少作者资料不是同一件事。函数保留字段原样,供调用方区分删除信号和可选信息不可用。

缺失计数保持未知,明确数字零保留为零;认证 false 和没有认证字段也要区分。粉丝数不是文章触达,阅读计数不是核验过的独立受众,更不是未来表现预测。认证说明有助于核对身份,不等于可自动排名或开展联系。

旧文曾遇到一个特定媒体账号的稀疏 user-info 结果。这里只把它当有日期的对照,不能泛化为 user-info 普遍失效,也不能据此把所有资料查询都换成文章数据。具体要看研究问题和当前实际返回什么。

ID 精度和保存示例的展示限制

文章 ID 从输入到存储都应保持字符串,这些长数字超过 JavaScript 精确整数范围。本地保存的示例就体现了这个风险:数值 group_id 显示成 7450114952884504000,而请求和字符串 gidStr 仍保留 7450114952884503059。这是捕获中的序列化/展示差异,不是实时接口改了文章 ID 的证据。已经舍入的数字再转字符串,也找不回丢掉的末位。

核对身份时优先使用原请求,以及存在时已确认的字符串标识,不把舍入后的展示数字拿来做严格相等比较。Python 示例发送原字符串,也不会把业务 ID 转成浮点数。

这些保存捕获还在 content、context 等位置带有 $1d 一类渲染引用,它不是正文,不应变成解析器样本或新的业务证据。保存时间与公开节选说明的是已有材料,不是本次请求成功。审阅截图或从页面复制测试数据时,这个区别尤其需要保留。

web 正文是 HTML,不是现成摘要

当前 web 参考把 content 展示为 HTML,并描述标题、发布信息、来源账号和图片。旧实验在 h5_extra 找到部分字段,而当前字段说明也提及顶层位置。不能从某次观察就断言其他位置永远不会出现,应检查当前记录并保留来源。

本例原样返回 HTML,不执行它、不插入网页、不访问内嵌链接,也不取图片。应用若需要纯文本,应选合适的 HTML 解析器,验证标题、实体、段落边界和嵌入元素。旧代码用正则去标签后截到 2,000 字符,只是研究摘录,不是可靠全文抽取,也不是安全清洗。

记录里有媒体地址,不等于已验证能下载;部分公开参考 URL 已截短,不能照抄成真实目标,也不应让 Agent 自动访问所有链接。首次接入先认清字段,比收到一个响应就宣称做完文章归档更可靠。

费用和请求预算

2026-11-08 免费 inspect 显示,两个选定端点的基础价都是 $0.001/次,均符合组织共享的每日 100 次合资格 API 调用额度,在 UTC 00:00 重置。资格不是剩余额度,本次没查余额或实际扣费,不能承诺一定免费。

选 app 或 web 都只发一次请求。若另行决定两个都读,基础价估算 $0.002,再考虑实际额度;评论、更多页面和重试会增加调用。后面的旧三链接研究有另一套调用预算,不能把它当成当前首次接入成本。

历史头条 Free Week 目录 历史目录截图:七个端点与 Free Week 标签只描述旧画面,不代表当前数量或剩余额度。选定端点价格另行核对,代码使用上文 POST Model API 路由。

历史作者研究:2026-10-01 UTC

原封面表达“文章到作者再到评论”的思路,卡片与示意图是概念素材,不是本轮执行过这条链路的证据。

旧的闪电新闻文章实验调用 app article-info,run 为 7ce8965e-01c0-4577-8f27-195eacffe3d3。以下原始精简业务 JSON 逐字保留:

JSON
{
  "data": {
    "group_id": 7450114952884503059,
    "read_count": 95,
    "digg_count": 2,
    "comment_count": 1,
    "repin_count": 1,
    "user_info": {
      "name": "闪电新闻",
      "user_id": 51050126444,
      "media_id": 51201073347,
      "fans_count": 5582263,
      "user_verified": true,
      "user_auth_info": "{\"auth_info\":\"闪电新闻官方账号\",\"auth_type\":\"5\"}"
    }
  },
  "message": "success"
}

新华网文章 run a4b82d62-f916-4e48-a6fc-5133965ebd5f 有相似卡片,约 2,940 万粉丝、2.6 万阅读。这些是旧观察,不是当前数字。当时 user_id 是数值,user_auth_info 是 JSON 字符串;转换需要类型检查,转字符串之前也得先保证数字精度没有损失。

旧 user-info 对照显示空名称、49 粉丝,而文章卡片约 558 万粉丝,看起来指向关联短视频资料。原作者无法判断是上游路由还是特定账号造成,这个不确定性仍保留。本次不能把它改写成接口普遍失败的规则。

另一旧文章返回 delete: 1 且没有 user_info。旧函数同时跳过删除和任何缺少作者卡片的记录,把两种情况混在一起。当前首请求不隐藏这些数据;只有作者字段缺失,不足以确认删除。

历史 app article-info 参考 历史 app article-info 参考,展示必填 group_id。其中空响应示例是文档占位,不代表接口不返回作者字段。

web 第一次误传 group_id,得到缺少 aweme_id 的 400。修正后保存的 run 19d6214f-a69e-448f-bdff-b0f62ba2c88f 返回 HTML、media_user_id 及 h5_extra 元数据,例如 2024-12-19 21:31 的发布时间。那次媒体账号 ID 与先前卡片一致;当前代码不会自动再查一次来做对照。

历史 web article-info 参考 历史 web article-info 参考。同一个头条文章标识在这里放入 aweme_id,截图不是本次新请求。

旧评论实验观察了一个共 1,076 条评论的帖子。run c61a4cd6-8502-44dc-a344-61a88bbe5b8e 返回 20 条、has_more: true、offset: 20;run 0e4c824c-d42c-4d36-9758-fc296c089d61 返回 offset 40。正文、点赞、回复数、创建时间属于当时观察字段,旧输出主动丢弃评论者姓名和 ID。这些是历史分页现象,本次没重验评论契约,也不实现续页。

历史评论参考 历史评论参考,包含 group_id 和字符串 offset;本轮没有复验评论或继续翻页。

旧组装流程处理三个链接:两个可用文章卡片和一个删除记录。每个可用文章读取一页评论时,计划路径合计七次调用:两次 app、两次 web、两次评论,再加删除文章的一次 app。旧文“每篇三次”没有覆盖跳过记录的情况;多读评论或重试还会增加次数。

两种语言各五段原 Python 均逐字保存在历史代码归档,附哈希。双信封回退、宽泛跳过缺卡片、正则处理 HTML、多文章与评论自动调用只作审计材料。旧 TLS 重试成功的观察,也不是现在加入自动重试的建议。

常见问题

缺少作者卡片就是文章删除吗? 不是。保留未知,与明确删除信号分开;裁剪过的 README 示例也不能证明完整结果缺字段。

到底传哪个 ID 字段? app article-info 用 group_id,web article-info 用 aweme_id;两个请求中的头条文章 ID 都保持字符串。

可以直接交给 Agent 吗? 可以给它 setup skill、已知文章 ID 和所选接口,要求返回经过校验的数据、标明未知字段、不自动执行后续调用。

会取完评论或全文吗? 示例只做一次文章读取,保留返回数据。评论需要另查;web HTML 不会在这里被渲染、清洗或总结。

收个尾

从已知文章和具体问题出发,选 app 或 web,用准确的字段名,并先验证成功消息与内层对象,再解释可选元数据。可打开 app article info、web article info,或先看 API 总览。

觉得有用?分享给更多人