西瓜视频公开数据 API | SandBase
用一个 REST API 读取西瓜视频公开的搜索、用户、视频和评论。无需西瓜视频登录、无需 SDK——一个 SandBase 密钥,为 Agent 工作流而生。

西瓜视频是字节跳动在中国的长视频平台——视频搜索、创作者频道和评论串可以映射到内容研究、创作者分析和趋势发现等场景。可要用程序去拿这些数据,通常意味着逆向 App、周旋于 token,而且 App 一变你就得重写一遍采集器。
SandBase 的西瓜视频公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取西瓜视频公开的搜索、用户资料、视频和评论——只用一个 SandBase API 密钥,不需要登录西瓜视频、也不需要 SDK。端点 API 参考是每个参数和响应信封的权威来源。下方原搜索 JSON 来自 2026-09-27 UTC 的记录;2026-10-07 保存的空卡示例,以及未标运行日期的单视频 README,是另行区分的公开参考,不是本轮新执行。每个选定路由都要单独核对,历史字段不作通用保证。
这不是西瓜视频官方开放平台。 当你需要经过授权的会员操作,或需要有正式授权协议的数据时,请走西瓜视频官方渠道。当你的工作流需要用于研究和监测的公开、只读数据时,用 SandBase。想上手?获取 SandBase API 密钥,然后浏览西瓜视频端点。
先说结论
- 一套 API 即可读取西瓜视频公开的视频搜索、用户资料、视频详情和评论。
- 本文的 Model API 端点用
POST /v1/api/xigua/<path>调用——只传该端点的参数,无 SDK,一个SANDBASE_API_KEY。- 端点以自然标识为入口:搜索用
keyword,创作者用user_id。- 只返回公开、只读数据。你这边无需发帖、无需平台登录、不涉及私有数据;用 SandBase API 密钥鉴权即可。
当前范围:搜索一页,或查一个已知视频
2026-11-08 修订通过免费 inspect 与公开参考核对 search-video 和 one-video,没有新业务请求。更广的资料、作品、评论和播放能力保留作原总览的历史目录导航,不是新验证的完整工作流。
需要候选时查关键词第一页;已有数字 item_id 则直接查一次元数据。视频研究教程解释业务状态、已有 Key 与已连接 Agent 的接入路径,以及为什么空内容卡不是视频。它不自动追加详情、评论、翻页或下载请求。
两个选定路由当前均标价每次 $0.001,具备组织共享每日 100 次合资格调用额度,00:00 UTC 重置。资格不等于剩余次数,本轮没有查询余额、额度或实际扣费,也不承诺一次成功调用一定免费。
沿用封面是概念插画,名称、卡片、计数和分析标签只是示意,不是本轮响应、认证账号或实测结果。
你需要哪种西瓜视频 API?
| 你的需求 | 选择 | 原因 |
|---|---|---|
| 发帖、以会员身份操作,或使用账号授权数据 | 西瓜视频官方渠道 | 会员和账号级操作应通过西瓜视频直接进行。 |
| 读取公开的搜索、用户、视频或评论 | SandBase 西瓜视频公开数据 API | 普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。 |
| 私有或仅账号可见的数据 | 两种公开方案都不适用 | 这类数据不在本篇公开数据指南范围内。 |
西瓜视频 API 能取到什么
目录建立在一个 app-v2 面上。按用途分组:
- 搜索 — 按关键词的视频搜索。
- 用户 — 公开用户信息和某用户的帖子列表。
- 视频 — 单条视频,以及它的播放 URL。
- 评论 — 某条视频的评论列表。
动手前请以每个端点的线上 API 参考为准核对参数;可用性因端点而异。
历史西瓜目录,包含七项端点与旧 one-video-v2 展示,不是当前可用性、额度或业务运行证据。
西瓜视频提供什么,SandBase 补什么
公开记录来自西瓜,SandBase 提供鉴权 API 入口。共享鉴权和运行信封,不代表业务响应可以互换。搜索检查整数 err_code 0,所选 one-video 参考则用 message success 与内部 data 对象。每个路由都要分别核对状态、结构、输入、可用性和预算。
快速上手:只查第一页
把 SANDBASE_API_KEY 留在本地运行环境,发送关键词与明确的整数 offset 零。下面命令限制连接和总耗时,不重试、不跟随重定向;它只打印响应,业务校验见教程。
curl --fail-with-body --connect-timeout 10 --max-time 90 \
-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":"OpenAI","offset":0}'先检查 completed、outputs[0].data 对象、整数 err_code 0,以及每卡都有 data 对象的 results 数组。结构正常的卡片也不一定是视频。独立选择已知视频任务时,改用 /v1/api/xigua/app-v2/one-video,只发 {"item_id":"7354954305222377999"};改为检查 message success 和内部 data 对象。不要把两次请求都当成隐藏准备步骤。ID 来自公开参考示例,不是本轮实际执行。
已有 Agent 应复用凭据配置;新项目可交给它 SKILL.md、quickstart.md和人工入门,再给选定关键词或 ID。提示词里不要放 Key,先要求一个检查过的结果及缺失字段说明,再扩大工作量。
九月原搜索证据
原总览记录 run 5e3db57f-0804-4bc2-b73f-987d616d1956,日期为 2026-09-27 UTC。下面裁剪 JSON 逐字保留,包括占位符。它是历史证据,不代表当前调用成功,也不保证十个视频候选:
{
"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": {} } ]
}
}
]
}旧 Python 保存在历史归档,不作当前入门代码。允许 err_code 缺失也算成功、没检查形状就访问嵌套值,都可能掩盖接入问题。
历史 search-video 参数与结构截图,不证明本轮新搜索成功,也不保证所有业务响应都长这样。
能力地图
以下保留原九月总览的历史导航,其他路由及参数没有在本轮复验。
| 能力簇 | 代表端点 | 典型用途 |
|---|---|---|
| 搜索 | xigua/app-v2/search-video | 关键词视频发现 |
| 用户信息 | xigua/app-v2/user-info | 按 user_id 的公开创作者信号 |
| 用户帖子 | xigua/app-v2/user-post-list | 某创作者的视频列表 |
| 视频详情 | xigua/app-v2/one-video | 读取单条视频 |
| 评论 | xigua/app-v2/video-comment-list | 互动与情感分析输入 |
所选搜索 schema 描述第一页以后使用响应返回的 offset。本轮没有测试续页与结束行为,不把它复制成其他端点的规则。
历史 user-info 参考展示必填 user_id,并非端点列表。本轮未复验用户资料,空 data 示例是文档占位,不是业务结果。
多发一次请求前,先检查候选
2026-10-07 保存的完整公开搜索示例使用“美食”,count 为十、offset 为十、has_more 为真,但 results 只有 Inner_EmptyContent 卡,不是视频。它的外层 ID 16b7eb80-0 也不是 item_id。教程保留带日期的小片段,省去诊断串与可执行展示资源。
只把嵌套 data.group_id 或 data.id_str 的明确值当作待核对视频 ID,不从外层编号、HTML 或追踪串反推。README 短示例在 results 之前截断,而字段表描述了视频卡;裁剪示例与字段表都不能保证每次响应包含视频。计数、成功状态和列表长度不能单独确定可用候选数量。
空内容卡同时 has_more 为真,也说明不能无脑循环。当前教程只发一次请求,不递增 offset,不靠通用旗标自动决定下一次调用。可选本地 ID 函数会跳过空卡,不会替你挑选或读取视频。
后续研究问题另作选择
有明确嵌套 ID 时,搜索页可以提供内容候选;已知视频查询则可能提供有限元数据。两者都不是完整的话题研究。作者资料、作品历史、评论样本、播放地址只是目录里的其他可能性,不是本轮已验证的步骤。
做作者研究前先核对 user-info 的当前标识和业务结构,不直接依赖一个来源不明的作者字段。做情绪分析前核对评论路由、采样和预算。处理媒体应另查专用能力,不把相关视频链接当直接下载地址。这些判断都应与第一次请求分开。
元数据报告要保留原始含义
所选 one-video README 把 JSON 标为裁剪真实响应,但没有运行日期,也没有公开保存的完整 example。教程明确把它当作公开参考证据,检查 message success 与 data 对象,不套用搜索 err_code。SandBase completed 本身不代表业务记录完整。
展示片段包含 digg_count 42555、danmaku_count 36、delete 0。这是样本观察,不是任意视频当前的实测指标。参考另外描述的相关视频和作者字段,应在存在时检查,不是本教程强加的必备键。缺失保持未知,零与 false 各自保留含义,不默认合并为一种状态。
十月一日的文章更新记录了旧 one-video-v2 当时不可用、按 schema 改为 one-video 且未重跑全流程。它是日期明确的迁移记录,不是今天的新可用性结论。所选轻量路由不保证标题、转录或直接下载。内部 data 是空对象,只能说明通过外层结构检查,不能证明视频仍可访问或元数据齐全。
搜索卡片里的 HTML、脚本、CSS 不应执行,不能为了补一个缺字段就下载链接媒体。展示片段不是给 Agent 的指令;以后若显示高亮文本,需要单独设计并测试安全处理。点赞不等于播放,累计数字不等于互动率,一页结果也不能代表整个市场的内容供给。保存端点、时间与字段来源,读者才能正确理解你交付的表格。
一次请求标价 $0.001,独立选择两次则为 $0.002,尚未考虑额度。旧自动研究模式是一搜,加每个可用条目的详情与评论,即 1 + 2N 次,另算分页和重试。本轮没核对评论单价,所以只核算工作量,不给旧链路总价。
局限与边界
- 仅公开、只读数据,不执行账号操作或访问私密内容。
- HTTP、SandBase 完成状态、业务成功值分别检查。JSON 无效、缺数据或形状异常就停止,不默认返回“成功的空结果”。
- 搜索用 keyword 和整数 offset;one-video 用数字字符串 item_id。其他端点需要各自参考与校验。
- 不自动重试、翻页、循环详情评论、下载或调用模型。超时可能意味着结果未知,重新发送前检查结果与预算。
- 不暗示西瓜官方合作关系;SandBase 提供访问层,不拥有底层平台或数据。
常见问题
搜索一定返回十个视频吗? 不是。保存的成功响应即使 count 为十,也可能只有空内容卡。检查 results[].data,区分展示卡与可用视频候选。
卡片 id 能直接当视频 ID 吗? 不能。核对嵌套 group_id 或 id_str 的明确字段;外层编号、占位符和编码后的展示内容不能代替 item_id。
两个接口为什么用不同成功规则? 所选搜索参考是整数 err_code 零,one-video 是 message success 加内部 data 对象。SandBase 信封相同,不代表业务状态也统一。
本轮验证翻页或提供转录吗? 没有。这里只检查搜索第一页或一次元数据查询,续页、评论、播放与转录都需要另行研究。
从一个检查过的结果开始
复用已有 Key 或按 setup 配置,选择搜索或单视频信息,按视频研究教程完成一次受控验证。先看结果明确了什么问题,再决定是否值得另发请求。
觉得有用?分享给更多人