跳到正文
阿里雲開發者社區 AI·· 5 小時前AI 評分46

視頻反推提示詞 API 返回甚麼?用 Python 把 content 解析成可重用提示詞庫

视频反推提示词 API 返回什么?把 content 解析成可复用提示词库(Python 实战)

AI 導讀

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 的防御式解析

假设格式是接入事故的主要来源。稳妥做法分三层:先原样留存、再探测、最后降级。

  1. 无论解析成功与否,raw_content 全文落库——解析规则可以事后重算,原文丢了就找不回来;
  2. 尝试 JSON 探测(json.loads),成功则把对象/数组按已知键归一化;
  3. 失败则按分段标题、编号行、空行切分,再用关键词把段落归入自定义维度;全部匹配不上就整段放进 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));

七、批量流水线的三个检查点

  1. 上游先用元数据解析补齐上下文。 用 /doc/43 把分享口令转成 title、author、platform、cover_url,作为提示词卡的标签一起入库;否则三个月后你只看到一段镜头描述,不知道它来自谁、哪个平台。
  2. 提交时显式设 maxDuration。 预扣按这个上限计算,处理 30 秒素材却用默认 600 提交,会占用不必要的在途点数(完成后多退少补)。批量任务还要按官方文档标注的频率限制做可配置节流,不要写死并发数。
  3. 失败要留痕。 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