Video Script Audit

Video Script Audit（视频脚本审核）

概述

支持两条摄入链路，后端异步执行 12 维度结构化拆解：

调用流程：

链路1: submit(video_url) → poll(status) → result
链路2: media_upload → submit(oss_url) → poll(status) → result

任意一条链路固定计费 100 credits/次（submit）+ 链路2 额外 20 credits（media_upload），与视频时长无关。

脚本引用

异步任务生命周期

progress 字段语义：pending=0 / processing=50 / completed=100 / failed=0。不要根据 progress 判断终态，只能根据 status。

[禁止] progress: 100 但 status: processing 时报告"完成"。 必须等 status 实际变为 completed 后才能调 result 取数。

建议轮询间隔：10 秒。video_audit_poll.mjs 默认 interval=10、max_attempts=40，最多等 400 秒；超时后引导用户改用 video_audit_status.mjs 手动查询。

提交参数（video_audit_submit.mjs）

video_url 和 oss_url 二选一，不可同时为空，也不可同时传。参数名与后端 SubmitAuditTaskRequest 一致。

△ video_url 和 oss_url 必须恰好传一个：都不传或都传，后端 model_validator 都会拒绝。

已废弃的旧参数名

URL 白名单（链路1 强制）

只有以下三种格式会被接受，video_audit_submit.mjs 在提交前本地校验，后端 submit 也会二次校验：

常见不支持的形态（遇到这些不要提交，直接向用户要正确链接）：

[强制规则]

1. boolean 参数必须传 JSON boolean（true/false），不要传 "true"、1、0。
2. audit_mode 只接受 high / low，不要传 medium（后端已不支持）。
3. 一次只能审核一条视频；批量审核由调用方循环管理 task_id。
4. 同一视频重复 submit 会重复扣 100 credits/次，失败后查 error_message 而不是重新 submit。
5. 提交前必须核对上方 URL 白名单。 不匹配时禁止提交，直接把不支持的原因和正确格式告知用户并索取新链接。提交也会被拒（40004），但会白跑一次请求。

示例

# 链路1：最小参数
node ../../scripts/video_audit_submit.mjs '{"video_url":"https://www.tiktok.com/@creator/video/7648432916250250526"}'

# 链路1：带 Brief + benchmark 对比
node ../../scripts/video_audit_submit.mjs '{"video_url":"https://www.tiktok.com/@creator/video/123","brief":"给职场妈妈的 SLG 手游，5 分钟一局","audit_mode":"high","enable_benchmark":true}'

# 链路2：先上传，再审核（两步）
node ../../scripts/media_upload.mjs '{"file_path":"/path/to/draft.mp4"}'
# → 从响应里取 oss_url（不是 oss_key）: "https://oss.creativault.tech/media_ingestion/uploads/user@example.com/20260615_a1b2.mp4"
node ../../scripts/video_audit_submit.mjs '{"oss_url":"https://oss.creativault.tech/media_ingestion/uploads/user@example.com/20260615_a1b2.mp4","brief":"发布前自审","audit_mode":"high"}'

**提交响应**

