今日头条公开数据 API | SandBase

今日头条是中国体量最大的内容推荐平台之一——一条由文章、视频和创作者账号组成的信息流,可以直接映射到媒体监测、作者研究和内容分析等场景。可要用程序去读这些数据,通常意味着逆向 App、周旋于 token,而且 App 一变你就得重写一遍采集器。

SandBase 的今日头条公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取头条公开的作者主页、文章、视频和评论——只用一个 SandBase API 密钥,不需要登录头条、也不需要 SDK。端点 API 参考是每个参数和响应信封(id/status/model/outputs[0].data)的权威来源;下面展示的业务载荷字段名只是一个示例结构、并非保证的 schema,请以一份真实响应为准核对。

这不是今日头条官方开放平台。 当你需要经过授权的会员操作,或需要有正式授权协议的数据时,请走头条官方渠道。当你的工作流需要用于研究和监测的公开、只读数据时,用 SandBase。想上手?获取 SandBase API 密钥,然后浏览头条端点。

先说结论

• 一套 API 即可读取今日头条公开的作者主页、文章、视频和评论。
• 本文的 Model API 端点用 POST /v1/api/toutiao/<path> 调用——只传该端点的参数,无 SDK,一个 SANDBASE_API_KEY。
• 端点以自然标识为入口:作者用 user_id、文章/视频及其评论用 group_id。
• 只返回公开、只读数据。你这边无需发帖、无需平台登录或 OAuth、不涉及私有数据;用 SandBase API 密钥鉴权即可。

你需要哪种头条 API?

你的需求	选择	原因
发布、以会员身份操作,或使用账号授权数据	头条官方渠道	会员和账号级操作应通过头条直接进行。
读取公开作者、文章、视频或评论	SandBase 头条公开数据 API	普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。
私有或仅账号可见的数据	两种公开方案都不适用	这类数据不在本篇公开数据指南范围内。

头条 API 能取到什么

目录按用途分组:

• 作者 — 按 user_id 读取公开作者主页。
• 文章 — 按 group_id 读取文章详情。
• 视频 — 按 group_id 读取视频详情。
• 评论 — 按 group_id 读取某内容项的评论。

动手前请以每个端点的线上 API 参考为准核对具体面和参数;可用性因端点而异。

SandBase 上的头条 API 页面——带标签的概览和端点列表,每个端点都标了路径。

头条提供什么,SandBase 补什么

公开数据来自头条。SandBase 并不拥有或运营头条,它为符合条件的公开数据工作流提供一层统一的 API。每个能力都成为一个稳定端点,鉴权收敛为单个密钥,响应回来是可预测的 JSON——于是 Agent 可以沿着”读作者 → 读文章 → 读评论”这一条约定链式调用,而不用维护采集器。

快速上手:第一次调用

SandBase 暴露不止一个 API 面。目录里可能显示 /apis/v1/... 下的 GET 路径;本文使用每个端点 API 参考上标注的带厂商前缀的 Model API 路径。不要擅自改动 HTTP 方法或 URL——以你所选端点的参考为准。

读取作者主页:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/toutiao/app/user-info",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"user_id": "6457199476"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "头条请求未完成"))

# 参考保证信封和上游 code,业务字段随端点而定、以真实响应为准。
payload = body["outputs"][0]["data"]
if payload.get("errno") != 0:
    raise RuntimeError(payload.get("message", "上游错误"))
author = payload.get("data", {})
print(author.get("name"), author.get("followers_count"), author.get("publish_count"))

curl -X POST https://api.sandbase.ai/v1/api/toutiao/app/user-info \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "6457199476"}'

每个响应都使用同一个信封:一个 id、一个 status、model 名称,以及一个 outputs 数组,其唯一元素在 data 下承载数据。头条的若干端点会在结果外再包一层上游状态字段——user-info 用 errno(0 表示成功),主体在 data.data 下;另一些端点用 err_no。所以先按 SandBase 的 status 分支判断,再检查上游 code,然后才读内层对象;并查阅每个端点参考确认其运行模式(run mode)。下面是一个示例响应结构——字段名并非保证的 schema、以真实响应为准,请把字段名和取值当作示例,并对照真实响应核对,因为负载会随时间变化:

{
  "id": "79661704-523a-455e-bd9b-c57be210ca1a",
  "status": "completed",
  "model": "toutiao/app/user-info",
  "outputs": [
    {
      "data": {
        "errno": 0,
        "message": "success",
        "data": {
          "user_id": "…",
          "name": "…",
          "description": "…",
          "followers_count": 0,
          "followings_count": 0,
          "publish_count": 0,
          "digg_count": 0,
          "avatar_url": "…"
        }
      }
    }
  ]
}

