視頻反推提示詞 API 返回甚麼?用 Python 把 content 解析成可重用提示詞庫
视频反推提示词 API 返回什么?把 content 解析成可复用提示词库(Python 实战)
API 開放平台的「視頻反推提示詞」接口會以異步任務方式處理視頻連結,成功後以字符串形式返回 data.content,但官方沒有規定其內部格式。文章示範用 Python 輪詢任務並防禦式解析內容,將原文保留、嘗試識別 JSON,失敗時再按段落分類,並以指紋去重及存入 SQLite。
简介: 面向AIGC开发者,提供短视频链接→反推提示词→结构化资产的完整链路。支持curl/Python/Node.js调用,含防御式解析、指纹去重、SQLite落库方案,将非结构化`data.content`转化为可检索、可复用、可长期迭代的提示词资产。(239字)
面向 AIGC 与内容工程开发者:从一条短视频分享链接出发,拿到反推提示词,并把一段不保证格式的
data.content变成可检索、可去重、可复用的结构化提示词资产。含 curl / Python / Node.js 可运行代码。
API 开放平台 的「视频反推提示词」接口,把短视频分享链接或公网视频直链交给模型,反推出画面、镜头、光影描述与可复用的视频生成提示词。开发者常说的「短视频反推」「视频转提示词」「爆款视频拆解」,在平台接口目录里对应的就是这一个接口。本文解决的是接入后半段最容易被忽略的问题:任务成功之后,返回的 data.content 到底是什么结构,怎么把它变成能长期复用的资产。
一、先消歧:没有独立的「短视频反推」接口,对应的是 doc/60
在视频类接口目录中,唯一的反推类接口是「视频反推提示词」,官方文档为> 。它和下面几个容易混淆的能力是分开的:
| 你可能想做的事 | 对应接口 |
|---|---|
| 反推画面、镜头、光影、可复用生成提示词 | 视频反推提示词 https://xiaoapis.com/doc/60(本文) |
| 把分享链接解析成标题、封面、直链、作者 | 全平台链接元数据解析 https://xiaoapis.com/doc/43 |
| 提取口播/字幕文本 | 短视频提取文案解析 https://xiaoapis.com/doc/28 |
| 把长视频切成高光片段 | AI 视频切片 https://xiaoapis.com/doc/7 |
一句话:反推的是"怎么拍/怎么生成",不是"视频里说了什么",也不是"把视频文件拆开"。 三者经常串在同一条流水线里,但输出结构和计费口径完全不同。
二、结论先行:异步任务,结果是一个字符串
| 项目 | 官方口径 |
|---|---|
| 接口地址 | POST https://xiaoapis.com/api/video/prompt |
| 请求体 | application/json 或 application/x-www-form-urlencoded,参数放在请求体里;只接受 POST |
| 鉴权 | 请求参数 key(平台 API 密钥) |
| 任务模型 | 异步;同一地址支持创建与查询,创建后立即返回 task_id |
| 结果获取 | notify 回调(终态后 POST JSON,只推一次)或用 task_id 轮询;查询不扣费 |
| 轮询建议 | 官方建议间隔 3~5 秒,直到 status 为 1 或 2 |
| 关键返回字段 | data.content(string,反推提示词,成功时有值)、data.duration、data.power_cost、data.fail_reason |
status |
0 处理中 / 1 成功 / 2 失败 |
| 单条上限 | 最长处理 10 分钟,maxDuration 默认 600、最大 600 |
| AI 可读文档 | https://xiaoapis.com/model/video/prompt.md |
最需要注意的一点:官方 AI Markdown 文档把 data.content 定义为 string「反推提示词。成功时有值」,并没有规定它的内部格式——没说是 JSON,没说有分镜数组,也没承诺固定的字段或小标题。所以任何把 data.content 直接当 JSON 反序列化的代码都是脆弱的。这是本文要解决的工程问题,下面所有结构化逻辑都属于调用方自己的约定,不是接口承诺。
三、请求参数(官方原文口径)
| 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|
key |
是 | string | 平台 API 密钥 |
videoUrl |
创建时必填 | string | 分享链接、带链接的口令,或视频直链;兼容 url、content、link |
maxDuration |
否 | int | 最多处理多少秒,默认 600、最大 600;预扣按这个上限计算 |
notify |
否 | string | 完成后 POST JSON;兼容 callbackUrl、callBackUrl |
task_id |
查询时必填 | string | 创建返回的任务号;兼容 taskId;只传任务号时按查询处理 |
action |
否 | string | create(默认)或 query |
请求 HEADER 的 Content-Type 为 application/json 或 application/x-www-form-urlencoded。
最简调用(密钥走服务端环境变量,不写进代码与前端):
export XIAOAPIS_KEY='控制台申请的密钥'
curl -X POST "https://xiaoapis.com/api/video/prompt" \
-H "Content-Type: application/json" \
-d "{\"key\":\"$XIAOAPIS_KEY\",\"videoUrl\":\"https://v.douyin.com/xxxx\",\"maxDuration\":180,\"action\":\"create\"}"
# 拿到 task_id 后查询(查询不扣费)
curl -X POST "https://xiaoapis.com/api/video/prompt" \
-H "Content-Type: application/json" \
-d "{\"key\":\"$XIAOAPIS_KEY\",\"action\":\"query\",\"task_id\":\"$TASK_ID\"}"
创建成功的官方返回示例:
{
"code": 200,
"msg": "任务创建成功",
"data": {
"task_id": "vp_a1b2c3d4e5f67890",
"status": 0,
"schedule": "PROCESSING",
"max_duration": 600,
"power_cost": 100,
"power_prepaid": 100,
"billing": "已预扣。完成后按实际时长结算:不超过 60 秒 10 点,超过则每分钟 10 点向上取整,差额退回"
}
}
四、拿到结果:Python 创建 + 轮询(标准库零依赖)
# prompt_client.py —— python3 prompt_client.py
import json
import os
import time
import urllib.request
ENDPOINT = "https://xiaoapis.com/api/video/prompt"
def _post(payload: dict, timeout: int = 30) -> dict:
payload = {
**payload, "key": os.environ["XIAOAPIS_KEY"]}
req = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Content-Type": "application/json", "Accept": "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: str, max_duration: int = 180) -> str:
body = _post({
"action": "create", "videoUrl": video_url,
"maxDuration": max_duration})
if body.get("code") != 200:
raise RuntimeError(f"创建失败 code={body.get('code')} msg={body.get('msg')}")
return body["data"]["task_id"]
def fetch_content(task_id: str, interval: int = 4, max_wait: int = 660) -> dict:
"""status: 0 处理中 / 1 成功 / 2 失败;查询不扣费,但仍要设总超时。"""
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
body = _post({
"action": "query", "task_id": task_id})
if body.get("code") != 200:
raise RuntimeError(f"查询失败 code={body.get('code')} msg={body.get('msg')}")
data = body.get("data") or {
}
if data.get("status") == 1:
return data # 含 content / duration / power_cost
if data.get("status") == 2:
raise RuntimeError(f"任务失败:{data.get('fail_reason', '未知原因')}")
time.sleep(interval)
raise TimeoutError(f"task_id={task_id} 超时未进入终态")
五、核心:content 的防御式解析
假设格式是接入事故的主要来源。稳妥做法分三层:先原样留存、再探测、最后降级。
- 无论解析成功与否,
raw_content全文落库——解析规则可以事后重算,原文丢了就找不回来; - 尝试 JSON 探测(
json.loads),成功则把对象/数组按已知键归一化; - 失败则按分段标题、编号行、空行切分,再用关键词把段落归入自定义维度;全部匹配不上就整段放进
other,绝不丢内容。
下面的维度(镜头 / 构图 / 光影 / 运镜 / 风格 / 负面词)是本文为演示定义的调用方 schema,不是接口返回字段,也不代表模型一定按这些维度输出。
# structure_content.py
import hashlib
import json
import re
from dataclasses import dataclass, field, asdict
# 调用方自定义维度 -> 中文/英文关键词,命中即归类
DIMENSION_RULES = {
"shot": ["镜头", "景别", "特写", "近景", "远景", "shot", "close-up"],
"light": ["光影", "光线", "逆光", "柔光", "色调", "lighting", "light"],
"camera": ["运镜", "推镜", "拉镜", "摇镜", "跟拍", "camera", "pan", "zoom"],
"style": ["风格", "画质", "质感", "胶片", "赛博", "style", "cinematic"],
"subject": ["主体", "人物", "画面", "场景", "subject", "scene"],
"negative": ["避免", "不要", "负面", "negative"],
}
HEADING = re.compile(r"^\s*(?:#{1,4}\s*|【|[((]?\d+[))]?[.、:]|[一二三四五六七八九十]+[、.])\s*")
# 「风格:xxx」这类中文标签行:保留标签词本身,否则归类时丢失维度线索
LABEL = re.compile(
r"^\s*[【\[]?\s*(镜头|光影|运镜|风格|画质|主体|画面|场景|色调|构图|"
r"避免|负面|提示词|描述|subject|style|lighting|camera)\s*[】\]]?\s*[::]",
re.I,
)
@dataclass
class PromptCard:
task_id: str
raw_content: str
fingerprint: str
duration: int = 0
power_cost: float = 0.0
dimensions: dict = field(default_factory=dict)
segments: list = field(default_factory=list)
def _normalize(text: str) -> str:
return re.sub(r"\s+", " ", text).strip().lower()
def _try_json(text: str):
try:
parsed = json.loads(text)
except (ValueError, TypeError):
return None
# 只接受对象/数组,避免把纯数字字符串误当结构
return parsed if isinstance(parsed, (dict, list)) else None
def _split_segments(text: str) -> list:
parts = []
for line in text.splitlines():
line = line.strip()
if not line:
continue
if HEADING.match(line):
parts.append(HEADING.sub("", line).strip())
elif LABEL.match(line):
parts.append(line) # 独立成段,且保留「风格:」等标签词
elif parts:
parts[-1] += " " + line
else:
parts.append(line)
return [p for p in parts if len(p) > 1] or ([text.strip()] if text.strip() else [])
def build_card(task_id: str, data: dict) -> PromptCard:
raw = data.get("content") or ""
parsed = _try_json(raw)
if parsed is not None:
# 若模型返回结构化对象,扁平化为 "键: 值" 段落再走同一套归类
segments = [f"{k}: {v}" for k, v in parsed.items()] if isinstance(parsed, dict) \
else [str(x) for x in parsed]
else:
segments = _split_segments(raw)
dims = {
k: [] for k in DIMENSION_RULES}
dims["other"] = []
for seg in segments:
low = seg.lower()
hit = next((k for k, words in DIMENSION_RULES.items()
if any(w.lower() in low for w in words)), None)
dims[hit or "other"].append(seg)
return PromptCard(
task_id=task_id,
raw_content=raw,
fingerprint=hashlib.sha256(_normalize(raw).encode("utf-8")).hexdigest(),
duration=int(data.get("duration") or 0),
power_cost=float(data.get("power_cost") or 0),
dimensions=dims,
segments=segments,
)
if __name__ == "__main__":
# 调用方示例文本,仅用于演示解析,不是接口真实返回
demo = """1. 镜头:低角度中近景,主体居中
2. 光影:黄昏逆光,边缘轮廓光明显
3. 运镜:缓慢推镜,最后 2 秒定格
风格:电影感,低饱和暖调"""
print(json.dumps(asdict(build_card("vp_demo", {
"content": demo,
"duration": 42})),
ensure_ascii=False, indent=2))
这段代码的关键不是关键词表写得多全,而是任何输入都不会抛异常、也不会丢原文:JSON 走扁平化,文本走分段,全不匹配就整体进 other。模型输出格式变化时,你只需要改规则、重跑一遍 raw_content,不用重新调用接口、不用重复付费。
六、落库与去重:把一次性结果变成提示词库
同一条素材重复提交、不同素材反推出相同镜头描述,都会污染提示词库。用归一化文本的 SHA-256 做唯一键,配合 SQLite(零依赖):
# store.py
import json
import sqlite3
from structure_content import PromptCard
DDL = """
CREATE TABLE IF NOT EXISTS prompt_card (
fingerprint TEXT PRIMARY KEY,
task_id TEXT NOT NULL,
raw_content TEXT NOT NULL,
duration INTEGER,
power_cost REAL,
dimensions TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS idx_prompt_task ON prompt_card(task_id);
"""
def init(db_path: str = "prompt_library.db"):
con = sqlite3.connect(db_path)
con.execute(DDL)
return con
def save(con, card: PromptCard, source_url: str = "") -> bool:
"""返回 True 表示新增,False 表示命中重复。原文始终保留。"""
cur = con.execute(
"INSERT OR IGNORE INTO prompt_card "
"(fingerprint, task_id, raw_content, duration, power_cost, dimensions) "
"VALUES (?, ?, ?, ?, ?, ?)",
(card.fingerprint, card.task_id, card.raw_content, card.duration,
card.power_cost,
json.dumps({
"source_url": source_url, **card.dimensions},
ensure_ascii=False)),
)
con.commit()
return cur.rowcount > 0
def search(con, keyword: str):
return con.execute(
"SELECT fingerprint, task_id, raw_content FROM prompt_card "
"WHERE raw_content LIKE ? ORDER BY created_at DESC LIMIT 20",
(f"%{keyword}%",),
).fetchall()
Node.js 侧如果只做「取结果 → 存原文」,用内置 fetch 就够了(Node 18+):
// fetch-content.mjs —— XIAOAPIS_KEY=xxx TASK_ID=vp_xxx node fetch-content.mjs
const endpoint = "https://xiaoapis.com/api/video/prompt";
export async function queryPrompt(taskId) {
const res = await fetch(endpoint, {
method: "POST",
headers: {
"Content-Type": "application/json" },
body: JSON.stringify({
key: process.env.XIAOAPIS_KEY,
action: "query",
task_id: taskId,
}),
signal: AbortSignal.timeout(30000),
});
const body = await res.json();
if (body.code !== 200) throw new Error(`code=${
body.code} msg=${
body.msg}`);
const d = body.data ?? {
};
if (d.status === 1) return {
content: d.content ?? "", duration: d.duration ?? 0 };
if (d.status === 2) throw new Error(`任务失败:${
d.fail_reason ?? "未知原因"}`);
return null; // status 0:处理中,交给外层定时器继续轮询
}
const result = await queryPrompt(process.env.TASK_ID);
if (result) console.log(result.duration, result.content.slice(0, 200));
七、批量流水线的三个检查点
- 上游先用元数据解析补齐上下文。 用
/doc/43把分享口令转成title、author、platform、cover_url,作为提示词卡的标签一起入库;否则三个月后你只看到一段镜头描述,不知道它来自谁、哪个平台。 - 提交时显式设
maxDuration。 预扣按这个上限计算,处理 30 秒素材却用默认 600 提交,会占用不必要的在途点数(完成后多退少补)。批量任务还要按官方文档标注的频率限制做可配置节流,不要写死并发数。 - 失败要留痕。
status=2时记录fail_reason与task_id单独入队;status=0超过总超时(建议按单条最长 10 分钟再加余量)要告警,而不是无限轮询。查询不扣费,但无限轮询会占用连接与配额。
成本口径(官方规则):
| 情况 | 结算 |
|---|---|
| 时长 ≤ 60 秒 | 10 点 |
| 时长 > 60 秒 | 每分钟 10 点向上取整(61–120 秒 20 点,10 分钟 100 点) |
| 识别不到时长 | 按 10 点结算 |
| 提交时 | 按 maxDuration 预扣;直链能读到时长时按该时长预扣 |
| 完成后 | 按实际时长多退少补 |
失败 / 查询 / 500 |
失败退回全部预扣;查询不扣费;500 不扣费 |
接口目录页展示的是「低至 0.1 元/次」这类起价口径,不是固定报价;实际点数与价格以当前官方文档、控制台余额与账单为准。
八、错误码
| 业务码 | 官方说明 | 建议动作 |
|---|---|---|
200 |
创建成功或查询成功 | 存 task_id / 取 content |
400 |
参数错误、点数不足,或任务失败 | 校验 videoUrl、maxDuration 与余额,不盲目重试 |
403 |
认证失败,请检查 key |
检查服务端密钥配置 |
500 |
服务暂时繁忙,此类错误不扣费 | 有限次退避重试 |
九、两个使用场景
场景 1|爆款拆解沉淀成提示词库。 一批同赛道视频逐条提交反推,content 原文 + 结构化维度 + 上游元数据一起入库,按 light、camera 等维度检索。团队复用的是可检索的描述,而不是聊天记录里的几句"感觉这个光挺好"。
场景 2|画风一致性的批量复刻。 先用反推结果归纳出稳定的风格片段,再喂给视频生成流程做参考;指纹去重能避免同一段提示词被反复计数,保证风格库里每条都是真正有差异的样本。
合规提醒:接入方需自行确认对输入内容拥有相应权利,并遵守原平台条款与版权要求;接口提供的是技术解析/推理能力,不等于获得原作品的传播或转售授权。
十、FAQ
Q:短视频反推是哪个接口?和"视频提取文案"是一回事吗?
A:反推对应「视频反推提示词」/doc/60,产出画面、镜头、光影与生成提示词;「短视频提取文案解析」/doc/28 产出的是口播/字幕文本。接口地址、参数与计费都不同,可以串联但不要混用。
Q:data.content 是 JSON 吗?能直接 json.loads 吗?
A:官方文档只把它定义为 string「反推提示词。成功时有值」,没有规定内部格式。可以探测,但必须准备降级路径;本文第五节给的是防御式解析,不是格式承诺。
Q:怎么拿到结果?是同步返回吗?
A:异步。创建后立即返回 task_id,用 notify 回调或 task_id 轮询取终态;官方建议 3~5 秒间隔,查询不扣费。
Q:反推一条 2 分钟视频大概多少点数?
A:按官方规则,>60 秒按每分钟 10 点向上取整,121–180 秒约 30 点;提交时按 maxDuration 预扣、完成后多退少补。具体价格以控制台与账单为准。
Q:任务失败或解析失败会扣费吗?
A:官方写明失败退回全部预扣、查询不扣费、500 不扣费。但仍建议记录 fail_reason 与 task_id,便于对账。
Q:密钥能放前端直接调吗?
A:不能。key 只应放服务端环境变量或密钥管理系统,由后端代理转发;回调地址也只暴露在服务端。
來源:阿里雲開發者社區 AI · developer.aliyun.com