VOD frame extraction

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 Snapshot tasks (StartExecution -> Operation.Task.Type: Snapshot) for frame extraction.

Product scope

If the user does not specify a strategy, use specified time at 0 ms. If they ask for multiple thumbnails but do not provide times, ask for the timestamps or use fixed interval only when they explicitly request evenly-spaced extraction.

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
• Environment template: see scripts/env.md.
• 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 }

Snapshot pipeline:
  [S3_SNAPSHOT] Submit frame extraction task (StartExecution / Task.Type Snapshot) -> RunId
  [S4_POLL]     Poll GetExecution -> output snapshot files / raw Snapshot output
  Output: { Status, SpaceName, ImageUrls[], Snapshot }

Quick self-check

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

Run from the Skill root directory (byted-byteplus-vod-frame-extraction/):

uv run python scripts/upload.py "/path/to/video.mp4" [space_name]
uv run python scripts/upload.py "https://example.com/video.mp4" [space_name]

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

On success, preserve Source (vid://...) for downstream processing.

S3_SNAPSHOT & S4_POLL: frame extraction

Run from the Skill root directory (byted-byteplus-vod-frame-extraction/):

# Default: first frame at 0 ms, 720p
uv run python scripts/snapshot.py '{"type":"Vid","video":"v0310abc"}'

# Three exact timestamps in milliseconds
uv run python scripts/snapshot.py '{"type":"Vid","video":"vid://v0d225gxxx","strategy":"specified_time","times":[0,5000,10000],"resolution":"720p"}' production_space

# Every 3 seconds
uv run python scripts/snapshot.py '{"type":"Vid","video":"v0310abc","strategy":"interval","interval_ms":3000}'

# Scene-change snapshots
uv run python scripts/snapshot.py '{"type":"Vid","video":"v0310abc","strategy":"scene_change","threshold":0.1}'

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

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

Parameter reference

Agent prompting

Ask for timestamps, interval, frame numbers, or scene-change detection only when the user's intent is ambiguous. Use conversational wording: “which frames or timestamps should I extract?” rather than raw API field names. If the user asks for a simple cover/thumbnail, use the default first-frame snapshot.

Output format

On success, one JSON object is printed to stdout:

{
  "Status": "Success",
  "SpaceName": "my_space",
  "ImageUrls": [
    {
      "FileId": "...",
      "Vid": "",
      "DirectUrl": "path/to/snapshot.jpg",
      "Source": "directurl://path/to/snapshot.jpg",
      "Url": "https://example.cdn.com/...",
      "Raw": {}
    }
  ],
  "VideoUrls": [],
  "AudioUrls": [],
  "Texts": [],
  "Snapshot": {}
}

• ImageUrls[].Url: playable / downloadable when signing succeeds for the space.
• Snapshot: raw API output from Output.Task.Snapshot.

Timeout handling

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

References

• StartExecution / OperationTaskSnapshot
• snapshot 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)