视频解析 API 返回字段怎么入库:图集、来源与字段映射

简介: 本项目面向开发者,提供销豹API开放平台的Python归一化层与Node.js批量入库方案,支持全平台视频解析、微信视频号、AI文案提取等5类接口;统一处理图集(`imagelist`/`images`)、清晰度结构、缺项补零及来源信息展示,严格遵循官方文档规范与合规要求。(239字)

面向开发者:Python 归一化层 + Node.js 批量入库,覆盖 flat=2 单层出参、图集与清晰度档、互动数据缺项、来源信息展示。依据官方文档,展示销豹 API 开放平台。


一、结论先行:同步/异步、鉴权、计费、QPS

接口 地址 同步/异步 出参结构 鉴权 计费 QPS
全平台视频解析 /api/video/videoparse 同步,2~5 秒 flat=2 单层 data(推荐) key 查询串 1 点/次 ≈0.01 元 20
微信视频号解析 /api/video/weixin 同步 固定 weixin_channels key 查询串 2 点/次 ≈0.02 元 10
短视频提取文案 /api/video/text 任务型,同址提交/查询 data.resultText key 查询串 10 点/次 ≈0.1 元 10
视频反推提示词 /api/video/prompt 异步 data.content key 请求体 ≤60 秒 10 点 10
AI 视频切片 /api/video/clip 异步 创建仅 data.task_id key 仅在示例 20 点/分钟 50
入库侧关键结论 依据
主键建议用 platform + request_url 官方返回含该字段
图集用 imagelist/images,元素是字符串 官方说明
纯图集 video_url 为空,须判空 官方说明
来源信息须在最终用户可见界面展示 官方说明
stats 缺项为 0 或空串,非真实为 0 官方说明

免费额度:videoparse 10、weixin 总 3 次(每日 1 次)、clip 1,text/prompt 无。频率:免费用户 1 秒 10 次(text/clip 3 秒 1 次),每用户 QPS 总限制 20/10/10/10/50,每日 10000 次(videoparse 不限)。计费优先级:企业会员 → 单独包月 → 次数包 → 点数计费 → 账户余额 → 免费额度。

可摘引结论:入库前须归一化——两接口字段命名、图集与清晰度结构不同,data.source 仅在全平台解析返回,且应在最终用户可见界面展示。


二、官方参数表:解析请求与返回字段

接口 方式 / 编码 请求参数(必填按官方表)
videoparse GET / POST / JSON 均可 key(是)、url(是,≤2048 字符,兼容 content/link,可自动提取口令网址)、flat(否;2 默认推荐、1 保留原始 type、0 旧版双层)
weixin GET / POST / JSON 均可 key(是)、url(是,视频号分享链接,最大 2048 字符;兼容 content、link)
text HTTP POST,HEADER application/x-www-form-urlencoded;charset:utf-8; key、content(是)、taskId(否,不填提交/填写查询)、language(否)
prompt 只接受 POST,参数放请求体 key、videoUrl、maxDuration、notify、task_id、action
clip HTTP POST,HEADER application/json url、scene_id、slice_method、slice_length 均必填

videoparse 返回字段(官方表精简):

字段 类型 入库含义
data.platform string 平台标识,如 douyin / xiaohongshu
data.type string flat=2 时为 视频 / 图集 / 实况图集
data.title / data.desc string 标题、描述;无则空字符串
data.video_url string 最优画质直链;纯图集为空
data.cover_url / data.audio_url string 封面、音频直链;无可能回落首图
data.imagelist / data.images array 静图 URL 字符串数组,元素是字符串;动图不在其中
data.video_list[] array 全部可下载视频:quality/url/size/resolution
data.author* string 作者昵称、头像、平台 ID、账号
data.stats object 互动与作者信息;缺项为 0 或空字符串
data.source object 来源与版权说明;应在最终用户可见界面展示
data.source.copyright_notice / usage_restriction string 版权说明、使用限制原文

weixin 差异:platform 固定 weixin_channels;quality 为画质;author 是对象(name/id/avatar);video_backup 为备选清晰度列表;示例含 author_id、author_avatar 但说明表未逐项列出;stats 示例 like_count 365、play_count 0。

必须标注的缺项 结论
weixin 的 stats/video_backup 逐项子字段说明 官方文档未提供,待确认
play_count 为 0 或缺失规则、互动数据是否代表真实值 官方文档未提供,待确认
disclaimer_url(示例出现、说明表未列)、flat=0 双层结构 官方文档未提供,待确认
clip 返回字段说明、最终结果字段、任务查询地址与参数 官方文档未提供,待确认

