抖音达人视频研究 API 教程 | SandBase

用已知抖音 sec_user_id 发起一次主页或作品首屏请求,检查错误、排序与额度,并区分历史零播放字段和缺失指标。

暗色电影感渲染:搜索镜头扫过一排达人头像,汇入资料卡片,再展开成一列按高度排序的视频卡片

已经拿到抖音创作者的 sec_user_id,下一步先选一个问题:核对主页资料,还是看一页已发布作品?这篇教程从已知账号出发,只发送一笔 SandBase 请求,不自动搜索其他人、给全部作品排名或追加统计调用。2026-10-01 的完整研究实验保留在后面,用来说明当时样本的边界。

先说结论

  • 已知 sec_user_id 查主页,用 app-v3/user-profile;读首屏作品,用 app-v3/user-post-videos。
  • 作品首页传整数 max_cursor=0,count 不超过 20;sort_type=0 为最新,1 为最热。
  • 只读取 outputs[0].data,再检查公开样本中观察到的 status_code=0 和对应业务结构。
  • 2026-11-08 核对的两个端点基础价均为 $0.001,符合组织每日共享 100 次额度条件;本轮没有查剩余额度。

已知账号,先选一笔请求

你要回答的问题选择
这个账号有哪些可读取的主页信息?用户主页,必填字符串 sec_user_id
这个账号的一页已发布作品是什么样?用户作品,必填 sec_user_id,可选 count、max_cursor、sort_type

使用你已经核实的完整标识。昵称、搜索关键词、数字 UID 或主页 URL 都不能直接替代 sec_user_id。如果目前只有关键词,可以先查看独立的 抖音 API 总览,这里不会自动搜索再选第一位用户。

想看近期内容,选择 sort_type=0;想看按热度排序的样本,选择 1。排序选项不等于完整覆盖,也不是对真实触达效果的独立排名。示例请求五条,符合最多 20 的限制,但不能保证一定返回五条;它从整数游标 0 开始,首笔结束后就停止。

  • **已经有 key:**放到本机 SANDBASE_API_KEY 环境变量或密钥管理器,不要发进提示词或提交进代码。
  • **Agent 已连接:**复用 SandBase 连接,搜索 Douyin,再 inspect 选定工具的当前契约和价格。
  • **从零开发:**把 setup Skill、Markdown Quickstart、已知标识和研究问题交给 Agent,先看它准备的请求,再决定执行。

任务可以这样写:“用这个已知 sec_user_id 准备一次作品首页请求,count 五条,最新排序。复用我的 SandBase 连接,先展示当前参数和费用依据。不要自动换账号搜索、翻页、重试,也不要追加批量统计或 LLM。”

一次请求,不把错误变成空数据

2026-11-08 免费 inspect 显示,这两个端点 base_price 都是 0.001,free_quota 为组织内符合条件的 API 共享每日 100 次,UTC 00:00 重置。这只确认资格,没有确认剩余额度,也不承诺请求必定免费。执行前重查账户使用情况和价格;本次修订没有新增付费业务查询。

运行 python -m pip install requests,在本地配置 SANDBASE_API_KEY,把已知账号标识放到 DOUYIN_SEC_USER_ID。将代码保存为 douyin_first_request.py;运行 python douyin_first_request.py 会发起一次可能计费的请求。profile 与 posts 是独立选择,不会先后一起执行;这里使用 Model API POST 路由,不是历史目录的 GET 地址。

Python
import os
import requests


