VOD precision erasure

Uploads video/audio to a BytePlus VOD space (from a local file or a public URL) and returns a vid://… reference. For media already in VOD, submits precision erasure tasks (StartExecution → Operation.Task.Type: Erase) using automatic OCR only. Do not tell end users they can change erasure mode between Manual and Auto — this skill always sends Auto. NewVid is always true (not surfaced as a user choice).

---

Product scope

Aspect	Behaviour
Input	Vid or DirectUrl (JSON field video)
Erasure coverage	Default subtitle only (Auto.Type: Subtitle, SubtitleFilter: {}). User may opt into all detected on-screen text via text: true or all_text: true → Auto.Type: Text.
Timeline	Default: whole video (no ClipFilter). Optional clip_filter with mode skip or selected — when either is used, clips is mandatory (non-empty).
Output asset	NewVid is always true — not configurable and not prompted.
Erasure metadata	Default with_erase_info: true (WithEraseInfo). If false, stdout EraseMeta is {}; VideoUrls are still populated when Erase.File is returned.

Not supported: Manual mode, custom ratio Locations, tuning SubtitleFilter beyond {}, VideoOption.EncodeMode, overriding NewVid.

Precision erasure allowlist: if you see HTTP 403 or “Permission denied”, explain allowlist / work order per BytePlus VOD.

---

Prerequisites

• Environment variables (required; optionally place a .env in the working directory — scripts load it automatically):
  • BYTEPLUS_ACCESSKEY — BytePlus Access Key
  • BYTEPLUS_SECRETKEY — BytePlus Secret Key
  • VOD_SPACE_NAME — VOD space name
• Execution: examples use uv run python … (python scripts/… works if deps are installed).

---

Workflow overview

Upload pipeline (local file):
  [S1_APPLY]  ApplyUploadInfo → TOS upload address + SessionKey
  [S2_TOS]    PUT file to TOS (direct or chunked)
  [S3_COMMIT] CommitUploadInfo → Vid
  Output: { Vid, Source, PlayURL, FileName, SpaceName, SourceUrl }

Upload pipeline (URL):
  [S1_UPLOAD] Submit URL upload job (UploadMediaByUrl) → JobId
  [S2_POLL]   Poll QueryUploadTaskInfo → Vid
  Output: { Vid, Source, PlayURL, FileName, SpaceName, SourceUrl, JobId }

Precision erasure pipeline:
  [S3_ERASE]  Submit Erase task (StartExecution / Task.Type Erase) → RunId
  [S4_POLL]   Poll GetExecution → output Erase.File (+ optional Erase.Info)
  Output: { Status, SpaceName, VideoUrls[{ FileId, Vid, DirectUrl, Source, Url }], EraseMeta? }

---

Quick Self-Check (recommended)

Before running any script:

• .env or env vars contain BYTEPLUS_ACCESSKEY, BYTEPLUS_SECRETKEY, and VOD_SPACE_NAME.

Pick the pipeline from user intent:

User intent	Pipeline	Entry script
Upload video to VOD	Upload	scripts/upload.py
Subtitle / on-screen text erasure	Precision erasure	scripts/precise_erase.py

---

S1_UPLOAD & S2_POLL: Upload and Obtain Vid

Calling convention

Run from the Skill root directory (byted-byteplus-vod-precision-erasure/):

# Local file upload (returns Vid when complete)
uv run python scripts/upload.py "/path/to/video.mp4" [space_name]

# URL upload (polls until Vid is returned)
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

• First argument: local file path or public http:// / https:// URL (auto-detected).
• Second argument (optional): space name; if omitted, VOD_SPACE_NAME is used.
• Paths and URLs must include a file extension (e.g. .mp4, .mov, .mp3).

Upload flow

Local file (synchronous, three-step):

1. ApplyUploadInfo (API version 2023-01-01) → TOS address, SessionKey
2. PUT to TOS (direct < 20 MiB, else chunked)
3. CommitUploadInfo (2023-01-01) → Vid

URL pull (async + poll):

1. UploadMediaByUrl (2023-01-01) → JobId
2. Poll QueryUploadTaskInfo until done (same limits as sibling skill: typically 360 × 5 s)
3. Return Vid

Output format

On success, one JSON object on stdout, e.g.:

{
  "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"
}

• Preserve Source (vid://…) for downstream skills.

Timeout handling (URL upload)

If URL polling exhausts retries, stderr / JSON includes something like:

{
  "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 \"<original URL>\" [space_name]"
  },
  "JobIds": "job-xxx",
  "State": "running"
}

---

S3_ERASE & S4_POLL: precision erasure

Calling convention

Run from the Skill root directory (byted-byteplus-vod-precision-erasure/):

# Default: subtitle-only, whole video, WithEraseInfo on
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

# Broader OCR (subtitle + other on-screen text)
uv run python scripts/precise_erase.py '{"type":"Vid","video":"v0310abc","text":true}'

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

# Resume after timeout
uv run python scripts/poll_execution.py '<RunId>' [space_name]

Parameter reference

Parameter	Type	Required	Description
type	string	✅	Vid or DirectUrl
video	string	✅	Vid or VOD FileName; vid:// / directurl:// stripped automatically
text	boolean	no	If true: Auto.Type: Text (more aggressive). Default false → subtitle-only.
all_text	boolean	no	Synonym for text (if both are set, text is applied first).
clip_filter	object	no	Omit = whole video. If set: mode skip or selected, and clips (non-empty list of { "start", "end" } seconds; Start/End accepted).
with_erase_info	boolean	no	Default true (WithEraseInfo). If false, detailed erase geometry is not requested; stdout EraseMeta is {}.

Do not prompt users for Manual mode or NewVid.

Agent prompting (plain language)

Clarify: subtitle-only vs all on-screen text; whole video vs segments (skip / selected + clips); whether they need region-level erase telemetry (with_erase_info). Use conversational labels — avoid exposing raw JSON field names unless the user asks for implementation details.

Output format

On success, one JSON object on stdout, roughly:

{
  "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": {}
  }
}

When with_erase_info was false, EraseMeta is {}.

• VideoUrls[0].Url: playable / downloadable when signing succeeds for the space.
• Source: prefer vid://… when the API returns a new Vid; else directurl://….

Timeout handling (GetExecution polling)

Same pattern as the enhancement skill:

{
  "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 '<RunId>' [space_name]"
  }
}

---

Environment Variables

Name	Description	Required
BYTEPLUS_ACCESSKEY	BytePlus Access Key	Yes
BYTEPLUS_SECRETKEY	BytePlus Secret Key	Yes
VOD_SPACE_NAME	VOD space name	Yes (or via CLI argument)
VOD_POLL_INTERVAL	Polling interval (seconds, default 5)	No
VOD_POLL_MAX	Maximum polling attempts (default 360)	No
VOD_URL_EXPIRE_MINUTES	Signed URL expiry (minutes, default 60)	No
VOD_PLAY_DOMAIN	Force a specific playback domain (optional, highest priority)	No
VOD_HOST	Override VOD OpenAPI hostname (optional)	No

---

Error Output Format

All failures use:

{"error": "error description"}

---

References

• BytePlus VOD Python SDK
• precision erasure parameter reference
• 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)