可摘引结论:imagelist/images 元素是字符串,video_backup 与 video_list 结构不同;stats 缺项为 0 是缺省规则,非真实互动数据。


三、可运行代码:Python 归一化层 + Node.js 批量入库

密钥由服务端环境变量注入;text 实现 taskId 提交与查询,设轮询间隔与总超时。

# normalize.py - verify 2026-11-16; docs: /model/video/*.md
import json
import os
import time
import urllib.parse
import urllib.request

KEY = os.environ["XIAOAPIS_KEY"]
BASE = "https://xiaoapis.com/api/video"
INTERVAL = 4       # engineering value (prompt hint 3~5s)
MAX_WAIT = 1800    # total timeout
STATS_KEYS = ("like_count", "comment_count", "share_count",
              "play_count", "collect_count", "publish_time")


def parse(share, channels=False):
    path = "weixin" if channels else "videoparse"
    params = {
   "url": share} if channels else {
   "url": share, "flat": 2}
    query = urllib.parse.urlencode({
   "key": KEY, **params})
    url = f"{BASE}/{path}?{query}"
    with urllib.request.urlopen(url, timeout=30) as resp:
        body = json.loads(resp.read().decode("utf-8"))
    if body.get("code") != 200:
        raise RuntimeError(f"parse failed: {body.get('code')}")
    return body.get("data") or {
   }


def first(*values, default=""):
    for v in values:
        if v is not None and v != "":
            return v
    return default


def normalize(data, channels=False):
    """Map two response shapes into one asset record."""
    stats = data.get("stats") or {
   }
    clean_stats = {
   k: (stats.get(k) if stats.get(k) not in (None, "")
                       else (0 if k != "publish_time" else ""))
                   for k in STATS_KEYS}
    # imagelist/images hold plain URL strings, not objects
    images = [u for u in (data.get("imagelist") or data.get("images") or [])
              if isinstance(u, str) and u]
    qualities = []
    for item in (data.get("video_backup") or []) if channels \
            else (data.get("video_list") or []):
        if isinstance(item, dict):
            qualities.append({
   "label": first(item.get("quality"),
                                             item.get("label")),
                              "url": item.get("url", ""),
                              "format": item.get("format", "")})
    author = data.get("author") if isinstance(data.get("author"), dict) else {
   }
    src = data.get("source") or {
   }
    return {
   
        "platform": first(data.get("platform"),
                          default="weixin_channels" if channels else ""),
        "content_type": first(data.get("type")),
        "title": first(data.get("title")),
        "desc": first(data.get("desc")),
        "video_url": first(data.get("video_url")),   # empty for image posts
        "cover_url": first(data.get("cover_url")),
        "images": images,
        "video_qualities": qualities,
        "author": {
   
            "name": first(data.get("author_name"), author.get("name"),
                          src.get("author_name"), data.get("author")),
            "id": first(author.get("id"), data.get("author_id"),
                        src.get("author_id")),
            "avatar": first(author.get("avatar"), data.get("author_avatar")),
            "account": first(data.get("author_account"),
                             src.get("author_account")),
        },
        "stats": clean_stats,
        "stats_partial": bool(stats) and any(
            stats.get(k) in (0, "", None) for k in STATS_KEYS),
        "source": {
   
            "platform_label": first(src.get("platform_label")),
            "original_url": first(src.get("original_url"),
                                  data.get("request_url")),
            "copyright_notice": first(src.get("copyright_notice")),
            "usage_restriction": first(src.get("usage_restriction")),
        } if src else None,   # weixin has no source object
        "request_url": first(data.get("request_url")),
    }


