VOD 精准擦除

将视频/音频上传至 BytePlus VOD 存储空间（来源为本地文件或公开 URL），并返回一个 vid://… 引用。对于已存在于 VOD 中的媒体，提交精准擦除任务（StartExecution → Operation.Task.Type: Erase），且仅使用自动 OCR。请不要向终端用户说明其可切换擦除模式（手动 / 自动）——本能力始终发送 Auto 模式。NewVid 始终为 true（不作为用户可选配置项暴露）。

产品范围

不支持：Manual 模式、自定义比例的 Locations、对 SubtitleFilter 超出 {} 的调优、VideoOption.EncodeMode、覆盖 NewVid 值。

精准擦除白名单：若遇到 HTTP 403 错误或“Permission denied”，请按 BytePlus VOD 要求说明白名单 / 工单流程。

前置条件

• 环境变量（必需；可选地在工作目录下放置 .env 文件 —— 脚本会自动加载）：
  • BYTEPLUS_ACCESSKEY — BytePlus Access Key
  • BYTEPLUS_SECRETKEY — BytePlus Secret Key
  • VOD_SPACE_NAME — VOD 存储空间名称
• 执行方式：示例中使用 uv run python …（若已安装依赖，也可直接运行 python scripts/…）。

工作流概览

上传流水线（本地文件）：
  [S1_APPLY]  ApplyUploadInfo → TOS 上传地址 + SessionKey
  [S2_TOS]    向 TOS 执行 PUT（直传或分块）
  [S3_COMMIT] CommitUploadInfo → Vid
  输出：{ Vid, Source, PlayURL, FileName, SpaceName, SourceUrl }

上传流水线（URL）：
  [S1_UPLOAD] 提交 URL 上传任务（UploadMediaByUrl）→ JobId
  [S2_POLL]   轮询 QueryUploadTaskInfo → Vid
  输出：{ Vid, Source, PlayURL, FileName, SpaceName, SourceUrl, JobId }

精准擦除流水线：
  [S3_ERASE]  提交 Erase 任务（StartExecution / Task.Type Erase）→ RunId
  [S4_POLL]   轮询 GetExecution → 输出 Erase.File（+ 可选 Erase.Info）
  输出：{ Status, SpaceName, VideoUrls[{ FileId, Vid, DirectUrl, Source, Url }], EraseMeta? }

快速自检（推荐）

运行任意脚本前，请确认：

• .env 文件或环境变量中包含 BYTEPLUS_ACCESSKEY、BYTEPLUS_SECRETKEY 和 VOD_SPACE_NAME。

根据用户意图选择对应流水线：

S1_UPLOAD & S2_POLL：上传并获取 Vid

调用约定

请从 Skill 根目录（byted-byteplus-vod-precision-erasure/）执行：

# 本地文件上传（完成后返回 Vid）
uv run python scripts/upload.py "/path/to/video.mp4" [space_name]

# URL 上传（轮询直至返回 Vid）
uv run python scripts/upload.py "https://example.com/video.mp4" [space_name]

uv run python scripts/upload.py "https://example.com/sample.mp4" my_space

• 第一个参数：为本地文件路径或公共 http:// / https:// URL（自动识别）。
• 第二个参数（可选）：存储空间名称；若省略，则使用 VOD_SPACE_NAME。
• 路径与 URL 必须包含文件扩展名（例如 .mp4、.mov、.mp3）。

上传流程

本地文件（同步，三步）：

1. ApplyUploadInfo（API 版本 2023-01-01）→ 获取 TOS 地址与 SessionKey
2. 向 TOS 执行 PUT（直传适用于 < 20 MiB，否则分块上传）
3. CommitUploadInfo（2023-01-01）→ 返回 Vid

URL 拉取（异步 + 轮询）：

1. UploadMediaByUrl（2023-01-01）→ 返回 JobId
2. 轮询 QueryUploadTaskInfo 直至完成（轮询限制同关联技能：通常为 360 次 × 5 秒）
3. 返回 Vid

输出格式

成功时，标准输出为单个 JSON 对象，例如：

{
  "Vid": "v0d123abc",
  "Source": "vid://v0d123abc",
  "PlayURL": "https://example.cdn.com/xxx.m3u8",
  "PosterUri": "",
  "FileName": "uuid-filename.mp4",
  "SpaceName": "my_space",
  "SourceUrl": "https://example.com/video.mp4",
  "JobId": "job-xxx"
}

• 请保留 Source（vid://…）供下游技能使用。

超时处理（URL 上传）

若 URL 轮询耗尽重试次数，标准错误输出 / JSON 中将包含类似内容：

{
  "error": "Polling timed out (360 attempts × 5s); the URL pull upload is still processing",
  "resume_hint": {
    "description": "The URL upload has not finished yet; retry with the command below",
    "command": "uv run python scripts/upload.py "" [space_name]"
  },
  "JobIds": "job-xxx",
  "State": "running"
}

S3_ERASE & S4_POLL：精准擦除

调用约定

请从 Skill 根目录（byted-byteplus-vod-precision-erasure/）执行：

# 默认：仅字幕、整段视频、启用 WithEraseInfo
uv run python scripts/precise_erase.py '{"type":"Vid","video":"v0310abc"}'

uv run python scripts/precise_erase.py '{"type":"Vid","video":"vid://v0d225gxxx"}' production_space

# 更广范围 OCR（字幕 + 其他屏幕内文字）
uv run python scripts/precise_erase.py '{"type":"Vid","video":"v0310abc","text":true}'

uv run python scripts/precise_erase.py @params.json

# 超时后恢复执行
uv run python scripts/poll_execution.py '' [space_name]

参数参考

请不要向用户提示 Manual 模式 或 NewVid 配置项。

智能体提示（自然语言）

需明确区分：仅字幕 vs 全部屏幕内文字；整段视频 vs 指定片段（skip / selected + clips）；以及用户是否需要区域级擦除遥测信息（with_erase_info）。请使用对话式表述 —— 除非用户主动询问实现细节，否则避免暴露原始 JSON 字段名。

输出格式

成功时，标准输出为单个 JSON 对象，大致如下：

{
  "Status": "Success",
  "SpaceName": "my_space",
  "VideoUrls": [
    {
      "FileId": "…",
      "Vid": "v0…",
      "DirectUrl": "path/to/output.mp4",
      "Source": "vid://v0…",
      "Url": "https://example.cdn.com/…"
    }
  ],
  "AudioUrls": [],
  "Texts": [],
  "EraseMeta": {
    "Duration": 57.099,
    "Info": {}
  }
}

当 with_erase_info 为 false 时，EraseMeta 为 {}。

• VideoUrls[0].Url：当该空间签名成功时，此 URL 可播放或下载。
• Source：若 API 返回新 Vid，优先使用 vid://…；否则使用 directurl://…。

超时处理（GetExecution 轮询）

与增强类技能采用相同模式：

{
  "error": "Polling timed out (360 attempts × 5s); the job is still processing",
  "resume_hint": {
    "description": "The job has not finished yet; resume polling with the command below",
    "command": "uv run python scripts/poll_execution.py '' [space_name]"
  }
}

环境变量

错误输出格式

所有失败均统一使用：

{"error": "error description"}

参考文档

• BytePlus VOD Python SDK
• 精准擦除参数参考
• API：ApplyUploadInfo（2023-01-01）
• API：CommitUploadInfo（2023-01-01）
• API：UploadMediaByUrl（2023-01-01）
• API：QueryUploadTaskInfo（2023-01-01）
• API：StartExecution（2025-07-01）
• API：GetExecution（2025-07-01）