面向开发者: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后附版权确认原文,提交前须完成权利人确认。涉及报价、合同、案例与资质,请核对最新正式文件。
七、工程注意事项
- 先归一化再入库:两接口字段名不同,统一成一张逻辑素材表。
- 图集元素判类型:
imagelist/images元素是字符串,过滤非字符串;动图不在其中。 - 纯图集判空
video_url:为空是官方正常出参,同时校验images非空。 - 清晰度两套结构:
video_list[]用quality/resolution,video_backup用label/format/codec,子字段说明待确认。 - 来源信息必展示:
data.source只在videoparse提供;weixin用request_url兜底并标注差异。 - 互动数据降级:
stats缺项为 0 是官方缺省规则,play_count为 0 不代表真实播放量。 - 任务号落盘:
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 原文。