failed 或 timeout 的运行会带 error,且不含 outputs。响应结构因端点而异——请检查一次真实响应,并逐端点确定精确的字段路径。

端点 API 参考是每个参数名和响应路径的事实来源。

能力地图

能力簇	代表端点	典型用途
作者主页	toutiao/app/user-info	创作者研究与受众规模评估
文章详情	toutiao/app/article-info	按 group_id 做内容分析
视频详情	toutiao/app/video-info	按 group_id 读取视频项
评论	toutiao/app/comments	互动与情感分析输入

分页方式因端点而异——评论端点接受一个 offset(以字符串传入)来遍历评论。请查阅每个端点的结构。

头条端点列表的一角,覆盖 app 面。

在 Agent 工作流中链式调用

因为每个端点共享同一套鉴权和同一个响应信封,Agent 可以从一个作者一路走到一条评论,而不用为每个面单独写特例。一个常见的媒体研究模式是这样:

1. 读作者。 用一个 user_id 调用 toutiao/app/user-info 拿到名称、简介和粉丝/发文数。
2. 读内容。 用一个 group_id 调用 toutiao/app/article-info 或 toutiao/app/video-info 拿内容项详情。
3. 读评论。 用同一个 group_id 加一个 offset 字符串调用 toutiao/app/comments 拿互动输入。

每一步都返回相同的 { id, status, model, outputs } 结构,所以你的 Agent 只需按 status 分支一次,检查上游 code(errno/err_no),并在每一步复用同一段读 JSON 的代码。

常见用例

头条作者 API 做创作者研究

用一个 user_id 调用 toutiao/app/user-info 读取作者主页——名称、简介和粉丝/发文数。输入:一个 user_id。输出:一个主页对象。端点:user-info。

头条文章 API 做内容分析

用一个 group_id 读取 toutiao/app/article-info 拿文章详情。输入:一个 group_id。输出:一个文章详情对象。端点:article-info。

头条评论 API 做互动信号

用一个 group_id 加一个 offset 字符串运行 toutiao/app/comments 来遍历评论。输入:一个 group_id 加 offset。输出:一个评论负载。端点:comments。

为什么放在 API 层来做

你当然可以用无头浏览器指向头条、解析 App 的负载,但这条路很脆:App 会变,token 会轮换,你维护的是采集器而不是在做产品。通过一层统一 API 来读,意味着你的代码依赖的是有名字的 JSON 字段和单个响应信封,而不是某个 App 内部实现。鉴权是一个密钥,而且因为每个端点都返回相同的 { id, status, model, outputs } 结构,重试、日志和错误处理都可以收进一个你写一次、处处复用的辅助函数里。

正是这种一致性让工作流对 Agent 而言可组合。把一个 user_id 换成另一个、把一个 group_id 换成下一个,代码路径完全一样。再加第四个读取——比如某条视频的详情——它也照样接在同一个判 status 的辅助函数后面,用同样的 errno 或 err_no 上游 code 检查。实际的收益是:你的时间花在”数据对你的研究意味着什么”上,而不是花在维持一个采集器去追一个移动靶。当你需要的不止是单次读取时,在线上列表里查到合适的端点,并在接入前确认它的参数。

局限与边界

• 仅公开、只读数据。 不发帖、不关注、不涉及私有或仅账号可见的数据。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 等瞬时错误时按退避策略重试。
• 参数与结构随上游面而定。 标识各异(user_id、group_id);评论 offset 是字符串;上游成功码各异(errno 与 err_no)。先看一次真实响应、读一遍结构。
• 以线上参考核对端点。 可用性和字段可能变化;在依赖某个具体端点前先确认。
• 这不是头条官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守头条条款和适用规则。

常见问题

我需要头条开发者应用或登录吗? 不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有头条账号或 OAuth。

什么标识一个作者或一篇文章? user_id 标识一个作者。group_id 标识一篇文章、一条视频,或该内容项上的评论。

为什么响应里 data 内层还有一个 code? 头条端点会在结果外包一层上游状态字段——user-info 用 errno(0 为成功),主体在 data.data 下;另一些端点用 err_no。读内层对象前先检查它。

我能读私有或仅账号可见的数据吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。

从作者主页开始

创建一个 SandBase API 密钥,调用 user-info,在扩展到文章、视频或评论之前先检查返回的结构。准备好后:

• 获取 SandBase API 密钥
• 浏览头条端点
• 打开 user-info API 参考