Byted Byteplus Vod Precision Erasure

Upload video/audio media to BytePlus VOD (Video on Demand) storage, returning the Vid and playback references; supports local file upload (ApplyUploadInfo + TOS + CommitUploadInfo) and URL pull upload (UploadMediaByUrl); also submits precision erasure jobs on ingested media (StartExecution / Operation.Task.Erase): Auto OCR only — default subtitle-only erasure, optional full on-screen text, optional EraseOption ClipFilter (skip/selected); NewVid is always true; optional WithEraseInfo. Trigger keywords: precision erasure, precise erase, VOD upload, subtitle removal, OCR subtitles, remove on-screen text, erase text, StartExecution Erase.

volcengine-skills@volcengine-skills

Install

openclaw skills install @volcengine-skills/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

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

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

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):

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

URL pull (async + poll):

UploadMediaByUrl (2023-01-01) → JobId
Poll QueryUploadTaskInfo until done (same limits as sibling skill: typically 360 × 5 s)
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

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:

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

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:

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)

Byted Byteplus Vod Precision Erasure

Install

VOD precision erasure

Product scope

Prerequisites

Workflow overview

Quick Self-Check (recommended)

S1_UPLOAD & S2_POLL: Upload and Obtain Vid

Calling convention

Upload flow

Output format

Timeout handling (URL upload)

S3_ERASE & S4_POLL: precision erasure

Calling convention

Parameter reference

Agent prompting (plain language)

Output format

Timeout handling (GetExecution polling)

Environment Variables

Error Output Format

References

Related skills