def first_request(task, sec_user_id, *, count=5, sort_type=0):
    if not isinstance(sec_user_id, str) or not sec_user_id.strip():
        raise ValueError("Supply a known sec_user_id, not a nickname or search keyword")
    if sec_user_id != sec_user_id.strip() or "://" in sec_user_id:
        raise ValueError("Pass the exact sec_user_id string, not a URL")
    if task == "profile":
        path, params = "user-profile", {"sec_user_id": sec_user_id}
    elif task == "posts":
        if type(count) is not int or not 1 <= count <= 20:
            raise ValueError("Choose an integer count from 1 to 20")
        if type(sort_type) is not int or sort_type not in (0, 1):
            raise ValueError("Use sort_type 0 for latest or 1 for hottest")
        path = "user-post-videos"
        params = {"sec_user_id": sec_user_id, "count": count,
                  "max_cursor": 0, "sort_type": sort_type}
    else:
        raise ValueError("Choose profile or posts")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(f"https://api.sandbase.ai/v1/api/douyin/app-v3/{path}",
            headers={"Authorization": f"Bearer {key}"}, json=params,
            timeout=(10, 90), allow_redirects=False)
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}; inspect before retrying")
        body = response.json()
    except ValueError:
        raise RuntimeError("SandBase returned invalid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Request failed; check run history before retrying") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase run did not complete; inspect status and error")
    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 object at outputs[0].data")
    # Observed in the selected endpoints' public reference samples.
    if type(payload.get("status_code")) is not int or payload["status_code"] != 0:
        raise RuntimeError("Douyin failed or omitted its success status")
    if task == "profile" and not isinstance(payload.get("user"), dict):
        raise RuntimeError("Missing user object; do not infer zero followers")
    if task == "posts":
        posts = payload.get("aweme_list")
        if not isinstance(posts, list) or any(not isinstance(item, dict) for item in posts):
            raise RuntimeError("Missing or malformed aweme_list; do not infer zero posts")
    return payload


if __name__ == "__main__":
    # Choose ONE request; change profile to posts for one first-page request.
    payload = first_request("profile", os.environ.get("DOUYIN_SEC_USER_ID"))
    print("Payload keys:", sorted(payload))

2026-11-08 查看这两个公开参考样本时,都能看到 status_code: 0;主页响应含 user 对象,作品响应含 aweme_list。这些是样本中的结构观察。helper 对缺状态、缺结构直接报错,不把它们变成一个“成功的空结果”;也不多拆一层供应商 data,不接受旧的 SandBase 顶层 output 兼容路径。

有效的空列表保持为空页,不能据此断言账号从未发布作品;缺粉丝数也保持缺失。代码只打印业务体键名,不做排序或比率计算。超时或失败后应先查运行记录,再决定是否重试,因为传输失败不能证明服务端没有执行。本轮只用受控响应做离线测试,没有取得新的在线创作者结果。

历史证据:2026-10-01

原实验组合了搜索、主页、分页与批量统计。以下保留当时的 run ID、截断响应和四张原图。原 Python 代码已逐字归档并记录哈希,其中的兼容信封、自动重试和缺失补零逻辑已过时,不是当前推荐接入路径。本轮只核对两个选定端点的契约,并验证上方单次请求 helper。

SandBase 抖音 API 目录页,列表中可以看到 multi-video-statistics,右侧选中的端点状态为 Available、Free(API Free Week 期间) 历史截图(2026-10-01):SandBase 上的抖音目录页。端点以 GET /apis/v1/douyin/... 的形式列出,其中有 app-v3/multi-video-statistics;右侧面板显示选中端点为 Available、Free。本教程调用的是 Model API 的 POST /v1/api/douyin/... 路由。截图摄于 API Free Week 期间,Free 是当时的标价;活动已结束,旧图不能证明当前资格或剩余额度。

历史账号发现

我搜的是“中国国家地理”。每页返回 30 个账号,带 has_more: true 和 cursor: 30。把这个 cursor 原样传回去就拿到第二页(run id 563bdc12-2bbc-403f-b918-a1b964306571 和 4b610646-336c-49b7-9f64-3b35cac0da98)。排第一的是杂志主账号,粉丝约 564 万。后面跟着它的几个子品牌(景观、频道、地道风物、探索),再往后夹着几个不相干的科普号。

这里有两个细节。

