VOD Video Enhancement

Uploads video/audio to a BytePlus VOD space (from a local file or a public URL) and returns a vid://vxxxx reference. Additionally provides AI-based comprehensive quality restoration that removes compression artifacts, noise, and scratches from ingested videos, improving overall clarity and color rendition.

Prerequisites

• Environment variables (required, can be configured via a .env file in the working directory):
• BYTEPLUS_ACCESSKEY -- BytePlus Access Key
• BYTEPLUS_SECRETKEY -- BytePlus Secret Key
• VOD_SPACE_NAME -- VOD space name
• Execution: examples use uv run python ... (if the host environment can run Python directly, python scripts/... also works).

Workflow Overview

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

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

Quality restoration pipeline:
  [S3_ENHANCE] Submit restoration job (StartExecution/enhanceVideo) -> returns RunId
  [S4_POLL]    Poll GetExecution -> returns the restored file
  Output: { Status, SpaceName, VideoUrls[{ FileId, DirectUrl, Source }] }

Upload: Obtain Vid

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

# URL upload (automatically polls until a Vid is returned)
uv run python scripts/upload.py "https://example.com/video.mp4" [space_name]

• First argument: either a local file path or a public http:///https:// link. The script auto-detects which mode to use.
• Second argument (optional): the VOD space name; when omitted it is read from the environment variable VOD_SPACE_NAME.
• The file/URL must carry a file extension (such as .mp4, .mov, .mp3), otherwise an error is raised.

Output Format

On success, a JSON line is printed to stdout:

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

• Source: a vid://-formatted reference that can be passed directly to follow-up skills such as byted-mediakit.

Quality Restoration

Before quality restoration, you MUST ask the user to choose both required enhancement parameters if either config or repair_style is missing. Suggested prompt:

What type of video is it? 1. General video 2. Short video / UGC 3. Short drama / short series 4. AI-generated content 5. Old film / classic footage that needs restoration

>

Which video enhancement tier would you like to use? 1. Standard: balanced visual improvement and processing speed 2. Pro: cinematic-grade restoration with longer processing time

Internal mapping: General -> config=common; Short video -> config=ugc; Short drama -> config=short_series; AI-generated -> config=aigc; Old film -> config=old_film; Standard -> repair_style=1; Pro -> repair_style=2.

# Submit after the user has explicitly selected both config and repair_style
uv run python scripts/quality_enhance.py '{"type":"Vid","video":"v0310abc","config":"common","repair_style":1}'

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

Output Format

On success:

{
  "Status": "Success",
  "SpaceName": "my_space",
  "VideoUrls": [
    {
      "FileId": "xxx",
      "DirectUrl": "path/to/output.mp4",
      "Source": "directurl://path/to/output.mp4",
      "Url": "https://example.cdn.com/path/to/output.mp4?auth_key=..."
    }
  ]
}

• VideoUrls[0].Url: a directly accessible/downloadable URL.
• VideoUrls[0].Source (directurl://...) can be passed directly to downstream skills.

Timeout Handling

If polling times out (30 minutes), the output includes a resume_hint with a command to resume polling.

Environment Variables

| Name | Description | Required | |------|-------------|----------| | BYTEPLUS_ACCESSKEY | BytePlus Access Key | Yes | | BYTEPLUS_SECRETKEY | BytePlus Secret Key | Yes | | VOD_SPACE_NAME | VOD space name | Yes | | VOD_POLL_INTERVAL | Polling interval (seconds, default 5) | No | | VOD_POLL_MAX | Maximum polling attempts (default 360) | No |

References

• BytePlus VOD Python SDK
• API: ApplyUploadInfo (Version: 2023-01-01)
• API: CommitUploadInfo (Version: 2023-01-01)
• API: UploadMediaByUrl (Version: 2023-01-01)
• API: StartExecution (Version: 2025-07-01)
• API: GetExecution (Version: 2025-07-01)