西瓜视频公开数据 API | SandBase

西瓜视频是字节跳动在中国的长视频平台——视频搜索、创作者频道和评论串可以映射到内容研究、创作者分析和趋势发现等场景。可要用程序去拿这些数据,通常意味着逆向 App、周旋于 token,而且 App 一变你就得重写一遍采集器。

SandBase 的西瓜视频公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取西瓜视频公开的搜索、用户资料、视频和评论——只用一个 SandBase API 密钥,不需要登录西瓜视频、也不需要 SDK。端点 API 参考是每个参数和响应信封的权威来源。参考只保证信封本身;下面的业务载荷字段名来自我实际跑的一次搜索调用(测试于 2026-09-27,UTC),是示意性的、仅供观测——并非文档保证——所以请以真实响应为准核对,因为负载会随时间变化。

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

先说结论

• 一套 API 即可读取西瓜视频公开的视频搜索、用户资料、视频详情和评论。
• 本文的 Model API 端点用 POST /v1/api/xigua/<path> 调用——只传该端点的参数,无 SDK,一个 SANDBASE_API_KEY。
• 端点以自然标识为入口:搜索用 keyword,创作者用 user_id。
• 只返回公开、只读数据。你这边无需发帖、无需平台登录、不涉及私有数据;用 SandBase API 密钥鉴权即可。

你需要哪种西瓜视频 API?

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

西瓜视频 API 能取到什么

目录建立在一个 app-v2 面上。按用途分组:

• 搜索 — 按关键词的视频搜索。
• 用户 — 公开用户信息和某用户的帖子列表。
• 视频 — 单条视频、video-v2,以及它的播放 URL。
• 评论 — 某条视频的评论列表。

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

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

西瓜视频提供什么,SandBase 补什么

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

快速上手:第一次调用

SandBase 暴露不止一个 API 面。目录里可能把这个能力列成 GET /apis/v1/xigua/... 路径,但本文使用每个端点 API 参考上标注的 SandBase Model API POST /v1/api/xigua/... 路由。不要擅自改动 HTTP 方法或 URL——以你所选端点的参考为准,并在动手前于参考确认确切请求 body。

按关键词搜索视频:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/xigua/app-v2/search-video",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"keyword": "科技"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "西瓜视频请求未完成"))

# 在我的抓取里,负载报告了一个上游 err_code;参考并不保证这些业务字段,
# 所以防御式检查它,并对每条路径以真实响应核对。
payload = body["outputs"][0]["data"]
if isinstance(payload, dict) and payload.get("err_code") not in (0, None):
    raise RuntimeError("上游错误")
results = payload.get("results", []) if isinstance(payload, dict) else []
print(payload.get("count"), "条结果,has_more:", payload.get("has_more"))

curl -X POST https://api.sandbase.ai/v1/api/xigua/app-v2/search-video \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "科技"}'

参考只保证信封:一个 id、一个 status、model 名称,以及——在 completed 运行上——一个 outputs 数组,其唯一元素在 data 下承载数据。failed 或 timeout 的运行则带 error 而没有 outputs,所以读取 outputs[0].data 前先根据 status 分支判断。信封以下的一切都是示意性的、并非文档保证:在我的抓取里(搜索 run id 5e3db57f-0804-4bc2-b73f-987d616d1956,测试于 2026-09-27,UTC),负载报告了一个上游 err_code(0 表示成功),搜索则在 results 旁边给出 count、offset 和 has_more。参考的业务负载示例是刻意留空的,所以请把这些字段名当作仅供观测,防御式检查 err_code == 0,并在依赖它们之前对照你自己的真实响应核对:

{
  "id": "5e3db57f-0804-4bc2-b73f-987d616d1956",
  "status": "completed",
  "model": "xigua/app-v2/search-video",
  "outputs": [
    {
      "data": {
        "err_code": 0,
        "count": 10,
        "offset": 10,
        "has_more": true,
        "results": [ { "id": "…", "data": {} } ]
      }
    }
  ]
}

响应结构因端点而异,而且每个结果项会嵌套它自己的结构化负载——请检查一次真实响应,并逐端点确定精确的字段路径。

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

能力地图

能力簇	代表端点	典型用途
搜索	xigua/app-v2/search-video	关键词视频发现
用户信息	xigua/app-v2/user-info	按 user_id 的公开创作者信号
用户帖子	xigua/app-v2/user-post-list	某创作者的视频列表
视频详情	xigua/app-v2/one-video-v2	读取单条视频
评论	xigua/app-v2/video-comment-list	互动与情感分析输入

分页方式因端点而异——搜索返回一个 offset 和一个 has_more 标记;下一次请求把 offset 传回去。请查阅每个端点的结构。

西瓜视频端点列表的一角,在 app-v2 面上。

在 Agent 工作流中链式调用

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

1. 搜关键词。 用一个 keyword 调用 xigua/app-v2/search-video,再用返回的 offset 和 has_more 翻页。
2. 读创作者。 用从搜索里浮现出的 user_id 调用 xigua/app-v2/user-info,再调 xigua/app-v2/user-post-list 拿他们的视频。
3. 读评论。 调用 xigua/app-v2/video-comment-list 拿某条视频的互动输入。

每一步都返回相同的 { id, status, model, outputs } 信封;在我的抓取里内层负载还报告了一个 err_code,所以你的 Agent 可以按 status 分支、防御式检查 err_code,并在每一步复用同一段读 JSON 的代码。

常见用例

西瓜视频搜索 API 做视频发现

用一个关键词运行 xigua/app-v2/search-video 梳理某话题周边的视频,再用 offset/has_more 翻页。输入:一个关键词。输出:一个结果列表加分页字段。端点:search-video。

西瓜视频用户 API 做创作者研究

用 user_id 调用 xigua/app-v2/user-info 读取公开创作者,再调 xigua/app-v2/user-post-list 拿他们的视频。输入:一个 user_id。输出:用户记录和帖子列表。端点:user-info、user-post-list。

西瓜视频评论 API 做互动信号

读取 xigua/app-v2/video-comment-list 拿某条视频的评论串。输入:一个视频标识。输出:一个评论列表。端点:video-comment-list。

为什么放在 API 层来做

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

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

局限与边界

• 仅公开、只读数据。 不发帖、不关注、不涉及私有或仅账号可见的数据。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 等瞬时错误时按退避策略重试。
• 参数与结构随上游面而定。 搜索用 keyword;user_id 标识创作者;在我的抓取里上游用 err_code 报告状态(0 表示成功)、每个结果项嵌套它自己的结构化负载——这些业务字段不在参考保证之列。分页是每端点各自的;查阅每个端点的结构确定确切参数,并先看一次真实响应。
• 以线上参考核对端点。 可用性和字段可能变化;在依赖某个具体端点前先确认。
• 这不是西瓜视频官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守西瓜视频条款和适用规则。

常见问题

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

什么标识一次搜索或一个创作者? 搜索用 keyword,创作者用 user_id。你可以从一条搜索结果里浮现出 user_id。

为什么负载里有一个 err_code? 在我的抓取里,上游负载报告了一个 err_code(0 表示成功)——这是一个参考并不保证的业务字段。读其他字段前先防御式检查它,并用 .get() 读取每个结果项的嵌套负载,以真实响应核对。

分页怎么做? 搜索返回一个 offset 和一个 has_more 标记;下一次请求把 offset 传回去取下一页。请查阅每个端点的结构。

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

从视频搜索开始

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

• 获取 SandBase API 密钥
• 浏览西瓜视频端点
• 打开 search-video API 参考