第一,字段名叫 user_id,值却是 MS4wLjABAAAA... 这种形式,也就是 app-v3 端点要的 sec_user_id,当时直接传给主页接口成功。

第二,参考页的描述说这个接口“支持按粉丝数和用户类型过滤”,但请求 schema 里只有 keyword 和 cursor 两个参数。没写进 schema 的过滤参数我没有传。这项历史观察不代表本次接入示例自动扩展到用户搜索。

SandBase 抖音 user-search-v2 端点 API 参考页 历史截图(2026-10-01):douyin/search/user-search-v2 的参考页:POST /v1/api/douyin/search/user-search-v2,参数是可选的 cursor(默认 0)和 keyword。文档里的响应示例中 outputs[0].data 是空的。

历史主页样本

杂志主账号这次的返回(run id 046c8eae-9a2c-411c-9914-3c8f5ed1f754):unique_id 是 zggjdl,粉丝约 564 万,获赞约 2,566 万,企业认证为《中国国家地理》杂志社有限公司。

作品数和搜索结果对不上:主页的 aweme_count 是 538,搜索里的 publish_cnt 是 545。之前试的那个新闻账号差得更多,大约 12,300 对 15,900。这两个来源字段不能直接当成同一个值;部分作品列表也不能证明账号的精确总量。

历史作品列表

当时参考的说法是:第一页 max_cursor 传 0,之后传上一页响应里的 max_cursor。历史实测也是这样,本轮没有复测续页。每页 20 条,has_more: 1,max_cursor 看起来是毫秒级时间戳,而每条作品的 create_time 是秒级。下面是第一页的节选(run id 28936f25-f639-471c-9f9b-1204e408db4c):

JSON
{
  "has_more": 1,
  "max_cursor": 1789444800000,
  "aweme_list": [
    {
      "aweme_id": "7690953381636017446",
      "desc": "【预告片】生命奇观2 川西山地 ...",
      "create_time": 1790740800,
      "is_top": 0,
      "statistics": {
        "play_count": 0,
        "digg_count": 845,
        "comment_count": 34,
        "share_count": 16,
        "collect_count": 43
      }
    }
  ]
}

这里返回 play_count: 0,不代表实际无人观看。下方历史统计样本里,其中一条作品返回了 70,966 次。应保留原值、来源与获取时间,同时标记含义尚未确认,不要直接用另一接口的值覆盖它。字段缺失又与返回零不同;两者都不能通过补零得到一个看似可靠的赞播比。

样本混有 aweme_type: 68 的条目,当时看起来像图文作品;这是观察,不是稳定的类型保证。旧截图未列 sort_type 取值,当前 Schema 已明确 0 最新、1 最热。

SandBase 抖音 app-v3 user-post-videos 端点 API 参考页 历史截图(2026-10-01):douyin/app-v3/user-post-videos 的参考页:必填 sec_user_id,可选 count(不超过 20)、max_cursor 和 sort_type。旧图没有列出 sort_type 取值;当前契约已说明 0 最新、1 最热。

历史统计对照

我跑的几次里,statistics_list 每个 id 对应一条,字段有 aweme_id、play_count、digg_count、share_count,有时还有 download_count。作品列表里播放量为 0 的那条图文,在这里查出来是 70,966 次(run id dc35d090-ba7a-4391-a4f4-da78349bc42b)。

关联时用字符串 id。两个接口返回的 aweme_id 都是字符串,这么长的数字也确实更适合当字符串用。

SandBase 抖音 app-v3 multi-video-statistics 端点 API 参考页 历史截图(2026-10-01):douyin/app-v3/multi-video-statistics 的参考页:只有一个必填的 aweme_ids 字符串,逗号分隔,最多 50 个。说明里写着抖音大多数接口已不再返回播放量。旧图中的“Price”是历史记录,不是当前报价或可用性检查。

历史汇总结果