```json
{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "estimated_time_seconds": 240
  },
  "meta": {
    "request_id": "req_abc123",
    "quota_remaining": 991,
    "credits_consumed": 100
  }
}

上传本地视频（media_upload.mjs）

链路2 专用。上传本地视频文件 → 公开桶，返回 oss_key。

node ../../scripts/media_upload.mjs '{"file_path":"/path/to/video.mp4"}'

响应

{
  "success": true,
  "data": {
    "oss_key": "media_ingestion/uploads/user@example.com/20260615_103000_a1b2c3d4.mp4",
    "oss_url": "https://oss.creativault.tech/media_ingestion/uploads/.../a1b2c3d4.mp4",
    "filename": "video.mp4",
    "size_bytes": 9969532
  },
  "meta": { "credits_consumed": 20 }
}

将返回的 oss_url（不是 oss_key）作为 video_audit_submit.mjs 的 oss_url 传入。oss_key 仅用于上传结果追踪，后端 submit 不接受它。计费 20 credits/次（与文件大小无关）。

状态查询（video_audit_status.mjs）

node ../../scripts/video_audit_status.mjs '{"task_id":"550e8400-e29b-41d4-a716-446655440000"}'

返回 status / progress / created_at / completed_at / error_message。状态查询本身不计费，但仍占用日 quota。

自动轮询（video_audit_poll.mjs）

# 轮询 + 自动取结果（推荐）
node ../../scripts/video_audit_poll.mjs '{"task_id":"550e8400-e29b-41d4-a716-446655440000"}'

# 长任务：把单次审核的轮询时长拉到 15 分钟
node ../../scripts/video_audit_poll.mjs '{"task_id":"xxx","interval":15,"max_attempts":60}'

# 只等终态，不自动取结果（result 由调用方控制）
node ../../scripts/video_audit_poll.mjs '{"task_id":"xxx","fetch_result":false}'

行为：

• 进度日志输出到 stderr（[轮询 N/M] 状态: ... | 进度: ...%），不污染 stdout JSON。
• 终态为 completed 且 fetch_result=true 时，stdout 输出完整 result JSON。
• 终态为 failed 或超时，stdout 输出 status JSON，进程退出码 1。
• 默认 400 秒覆盖大部分视频；显著超时（高峰期 / 大文件）应增大 max_attempts，不要默认推断"任务卡死"。

获取结果（video_audit_result.mjs）

node ../../scripts/video_audit_result.mjs '{"task_id":"550e8400-e29b-41d4-a716-446655440000"}'

响应结构（v2.1 含回填表扩展字段）

{
  "success": true,
  "data": {
    "task_id": "550e8400-...",
    "audit_result": {
      "storyboard": { "...": "..." },
      "viral_factors": { "...": "..." },
      "content_audit": { "...": "..." },
      "benchmark_comparison": { "...": "..." },
      "suggestions": [ "..." ],
      "scores": { "...": "..." },
      "confidence": { "...": "..." },
      "diagnosis_level": "average",
      "creator_metadata": {
        "nick_name": "Kirsten Gutierrez",
        "followers_cnt": 300800,
        "creator_type": "母婴达人",
        "creator_type_reason": "..."
      },
      "video_metrics": { "...": "..." },
      "hashtags": ["#momlife", "#babygear"],
      "content_type_label": "宝妈情绪消减",
      "content_type_reason": "视频聚焦宝妈日常疲惫与清洁焦虑...",
      "structured_analysis": {
        "scene_pain_point": "奶瓶清洗费时费力...",
        "filming_highlights": "用真实带娃场景+脏污特写...",
        "cta_highlights": ""
      }
    },
    "html_report_url": "https://oss.creativault.tech/video_audit/reports/20260612_073240_4a1f3840.html",
    "hashtags": ["#momlife", "#babygear"],
    "content_type_label": "宝妈情绪消减",
    "content_type_reason": "...",
    "structured_analysis": { "...": "..." }
  }
}

html_report_url 为客户级 HTML 报告的公开 URL（https://oss.creativault.tech/video_audit/reports/{ts}_{id}.html），无需鉴权可直接访问。任务正常完成后返回真实 URL；HTML 生成失败（极少数情况）时为 null，不影响 audit_result 主结果。

审核结果字段速查

原始 12 维度

v2.1 回填表扩展字段

飞书 12 维需求中的"评论区互动数据"目前后端尚未支持，遇到该需求时显式说明能力缺失，不要凭 viral_factors 其它字段编造。

关键评分字段

失败态处理（强制）

核心原则：success 字段只代表 HTTP 请求本身是否成功，不代表视频审核任务是否成功。

这条链路有三种失败，来源和读取字段都不同，任何一种都必须把失败原因原文告知用户：

[禁止] 只看外层 success 就当成功

// 这是一次「失败」的响应，不是成功
{
  "success": true,                  // ← 只说明状态查询这个 HTTP 请求成功了
  "data": {
    "status": "failed",             // ← 真正的任务状态在这里
    "error_message": "不支持的视频 URL（仅支持 TikTok / YouTube Shorts / Instagram Reels）: ..."
  }
}

[必须] 遵守的四条

1. 拿到任何响应，先看 data.status，再看外层 success。
2. data.status === "failed" 时，必须把 data.error_message 原文展示给用户。禁止只回复「分析失败」「处理出错」这类无信息量的话。
3. 脚本退出码非 0 时，禁止报告「任务处理中」或静默重试。必须先读 stdout / stderr 里的 error 字段，拿到原因再回复用户。
4. 脚本输出里若含 action_required 字段，按该字段要求执行。

失败呈现模板

❌ 视频审核未完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
失败阶段: {本地校验 / 提交 / 任务执行 / 轮询超时}
失败原因: {error 或 data.error_message 原文}
{如有 reason 字段，追加一行说明}
{如有 supported_formats，列出正确格式}

下一步: {向用户索取符合格式的链接 / 稍后重查 task_id / 充值}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

失败原因是后端唯一告诉用户「为什么没结果」的渠道。含糊掉它，用户只能看到扣了积分却没有报告。

错误码（视频审核专属）

同一个 code 在不同端点语义不同，必须按调用的端点判断：

任务阶段失败原因（data.error_message）

这些不是错误码，是 worker 执行过程中的失败，只能从 error_message 读取：

遇到不在上表的 error_message，原文透传给用户，不要归类成「未知错误」后丢弃原文。

通用错误码（40101 / 42901 / 50001 等）见 references/error-codes.md。

推荐工作流

链路1：单条已发布视频审核（最常见）

# 1. 提交（拿 task_id）
node ../../scripts/video_audit_submit.mjs '{"video_url":"https://www.tiktok.com/@creator/video/123","enable_benchmark":true}'

# 2. 轮询并自动取结果（推荐）
node ../../scripts/video_audit_poll.mjs '{"task_id":"<上一步返回的 task_id>"}'

链路2：发布前本地视频自审（两步）

# 1. 上传本地视频 → 公开桶（20 credits）
node ../../scripts/media_upload.mjs '{"file_path":"/path/to/draft.mp4"}'
# 输出中拿 oss_url，如: "https://oss.creativault.tech/media_ingestion/uploads/user@example.com/20260615_a1b2.mp4"

# 2. 提交审核（100 credits），传 oss_url
node ../../scripts/video_audit_submit.mjs '{"oss_url":"https://oss.creativault.tech/media_ingestion/uploads/user@example.com/20260615_a1b2.mp4","brief":"发布前自审","audit_mode":"high"}'

# 3. 轮询取结果
node ../../scripts/video_audit_poll.mjs '{"task_id":"<step 2 返回的 task_id>"}'

链路2 结果中 creator_metadata.status 和 video_metrics.status 均为 not_applicable——这是正常现象，上传素材天然没有社媒身份，不是数据缺失。

已有 task_id，只想拿结果

node ../../scripts/video_audit_status.mjs '{"task_id":"xxx"}'
# status=completed 后再取
node ../../scripts/video_audit_result.mjs '{"task_id":"xxx"}'

批量并发审核（v2.1 回填表需求）

后端单次只支持 1 条视频审核，Skill 侧通过 async/await 并发提交多条来实现批量审核。

并发策略（由 AI Agent 自主调度）：

并发实现要点：

1. 收集所有 URL → 同时 submit（Promise.all）
2. 收集所有返回的 task_id → 同时 poll（Promise.all，各自独立轮询）
3. 所有 completed 后 → 同时 fetch result（Promise.all）
4. 汇总结果 → 输出回填表

注意事项：

• 并发 submit 使用 Promise.all，不是串行 for 循环
• 每条视频独立 poll，不要等一条完成再提交下一条
• poll 超时（400s 默认）的 task 单独提示，不阻塞已完成的任务
• submit 失败（40201 积分不足 / 40001 参数错）单独提示，不影响其它
• 批量 submit 总积分消耗 = 100 credits × 视频数量

结果呈现

单条视频结果

向用户呈现已分析完毕的审核结果，包含 HTML 报告链接：

🎬 视频审核报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
基础信息
  达人: {creator_metadata.nick_name} ({followers_cnt} 粉)
  视频: {video_metrics.video_id} | 播放 {views_cnt} | 互动率 {interaction_rate}
  爆款等级: {viral_level} | 诊断: {diagnosis_level}
  内容类型: {content_type_label}

综合评分: {scores.overall_score}/10
  钩子 {hook_strength} | 节奏 {rhythm_design} | 卖点 {selling_point_delivery}
  亮点 {creative_highlight} | 转化 {conversion_guidance} | 制作 {production_quality}

Hook 拆解
  类型: {hook_analysis.hook_type} | 强度: {strength_score}/10
  口播首句: {hook_script}
  首屏画面: {first_frame_visual}

爆款因子
  痛点: {pain_point_targeting.targeted_pain_points[].description}
  情绪: {emotional_value.core_emotion} (共鸣 {resonance_score}/10)
  植入: 首次出现 {first_brand_appearance_time}s | 共 {brand_mention_count} 次

优化建议（按 P0 → P2）
  - [P0] {suggestions[i].problem_description} → {how_to_fix}
  - [P1] ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 HTML 报告: {html_report_url}
信息: 消耗 100 credits | request_id: {meta.request_id}

批量结果 → 回填表（飞书表格格式）

对批量审核或用户明确要求"回填表"时，以飞书兼容的 markdown 表格输出以下字段：

| 平台 | 达人ID | 主页链接 | 达人类型 | 商单链接 | 内容类型 | 作品分析 | 结构拆解 | 核心标签 |
|------|--------|---------|---------|---------|---------|---------|---------|---------|

字段映射规则：

通用规则：

• 任务失败时不要套用上面的成功模板，改用「失败态处理（强制）」章节的失败呈现模板，并原文带上失败原因。
• 仅展示实际返回的字段，缺字段不要捏造（特别是 benchmark / brief_compliance 关闭时为空）。
• confidence.requires_human_review=true 时在报告顶部加显式提示。
• 任何 *_score 为 null 时跳过，不要替换为 0 或"未知"。
• 批量结果表格中，作品分析 和 结构拆解 字段较长时建议截取关键信息 + 标注"详见 HTML 报告"。
• 输出后主动询问是否需要：① 进一步解释某个维度；② 拉同账号其它视频对比；③ 把建议导出。

积分与 quota 规则（强制）

• meta.credits_consumed=100 仅出现在 submit 成功响应中；status / result / poll 不再扣费。
• meta.quota_remaining 是当天 OpenAPI 请求次数余量，不是积分余额。即使值很小或为 0，也禁止解释为"积分不足"。
• 仅当后端返回错误码 40201 时才能提示"积分不足"。
• 40002（任务未完成）属于业务状态，不计入失败重试，应继续等待，不要中断流程。

与其它子 skill 的衔接

References

• API Reference
• Error Codes