西瓜视频研究 API 教程

一次查询西瓜搜索页或已知视频信息,区分空内容卡与真实候选 ID,逐层校验响应,不自动翻页或追加评论请求。

深色电影质感画面:一次西瓜视频搜索解析成一条视频和一条评论串,汇入 Agent 内核

西瓜搜索返回成功,不一定代表拿到了视频列表。本轮查看的公开保存示例写着 count: 10、has_more: true,但 results 里只有一个空内容卡,没有可用视频 ID。若 Agent 把卡片外层的 id 当成 item_id,下一次调用从输入开始就错了。

本文于 2026-11-08 依据免费 inspect 和公开参考修订,没有新业务调用。原先搜索、详情、评论的自动链路改成两个独立首请求。2026-09-27 UTC 的实验和 2026-10-01 的端点变更说明保留为历史;更多能力见西瓜 API 汇总。

先说结论

  • 搜索第一页发送 keyword 与整数 offset: 0,先检查嵌套卡片,再判断有没有候选。
  • 已知数字视频 ID 时直接向 one-video 传字符串 item_id,搜索卡片外层 ID 不是视频 ID。
  • 从 completed 的 outputs[0].data 读对象:搜索检查整数 err_code: 0,单视频检查 message: "success" 和内部 data 对象。
  • 搜索成功或轻量元数据接口,都不保证标题、转录、可下载视频或完整研究报告。

沿用封面是概念插画,其中虚构名称、1,250,000 搜索结果、623K 播放、1,243 评论和分析标签不是 API 测量。图里的搜索到评论链路是历史概念,不是当前一次请求的操作流程。

先选择你真正要做的一次查询

手上已有的输入选定接口本文请求参数
一个想调查的话题搜索视频keyword、整数 offset: 0
明确的数字视频 ID单视频信息字符串 item_id

搜索 schema 另有以秒为单位的整数 min_duration、max_duration,以及字符串 order_type。首次示例不发送这些筛选,不猜排序值,也不声称本轮验证了所有组合。当前 schema 的 offset 默认值为零,代码仍显式写出,方便看到第一页意图。

所选 one-video 是较轻的元数据接口,参考中还描述了相关视频信息。不能悄悄换成 one-video-v2、播放地址或评论路由,它们是独立能力与预算。SandBase Key 用于读取公开数据,不等于获得西瓜账号操作授权,也不能访问私密内容。

历史西瓜目录与端点导航 原教程端点截图作为历史导航保留,不证明当前可用性、价格或一次新调用成功,七项端点及 one-video-v2 列表均为历史展示。

从已有配置继续,不必重新开始

已有 Key,就在项目真正运行的环境或密钥管理工具里配置 SANDBASE_API_KEY。不要贴进提示词、文章、截图或提交记录。鉴权失败先检查该运行环境读到的配置,不让 Agent 自动另建账号。

Agent 已连接时,给它准确路由和一个明确任务:复用凭据、只请求一次、逐层检查、说明缺失字段。“研究这个话题”这样的宽泛指令,容易把空结果或不确定候选变成不断追加的请求。

新项目可把 SKILL.md 与 quickstart.md 交给 Agent,补一句:“查这个词的第一页,不查候选详情、不翻页、不读评论。”已知 ID 则选择单次元数据查询。人工快速入门解释配置方法。请在实际运行脚本的 Python 环境安装 requests。

一个请求,按端点检查业务状态

Python
import os
import re
import requests


def first_request(task, value):
    if task not in ("search", "video"):
        raise ValueError("Choose search or video")
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Supply a nonempty string")
    if task == "video" and not re.fullmatch(r"[0-9]+", value):
        raise ValueError("item_id must be a numeric string, not a card ID or URL")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    path = "search-video" if task == "search" else "one-video"
    params = {"keyword": value, "offset": 0} if task == "search" else {"item_id": value}
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/xigua/app-v2/{path}",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"HTTP {response.status_code}; inspect access and budget before retrying")
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Network request failed; no automatic retry") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase 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 outputs[0]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing business object at outputs[0].data")
    if task == "search":
        if type(payload.get("err_code")) is not int or payload["err_code"] != 0:
            raise RuntimeError("Search business status was not err_code 0")
        cards = payload.get("results")
        if not isinstance(cards, list) or any(
            not isinstance(card, dict) or not isinstance(card.get("data"), dict)
            for card in cards
        ):
            raise RuntimeError("Expected results array with nested data objects")
    elif payload.get("message") != "success" or not isinstance(payload.get("data"), dict):
        raise RuntimeError("Video business status or data structure was unexpected")
    return payload


