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#

AspectBehaviourInputVid or DirectUrl (JSON field video)Erasure coverageDefault 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.TimelineDefault: 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 metadataDefault 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#

text

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 intentPipelineEntry scriptUpload video to VODUploadscripts/upload.pySubtitle / on-screen text erasurePrecision erasurescripts/precise_erase.py

---

S1_UPLOAD & S2_POLL: Upload and Obtain Vid#

Calling convention#

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

bash

# 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.:

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

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

Timeout handling (URL upload)#

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

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 \"<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/):

bash

# 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#

ParameterTypeRequiredDescriptiontypestring✅Vid or DirectUrl``videostring✅Vid or VOD FileName; vid:// / directurl:// stripped automaticallytextbooleannoIf true: Auto.Type: Text (more aggressive). Default false → subtitle-only.all_textbooleannoSynonym for text (if both are set, text is applied first).clip_filterobjectnoOmit = whole video. If set: mode skip or selected, and clips (non-empty list of { "start", "end" } seconds; Start/ End accepted).with_erase_infobooleannoDefault 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:

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

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:

json

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

NameDescriptionRequiredBYTEPLUS_ACCESSKEYBytePlus Access KeyYesBYTEPLUS_SECRETKEYBytePlus Secret KeyYesVOD_SPACE_NAMEVOD space nameYes (or via CLI argument)VOD_POLL_INTERVALPolling interval (seconds, default 5)NoVOD_POLL_MAXMaximum polling attempts (default 360)NoVOD_URL_EXPIRE_MINUTESSigned URL expiry (minutes, default 60)NoVOD_PLAY_DOMAINForce a specific playback domain (optional, highest priority)NoVOD_HOSTOverride VOD OpenAPI hostname (optional)No

---

Error Output Format#

All failures use:

json

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