2026-10-01,我把归档脚本原样跑了一遍,一共八次调用:搜索两次,主页一次,作品列表三次(1eca7db3-03b1-4af2-866b-30e69a24c249、3042978c-8207-4915-9fea-a6e6c5d17c1c、d4a0422d-d0d3-409a-b057-4e3600902272),统计接口两次,覆盖 60 条作品(c67a86e8-4129-4205-8790-fa4510bc1b2c、6ab3f851-f942-436f-8121-0fb222cb77fa)。

这 60 条覆盖了 2026 年 1 月初到 9 月底的作品,分布非常不均。前两名播放量分别约 9,040 万和 8,700 万,第三名约 1,143 万,而 60 条的中位数只有约 37 万。前五名的赞播比在 1.5% 到 4.1% 之间。

这些是历史样本,不能证明观众偏好或因果关系。赞播比需要可比、可用的计数和非零分母,否则保留未知;不再沿用旧代码把缺失填成零的排序方式。

原文“主页+三页作品+一次统计=五次”与其最多 50 个 ID 的条件矛盾:60 条作品需要两次统计,选定账号后共六次,加上当时两次搜索共八次。这是历史调用核算,不是当前价格或可用性承诺。批量统计、续页和模型归纳需要分别重新验证与预算,不在新示例中自动执行。

原实验的证据范围(2026-10-01)

项目状态
POST /v1/api/douyin/search/user-search-v2,参数 keyword、cursor参考文档已写明
POST /v1/api/douyin/app-v3/user-profile,参数 sec_user_id参考文档已写明
POST /v1/api/douyin/app-v3/user-post-videos,参数 sec_user_id、max_cursor、count参考文档已写明
POST /v1/api/douyin/app-v3/multi-video-statistics,参数 aweme_ids(最多 50 个)参考文档已写明
信封 id / status / model / outputs[0].data参考文档已写明
搜索 data.user_list[] 的 user_id(sec_user_id 格式)、nick_name、fans_cnt,以及 cursor、has_more仅实测观察
主页 user.unique_id、follower_count、total_favorited、aweme_count、enterprise_verify_reason仅实测观察
作品列表 aweme_list[].statistics、has_more、max_cursor;play_count 返回 0仅实测观察
统计 statistics_list[] 的 aweme_id、play_count、digg_count仅实测观察

不用一页样本制造排名

已知账号时,主页请求可以帮助你看清哪些字段可用;一页最新作品可以帮助选择值得细读的内容。记录账号标识、排序、条数与获取日期,不要把五条样本当成完整作品库,也不要把“最热”直接等同于按真实播放量排序。

展示指标之前,区分三个状态:接口实际返回的数字、缺失字段、请求或业务错误。历史零播放案例说明,返回零本身也可能需要解释。不要把缺失点赞数补成零,不要用不可用的分母计算比率,也不要通过选更大的数来假装解决来源差异。

常见问题

sec_user_id 从哪里来? 使用你已经核实的账号标识,昵称或数字 UID 不能替代。账号发现是独立任务,不在这里自动执行。

能选最新或最热吗? 能。当前作品契约中整数 sort_type 0 为最新,1 为最热。示例选择 count 五条、max_cursor 0,这些是请求范围,不是返回数量保证。

两个请求都免费吗? 两个选定端点基础价均为 $0.001,并符合组织每日 UTC 共享 100 次额度资格;剩余未查。本轮不对用户搜索和批量统计的当前免费资格作承诺。

play_count 为 0 就是没人看吗? 历史样本不支持这个结论。保留来源值与不确定性,字段缺失也不能当零;本教程不会自动追加其他端点来补数。

空页要自动重试吗? 不要自动重试。先检查运行和业务状态;成功空页也只是本次样本结果,不证明已经完整覆盖,更不等于可以不断重发。

任务超出已知账号首请求时,可参考 抖音 API 总览,重新核对下一端点与预算后再扩展。

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

觉得有用?分享给更多人