def candidate_ids(search_payload):
    # Use only after first_request("search", ...); this makes no requests.
    found = []
    for card in search_payload["results"]:
        data = card["data"]
        if data.get("template_key") == "Inner_EmptyContent":
            continue
        ids = [data.get(name) for name in ("group_id", "id_str")]
        valid = {value for value in ids if isinstance(value, str) and re.fullmatch(r"[0-9]+", value)}
        if len(valid) == 1:
            value = next(iter(valid))
            if value not in found:
                found.append(value)
    return found


if __name__ == "__main__":
    result = first_request("search", "OpenAI")
    print("Returned fields:", sorted(result))

若查询已知视频,把最后赋值替换为 result = first_request("video", "7354954305222377999"),保留字段列表输出,不追加成第二次自动请求。此 ID 是公开参考原有示例,本轮没有重跑。

搜索之后可以在本地调用 candidate_ids(result) 检查候选,它不产生网络请求,也不读取外层 id。它只考虑 results[].data.group_id 或 id_str 里的数字字符串,跳过空内容卡;两项有效 ID 冲突时不选。去重之后仍只是一份待核对候选,不会替你挑人或继续调用详情。长得像 ID,也不证明相关性或当前可访问。

主函数保留原业务对象,不把缺字段改成零或“成功的空记录”。空 results 数组可以是正常结果;缺数组、嵌套 data 结构错误则明确停止。这些检查对应本轮选定的参考结构,不代表上游所有展示状态都一样;遇到变化应检查,不猜另一种信封兜底。

一个空内容卡,为什么值得单独说明

完整公开保存示例日期为 2026-10-07,关键词是“美食”。下面只保留相关值,省去追踪串、可执行展示代码和设备信息:

JSON
{
  "err_code": 0,
  "count": 10,
  "offset": 10,
  "has_more": true,
  "results": [
    {
      "id": "16b7eb80-0",
      "data": {"template_key": "Inner_EmptyContent"}
    }
  ]
}

外层 ID 标识的是展示卡片,不是嵌套业务字段里的明确视频 ID。这个卡片说明没有可用匹配内容,因此本样本应输出“没有可用候选”,不能因为 count 为十就说发现十个视频。汇总数字和数组长度都不能独立证明真实视频数量。

另一个查询的公开 README 短片段在 results 之前就截断了,不能据此判定完整响应一定缺 results。反过来,字段表描述了视频卡,也不意味着每次都有视频卡。解析器必须同时容纳“示例被裁剪”和“实际无匹配”这两种可能。

不要执行卡片里的 HTML、JavaScript、CSS 或 script 字符串来找缺失 ID,它们是展示材料,不是可靠数据字段的替代。以后若要显示带高亮标签的文字,需要另行设计可信的转义或清理流程;本教程不渲染这些内容,也不下载资源。

历史西瓜搜索参数参考 历史 search-video 参数截图。当前代码明确传 offset 零;图片不证明返回十个视频、有效 ID 或本轮翻页成功。

九月原实验仍按原日期保留

教程原搜索 run ID 为 07f62735-11c0-4394-997e-27da674651b9,记录于 2026-09-27 UTC。下面旧 JSON 逐字保留,包括示意占位符。它不是新的空卡保存示例,也不是十一月业务执行:

JSON
{
  "id": "07f62735-11c0-4394-997e-27da674651b9",
  "status": "completed",
  "model": "xigua/app-v2/search-video",
  "outputs": [
    {
      "data": {
        "err_code": 0,
        "count": 10,
        "offset": 10,
        "has_more": true,
        "results": [ { "id": "…", "data": {} } ]
      }
    }
  ]
}