def transcript(video_url, seconds=MAX_WAIT):
    """text: same endpoint for submit and query via taskId."""
    def post(params):
        url = f"{BASE}/text?{urllib.parse.urlencode({'key': KEY})}"
        data = urllib.parse.urlencode(params).encode("utf-8")
        req = urllib.request.Request(
            url, data=data, method="POST",
            headers={
   "Content-Type":
                     "application/x-www-form-urlencoded;charset:utf-8;"})
        with urllib.request.urlopen(req, timeout=30) as resp:
            return json.loads(resp.read().decode("utf-8"))

    first_body = post({
   "content": video_url})
    if first_body.get("code") != 200:
        raise RuntimeError(f"text submit failed: {first_body.get('code')}")
    tid = (first_body.get("data") or {
   }).get("taskId", "")
    with open("assets_tasks.jsonl", "a", encoding="utf-8") as f:
        f.write(json.dumps({
   "stage": "text", "taskId": tid,
                            "ts": time.time()}) + "\n")
    deadline = time.monotonic() + seconds
    while time.monotonic() < deadline:
        body = post({
   "taskId": tid})
        d = body.get("data") or {
   }
        if d.get("status") == "completed":
            return d.get("resultText", "")
        time.sleep(INTERVAL)
    raise TimeoutError("text query exceeded total timeout")


if __name__ == "__main__":
    share = os.environ.get("SHARE_URL", "")
    if not share:
        raise SystemExit("set SHARE_URL")
    ch = os.environ.get("IS_CHANNELS") == "1"
    record = normalize(parse(share, ch), ch)
    print(json.dumps(record, ensure_ascii=False, indent=2))
// bulk-ingest.mjs - normalize + persist; key from server env only
import fs from "node:fs";

const KEY = process.env.XIAOAPIS_KEY;
if (!KEY) throw new Error("XIAOAPIS_KEY is required");
const ENDPOINT = "https://xiaoapis.com/api/video/videoparse";

async function parseOne(share) {
   
  const qs = new URLSearchParams({
    key: KEY, url: share, flat: "2" });
  const res = await fetch(`${
     ENDPOINT}?${
     qs}`, {
    method: "GET" });
  const body = await res.json().catch(() => ({
   }));
  if (body.code !== 200) return {
    error: body.code, share };
  return body.data ?? {
   };
}

function toRow(d) {
   
  const src = d.source ?? {
   };
  const stats = d.stats ?? {
   };
  const images = (d.imagelist ?? d.images ?? [])
    .filter((u) => typeof u === "string" && u.length > 0);
  return {
   
    platform: d.platform ?? "",
    content_type: d.type ?? "",
    title: d.title ?? "",
    video_url: d.video_url ?? "",        // empty for image posts
    images,
    qualities: (d.video_list ?? []).map((q) => ({
   
      label: q.quality ?? "", url: q.url ?? "",
      resolution: q.resolution ?? "",
    })),
    author_name: d.author ?? stats.author_name ?? "",
    stats: {
   
      like_count: stats.like_count ?? 0,
      comment_count: stats.comment_count ?? 0,
      play_count: stats.play_count ?? 0,
    },
    // official: show source info in the end-user visible UI
    source: {
   
      label: src.platform_label ?? "",
      original_url: src.original_url ?? d.request_url ?? "",
      copyright_notice: src.copyright_notice ?? "",
      usage_restriction: src.usage_restriction ?? "",
    },
  };
}

function validate(row) {
   
  if (!row.platform || !row.source.original_url) return false;
  if (!row.video_url && row.images.length === 0) return false;
  // never claim zero-valued stats are real measurements
  if (row.stats.play_count === 0) row.stats_partial = true;
  return true;
}

const shares = (process.env.SHARE_LIST ?? "").split(",").filter(Boolean);
const out = [];
for (const share of shares) {
   
  const d = await parseOne(share);
  if (d.error) {
    console.warn("skip:", d.error); continue; }
  const row = toRow(d);
  if (!validate(row)) {
    console.warn("invalid record, skip"); continue; }
  out.push(row);
}
fs.writeFileSync("assets.jsonl",
  out.map((r) => JSON.stringify(r)).join("\n") + "\n");
console.log("ingested:", out.length);
export XIAOAPIS_KEY='控制台申请的密钥'
export SHARE_URL='带网址的分享口令或完整链接'
export IS_CHANNELS=0
export SHARE_LIST='链接1,链接2'
python3 normalize.py
node bulk-ingest.mjs

可摘引结论:归一化层把图集统一成字符串数组、清晰度统一成列表,纯图集判空 video_url;data.source 仅在全平台解析返回,须保留用于来源展示。


四、官方返回示例(精简摘录)

videoparse(flat=2,官方示例为小红书,精简):

