面向开发者:Python / Node.js 实现"枚举校验 → 创建 → 任务号落盘 → 间隔查询 → 总超时"。依据官方文档。
一、结论先行:同步/异步、鉴权、计费、QPS
| 能力 | 地址 | 结果获取 | 鉴权 | 计费 | QPS |
|---|---|---|---|---|---|
| 全平台视频解析 | /api/video/videoparse |
同步,2~5 秒 | key |
1 点/次 ≈0.01 元 | 20 |
| 微信视频号解析 | /api/video/weixin |
同步 | key |
2 点/次 ≈0.02 元 | 10 |
| 短视频提取文案 | /api/video/text |
taskId 提交/查询 |
key |
10 点/次 ≈0.1 元 | 10 |
| 视频反推提示词 | /api/video/prompt |
task_id 查询或 notify;查询不扣费 |
请求体 key |
≤60 秒 10 点,超期每分钟 10 点 | 10 |
| AI 视频切片(主) | /api/video/clip |
创建返回 task_id;查询地址待确认 |
?key=你的密钥 |
20 点/分钟 ≈0.2 元/分钟 | 50 |
| 项目 | 主接口官方口径 |
|---|---|
| 地址 / 方式 | https://xiaoapis.com/api/video/clip,HTTP POST,返回 application/json |
| HEADER | Content-Type: application/json |
| 任务模型 | 核心能力含「异步任务」「任务查询」;返回「任务创建成功」与 data.task_id |
| 鉴权 | 请求示例 ?key=你的密钥;参数表未列 key |
| 计费 | 按上传视频长度每分钟 0.2 元;参考价 0.2 元/分钟;20 点/分钟 |
| 免费额度 / 频率 | 1(单位待确认);50 QPS,免费/测试 3 秒 1 次,总 1 秒 50 次,每日 10000 次 |
| 准入 / 优先级 | 余额/点数用户不限每日次数与 QPS;企业会员 → 单独包月 → 次数包 → 点数计费 → 账户余额 → 免费额度 |
查询接口地址与参数、回调 notify 说明官方文档未提供,待确认;本文不推测地址,代码用可注入端点兜底。
可摘引结论:AI 视频切片是
/api/video/clip的 POST 异步创建接口,四参数必填、key在查询串、0.2 元/分钟、50 QPS;查询接口地址与参数、回调说明官方文档未提供,待确认。
二、官方参数表:三个参数决定切片效果
官方「请求参数说明」表只列 4 项,key、extension 不在表内。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
url |
string | 是 | https://xxx.mp4 |
可解析 HTTP URL;最长 512 字符;下载超时 5 分钟;必须带音频;5h / 4G;无扩展名需加 extension |
scene_id |
string | 是 | 0 |
场景 Id,指定视频类型 |
slice_method |
int | 是 | 0 |
切片方式 |
slice_length |
int | 是 | 30~60 |
切片大致长度,默认 30~180 |
| 枚举 | 官方取值 |
|---|---|
scene_id |
0 通用(默认)、1 直播、2 体育、3 访谈演讲、4 影视综艺 |
slice_method |
0 连续片段(默认)、1 智能拼接:合并多个片段成完整主题切片 |
slice_length |
30~60、60~90、90~120、120~180、180~300、300 |
slice_length 标为 int 但示例为区间文本,单位官方文档未提供,待确认;scene_id 为 string、slice_method 为 int,类型不要混用。
| 限制 / 缺项 | 结论 |
|---|---|
任务查询接口地址与参数、回调 / notify 说明 |
官方文档未提供,待确认 |
| 返回字段类型与含义、最终切片结果字段、状态字段 | 官方文档未提供,待确认 |
| 轮询间隔、结果有效期、取整规则、扣费时点 | 官方文档未提供,待确认 |
支持平台范围、slice_length 单位、免费额度 1 单位、extension 说明 |
官方文档未提供,待确认 |
key 类型 / 必填;401 文案的 X-API-KEY 与 key 关系 |
官方文档未提供,待确认 |
官方适用场景:长视频拆条、切片分发、二次剪辑。
可摘引结论:
scene_id五种场景、slice_method两种方式、slice_length六档区间,四参数全必填;查询接口、回调、结果字段与单位官方文档未提供,待确认。
三、可运行代码:创建 + 查询轮询(含间隔与总超时)
密钥由服务端环境变量注入。查询接口地址官方文档未提供,待确认,故端点不硬编码,未配置时只创建并留痕。
# clip_task.py — 依据官方文档,核验日期 2026-11-15
# Query endpoint and callback: not documented, injected via env.
import json
import os
import time
import urllib.parse
import urllib.request
CREATE = "https://xiaoapis.com/api/video/clip"
KEY = os.environ["XIAOAPIS_KEY"]
QUERY = os.environ.get("CLIP_QUERY_ENDPOINT", "")
SCENE = {
"通用场景": "0", "直播内容": "1", "体育赛事": "2", "访谈演讲": "3", "影视综艺": "4"}
METHOD = {
"连续片段": 0, "智能拼接": 1}
LENGTH = ("30~60", "60~90", "90~120", "120~180", "180~300", "300")
def post(url, payload, timeout=30):
req = urllib.request.Request(
url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers={
"Content-Type": "application/json"}, method="POST")
with urllib.request.urlopen(req, timeout=timeout) as resp:
return json.loads(resp.read().decode("utf-8"))
def create(video_url, scene="通用场景", method="连续片段", length="30~60", extension=None):
if scene not in SCENE or method not in METHOD or length not in LENGTH:
raise ValueError("enum mismatch")
if len(video_url) > 512:
raise ValueError("url too long")
payload = {
"url": video_url, "scene_id": SCENE[scene],
"slice_method": METHOD[method], "slice_length": length}
if extension: # 完整说明官方未提供,待确认
payload["extension"] = extension
url = f"{CREATE}?{urllib.parse.urlencode({'key': KEY})}"
body = post(url, payload)
if body.get("code") != 200:
raise RuntimeError(f"create failed: {body.get('code')} {body.get('msg')}")
tid = (body.get("data") or {
}).get("task_id")
if not tid:
raise RuntimeError(f"no task_id: {body}")
return tid
def save(tid, path="clip_tasks.jsonl"):
with open(path, "a", encoding="utf-8") as f:
f.write(json.dumps({
"task_id": tid, "ts": time.time()}, ensure_ascii=False) + "\n")
def poll(tid, interval=5, max_wait=3600, is_terminal=None):
"""5s / 3600s are engineering values; terminal fields not documented."""
if not QUERY:
raise RuntimeError("query endpoint not documented")
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
body = post(QUERY, {
"key": KEY, "task_id": tid})
save(tid)
if is_terminal and is_terminal(body):
return body
time.sleep(interval)
raise TimeoutError(f"task_id={tid} timeout {max_wait}s")
if __name__ == "__main__":
video = os.environ.get("CLIP_VIDEO_URL", "")
if not video:
raise SystemExit("set CLIP_VIDEO_URL")
tid = create(video, scene="访谈演讲", method="智能拼接", length="90~120")
print("task_id =", tid)
save(tid)
if QUERY:
poll(tid)
else:
print("query endpoint not documented; created and logged only")
export XIAOAPIS_KEY='控制台申请的密钥'
export CLIP_VIDEO_URL='带音频的公网视频直链'
# CLIP_QUERY_ENDPOINT 须向平台确认后再配置,本文不猜测
python3 clip_task.py
Node.js 做批量提交,按 50 QPS 保守节流并对 429 退避:
// clip-batch.mjs — query endpoint is not documented.
const ENDPOINT = "https://xiaoapis.com/api/video/clip";
const KEY = process.env.XIAOAPIS_KEY;
if (!KEY) throw new Error("set XIAOAPIS_KEY on server");
const SCENE = {
通用场景: "0", 直播内容: "1", 体育赛事: "2", 访谈演讲: "3", 影视综艺: "4" };
const METHOD = {
连续片段: 0, 智能拼接: 1 };
const LENGTH = ["30~60", "60~90", "90~120", "120~180", "180~300", "300"];
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function create(urlValue, opts = {
}) {
const {
scene = "通用场景", method = "连续片段", length = "30~60" } = opts;
if (!(scene in SCENE) || !(method in METHOD) || !LENGTH.includes(length)) {
throw new Error("enum mismatch");
}
if (urlValue.length > 512) throw new Error("url too long");
const url = `${
ENDPOINT}?key=${
encodeURIComponent(KEY)}`;
const res = await fetch(url, {
method: "POST", headers: {
"Content-Type": "application/json" },
body: JSON.stringify({
url: urlValue, scene_id: SCENE[scene],
slice_method: METHOD[method], slice_length: length }),
signal: AbortSignal.timeout(30000),
});
const body = await res.json();
if (body.code !== 200) throw new Error(`create code=${
body.code}`);
return body.data.task_id;
}
// 官方 50 QPS;保守间隔 + 429 退避
async function runBatch(items, gapMs = 100) {
const ids = [];
for (const item of items) {
let attempt = 0;
for (;;) {
try {
ids.push(await create(item.url, item.opts)); break; }
catch (err) {
if (!/429|timeout/i.test(String(err)) || attempt++ >= 3) throw err;
await sleep(2 ** attempt * 500);
}
}
await sleep(gapMs);
}
return ids;
}
const items = (process.env.CLIP_VIDEO_URLS ?? "").split(",").filter(Boolean)
.map((url) => ({
url, opts: {
scene: "访谈演讲", method: "智能拼接", length: "90~120" } }));
console.log(await runBatch(items));
可摘引结论:创建须做枚举与 512 字符校验,任务号必须落盘;查询用可注入端点、固定间隔与总超时,超时保留
task_id补查。
四、官方返回示例(精简摘录)
{
"code": 200, "msg": "任务创建成功",
"data": {
"id": 1, "task_id": "93e356ce-4b27-428c-ae6c-fe6815f23570" },
"exec_time": 0.418544, "ip": "112.49.185.124"
}
本页无返回字段类型表与含义表;最终结果、切片列表、状态与进度字段官方文档未提供,待确认。示例字段仅 code、msg、data.id、data.task_id、exec_time、ip,编排层只把 data.task_id 当创建凭据留痕。
可摘引结论:创建响应只含
code、msg、data.id、data.task_id、exec_time、ip,且官方未提供字段类型或含义,最终结果字段官方文档未提供,待确认。
五、错误码与失败处理
官方「HTTP 响应状态码说明」共 7 个码。逐码是否扣费,官方文档未提供,待确认;「只计 200 和 500」是监控计数口径,不是扣费规则。
| code | 官方含义 | 动作 |
|---|---|---|
| 200 | 请求成功 | 校验 data.task_id 并落盘 |
| 400 | 参数传递错误 | 回查四参数与枚举,不重试 |
| 401 | 认证失败,检查 X-API-KEY 或服务开通 | 查密钥与开通状态 |
| 404 | URL 或资源不存在,检查 URL 中 task id | 核对地址与任务号 |
| 413 | 文件超出大小限制 | 前置校验 5h / 4G,不重试 |
| 429 | 超出 QPS 限制 | 指数退避,压低并发 |
| 500 | 服务端异常 | 有限次退避并留证 |
| 层次 | 判断 | 动作 |
|---|---|---|
| 传输层 | HTTP 状态、超时、网络异常 | 有限次退避,保留原始响应 |
| 业务层 | code / msg |
按上表分流,未知码告警留证 |
| 任务层 | data.task_id 存在与否 |
缺失即终止;存在则落盘 |
取整规则、扣费时点与失败是否扣费官方文档未提供,待确认;小额验证并以账单核对,勿套用其他接口结论。
可摘引结论:官方给出 200/400/401/404/413/429/500 七个状态码但无逐码扣费规则;按三层分流,429 退避、4xx 不重试、500 留证,扣费以账单为准。
六、两个具体使用场景
场景 1|直播回放拆条。 2 小时回放切短片段分发:选 scene_id=1(直播)、slice_method=0(连续片段)、slice_length="30~60",保持时间连续便于回查。提交前校验 HTTP URL、带音频、512 字符与 5h/4G;task_id 落盘。查询地址官方文档未提供,待确认,当前只创建与留痕。
场景 2|访谈主题切片。 访谈适合 scene_id=3 配 slice_method=1(智能拼接),把同主题段落合成完整切片,用 slice_length="90~120" 控制长度,用于切片分发与二次剪辑。批量按 50 QPS 节流、429 退避。各场景效果对比数据官方文档未提供,待确认,先小样本评估。
合规边界:确认权利人授权并遵守原平台条款;分享链接素材可先用全平台视频解析取
data.source的来源与版权说明,并在最终用户可见界面展示。涉及报价、合同、案例与资质,请核对最新正式文件。