byted-byteplus-vod-precision-erasure

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

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:

---

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

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

---

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)