旧文已经注意到结果项内部还嵌套业务载荷,但组合流程依赖一个没有实现的 extract_item_id,随后为每条接受的记录查详情和评论。新版本不会把占位符变成真实 ID,也不把这段历史摘录当成通用提取器的证明。

关于分页,schema 描述第一页以后使用响应返回的 offset。本轮没有执行续页或确认终止规则。尤其空内容保存样本仍然 has_more 为真,只按它不断循环,并不能回答是否有可用视频。因此当前代码没有自动翻页、固定增加 offset 或默认重试。

one-video 检查什么,不保证什么

单视频 README 将示例标为裁剪真实响应,但未提供运行日期,也没有公开保存的完整 example。本轮把它作为公开参考使用,不声称自己刚执行成功。下面最小片段只保留它展示的状态和三个观察值:

JSON
{
  "message": "success",
  "data": {
    "danmaku_count": 36,
    "delete": 0,
    "digg_count": 42555
  }
}

参考还描述了作者信息、分类和相关视频,它们应按实际返回检查,而不是被 helper 强制要求存在。内部 data 即使是空对象,也只是通过最外层结构检查,不表示取得完整、可用的视频记录。缺失值保持未知;明确出现删除或限制旗标时另行解释。

这里不能复用搜索的 err_code 规则。SandBase completed 后仍可能是业务失败;把“没有错误码”当成功,会掩盖这种失败。示例要求 message 精确为 success 且 data 为对象,不允许另一个无关状态字段覆盖失败消息。

digg_count 是观察到的点赞计数,不是播放量或互动率。相关视频链接不是转录,也不是直接下载地址。当前描述说明该路由信息少于旧详情变体,因此本文不保证标题。播放、字幕转录、评论或作者历史都需要独立核对能力与请求范围。

十月换端点的说明不能变成今天的结论

2026-10-01 的原更新记录:当时使用的 xigua/app-v2/one-video-v2 不可用,于是根据 schema 替换为 one-video,且未重跑整条链路。这解释了历史修改原因,不能当作旧路由今天仍下线的新证据。本轮直接选择当前公开的 one-video 参考,仍没有业务请求。

历史西瓜评论参数参考 原 video-comment-list 截图作为旧工作流证据保留。本轮未复验或调用评论,评论也不是读取元数据后的必做步骤。

预算和错误要分别看

两个选定端点当前均标价 每次 $0.001,具备组织共享每日 100 次合资格调用额度,00:00 UTC 重置。资格不等于余额或剩余次数,本轮没有查询额度、扣费或账户余额,不能承诺成功执行一定免费。

只选一个请求标价 $0.001;独立选择两次才是 $0.002,尚未考虑额度。旧链路是一次搜索,加每个有效视频两次调用,即 1 + 2N,还没算续页或重试。本轮没重新核对评论价格,因此这里只算调用数量,不提供旧完整链路的总价。

helper 区分 HTTP、SandBase 完成状态与业务状态。重定向、鉴权、权限、预算、限流、无效 JSON 或信封异常都会停止。超时的结果可能未知,所以不自动重试,避免把另一次调用悄悄算进去。错误信息不包含原响应正文、请求头或 Key。离线测试验证处理逻辑,不代表在线可用性或实时业务结果。

扩大任务之前先回答这些问题

count 十代表十个匹配视频吗? 不是。保存的空内容示例说明必须看嵌套候选,不能只信汇总标签。

可以把 results[0].id 当 item_id 吗? 不能,它可能只是卡片编号。可选本地函数只看文档描述的嵌套 ID 字段,产生的候选还要先核对,才考虑另发请求。

会返回标题、字幕或下载吗? 本文不保证这些输出,只验证搜索第一页或所选轻量元数据响应。其他能力需要独立核对。

原来的工作流在哪里? 代码逐字保留在历史归档,旁边提供分块哈希。它是旧实现证据,不是当前运行指引。先得到一个经过检查的结果,再从西瓜 API 汇总调查一个明确的后续任务。

觉得有用?分享给更多人