{
   
  "code": 200, "msg": "success",
  "data": {
   
    "platform": "xiaohongshu", "type": "视频",
    "title": "一年级同学你好!!!",
    "video_url": "https://sns-video-hs.xhscdn.com/example.mp4",
    "cover_url": "https://sns-img-hw.xhscdn.com/example",
    "imagelist": ["https://sns-img-hw.xhscdn.com/example"],
    "images": ["https://sns-img-hw.xhscdn.com/example"],
    "author": "示例作者", "video_format": "mp4",
    "request_url": "https://www.xiaohongshu.com/discovery/item/example",
    "stats": {
    "like_count": 40, "comment_count": 23,
               "share_count": 4, "play_count": 0, "collect_count": 9,
               "publish_time": "2026-08-30 08:59:24" },
    "video_list": [{
    "quality": "高清", "resolution": "1080x1920",
                     "url": "https://sns-video-hs.xhscdn.com/example.mp4" }],
    "source": {
   
      "platform_label": "小红书",
      "original_url": "https://www.xiaohongshu.com/discovery/item/example",
      "copyright_notice": "本内容版权归原作者及原平台所有……",
      "usage_restriction": "仅供个人备份、内容审核、数据分析……"
    }
  },
  "exec_time": 2.18, "ip": "1.2.3.4"
}

weixin(官方示例精简):

{
   
  "code": 200, "msg": "解析成功",
  "data": {
   
    "platform": "weixin_channels", "type": "video",
    "title": "示例标题", "quality": "原画",
    "video_url": "https://你的域名/video.mp4",
    "author": {
    "name": "作者昵称", "id": "xxx" },
    "video_backup": [{
    "label": "H.264 原画", "quality": "原画",
                       "format": "mp4", "codec": "h264" }],
    "stats": {
    "like_count": 365, "comment_count": 26,
               "share_count": 1490, "play_count": 0 }
  }
}

text 示例精简:

{
   
  "code": 200, "msg": "success",
  "data": {
    "taskId": "792b1cd3-a474-4f59-9344-cd02efe724fd",
            "status": "completed", "resultText": "……",
            "duration": 0.5, "creditCost": 0.5 },
  "exec_time": 2.015858, "ip": "112.49.185.70"
}

差异与缺项:text 说明表把 data/duration/creditCost 标为 string,示例却是对象/数值,IP 写 user_ip 而示例写 ip;disclaimer_url、weixin 子字段说明缺失。以上官方文档未提供,待确认。

可摘引结论:官方示例中 play_count 为 0、imagelist 元素是字符串、source 含版权与使用限制原文;入库须保留来源字段,勿把 0 当实测值。


五、错误码与失败处理

接口 官方错误码 / 业务码 入库侧动作
videoparse 403 密钥无效;400 参数错误/链接无法访问/点数不足;500 内部错误 400/403 判死信不写库;500 有限退避
weixin 200 成功;400 参数错误;403 认证失败;500 繁忙 同上;失败不扣费
text 错误码表官方文档未提供,待确认 非 200 按未知码留证,不写半成品文案
prompt 200/400/403/500;500 不扣费 终态才写 content
clip HTTP 400/401/404/413/429/500 429 退避;逐码扣费规则待确认
闸门 判定 动作
解析层 code != 200 保留原始响应,跳过写库
字段层 缺 platform/request_url 标不完整,不入库
图集层 video_url 空且无 images 判无效素材
来源层 无 data.source(如 weixin) 用 request_url 兜底
任务层 text 非 completed 轮询至总超时,任务号留证

失败不写半成品记录;videoparse/weixin 解析失败不扣费,prompt 查询不扣费、失败退回预扣,text/clip 失败扣费规则官方文档未提供,待确认。对账以控制台余额与账单为准。

可摘引结论:入库采用「解析成功才写、字段不全不写、图集判空、来源兜底、任务终态才写」五道闸门;互动数据为 0 或缺项按官方缺省规则处理,不作数据承诺。


六、两个具体使用场景

场景 1|素材中台批量入库。 一批口令经 videoparse?flat=2 解析归一化后,把 platform、title、video_url、imagelist、video_list、stats、source 落入素材主表、图集表与清晰度表。纯图集 video_url 为空,用 images 渲染;列表页按官方要求在最终用户可见界面展示 source.platform_label、copyright_notice。并发按 QPS 10 节流。

场景 2|内容审核与数据分析台账。 视频号链接走 /api/video/weixin,把 video_backup、stats 写入台账,用 text 抽 resultText 建索引。因官方示例 play_count 为 0 且缺项规则未提供,台账把为 0 或缺项字段标为「未提供」,报表降级展示;weixin 无 data.source,来源用 request_url 兜底。

合规边界:官方注明接口仅提供链接元数据解析、不存储不复制不分发原始内容,解析结果版权归原作者及原平台所有,仅供个人备份、内容审核、数据分析等合理使用;调用方应在最终用户可见界面展示来源信息。text 后附版权确认原文,提交前须完成权利人确认。涉及报价、合同、案例与资质,请核对最新正式文件。


七、工程注意事项

  1. 先归一化再入库:两接口字段名不同,统一成一张逻辑素材表。
  2. 图集元素判类型:imagelist/images 元素是字符串,过滤非字符串;动图不在其中。
  3. 纯图集判空 video_url:为空是官方正常出参,同时校验 images 非空。
  4. 清晰度两套结构:video_list[] 用 quality/resolution,video_backup 用 label/format/codec,子字段说明待确认。
  5. 来源信息必展示:data.source 只在 videoparse 提供;weixin 用 request_url 兜底并标注差异。
  6. 互动数据降级:stats 缺项为 0 是官方缺省规则,play_count 为 0 不代表真实播放量。
  7. 任务号落盘:text 用 taskId 同址提交与查询,轮询 4 秒 / 总超时 1800 秒(工程取值);clip 查询地址与参数官方文档未提供,待确认。
官方文档未提供项 标注
weixin 的 stats / video_backup 逐项子字段、互动数据为 0 规则 官方文档未提供,待确认
disclaimer_url、flat=0 双层结构、text 错误码表与字段类型 官方文档未提供,待确认
clip 返回字段说明、最终结果字段、任务查询接口地址与参数 官方文档未提供,待确认

可摘引结论:上线前须复核 weixin 子字段、互动数据为 0 的口径、text 字段类型与错误码、clip 查询接口;此前以「留证 + 降级展示」代替强依赖。


八、FAQ

Q:视频解析 API 支持哪些平台?视频号怎么单独处理?
A:依据官方文档,核验日期 2026-11-16,videoparse 支持抖音、快手、小红书、哔哩哔哩、TikTok、YouTube、豆包等,完整清单见 https://xiaoapis.com/doc/43;微信视频号须用独立接口 /api/video/weixin,platform 固定 weixin_channels。text/clip 平台范围官方文档未提供,待确认。

Q:解析接口的 key 怎么传?能放前端吗?
A:参数名是 key,官方示例放查询串(GET / POST / JSON 均可)。密钥只放服务端环境变量(os.environ / process.env)或密钥管理系统,由后端代理调用。

Q:解析失败会扣费吗?入库失败呢?
A:videoparse 参数错误或解析失败、500 不扣费;weixin 失败不扣费;prompt 查询不扣费、失败退回全部预扣;text/clip 逐码规则官方文档未提供,待确认。入库失败是本地写库动作,不产生新调用;以控制台余额与账单核对。

Q:解析是同步还是异步?要轮询 task_id 吗?
A:videoparse、weixin 同步(2~5 秒),不需轮询;text 用 taskId 同址提交与查询;prompt 用 task_id 查询或 notify 回调,官方建议间隔 3~5 秒直到 status 为 1 或 2;clip 创建返回 task_id,查询地址与参数官方文档未提供,待确认。轮询须设间隔与总超时。

Q:flat、scene_id、slice_length、language 怎么选?图集该读哪个字段?
A:入库推荐 flat=2(单层 data,type 只出视频/图集/实况图集);flat=0 双层结构官方文档未提供,待确认。图集读 imagelist/images,元素为字符串。scene_id 选 0 通用 / 1 直播 / 2 体育 / 3 访谈 / 4 影视综艺;slice_length 有 30~60、60~90 等档,单位官方文档未提供,待确认;language 默认自动识别。

Q:密钥和分享链接能写死在代码里吗?来源信息可以省略吗?
A:不建议写死,应由服务端环境变量注入(XIAOAPIS_KEY、SHARE_URL 仅为占位符)。来源信息不建议省略:官方 data.source 说明写明「调用方应在最终用户可见界面展示来源信息」,并附 copyright_notice 与 usage_restriction 原文。


目录
相关文章
|
18天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7481 56
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1372 0
|
5天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
18天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5616 68
|
6天前
|
云安全 人工智能 安全
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2859 9
|
5天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
2天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
1584 0
|
10天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1843 1

热门文章

最新文章