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

Aspect	Behaviour
Input	Vid or DirectUrl (JSON field video)
Extraction strategy	Default: specified time at 0 ms. Supported: specified time, fixed interval, specified frames, scene-change detection.
Target image size	Default resolution: 720p because the API Snapshot Target requires a resolution. Optional scale_long / scale_short.
Sprite image	Optional sprite / sprite_config.
Output index mode	Optional output_mode: Files or Index.
Advanced API fields	Use snapshot for complete passthrough or snapshot_options to deep-merge extra fields into generated Snapshot.

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:

User intent	Pipeline	Entry script
Upload video to VOD	Upload	scripts/upload.py
Extract frames / thumbnails	Frame extraction	scripts/snapshot.py

---

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

Parameter	Type	Required	Description
type	string	no	Vid or DirectUrl. Default Vid.
video	string	yes	Vid or VOD FileName; vid:// / directurl:// prefixes are stripped automatically.
strategy	string/object	no	specified_time, interval, specified_frames, or scene_change. Default specified_time. If object, used directly as API Strategy.
times	integer/array	no	Millisecond offsets for specified_time. Default [0].
interval_ms	integer	for interval	Millisecond interval for fixed interval snapshots.
frames	integer array	for specified frames	Frame indexes for specified_frames; 0 means first frame and -1 means last frame.
threshold	float	no	Scene-change threshold in [0, 1], default 0.1.
resolution	string	no	Default 720p. Allowed: 240p, 360p, 480p, 720p, 1080p.
scale_long / scale_short	integer	no	Long/short output image edge, [0, 4096].
sprite / sprite_config	boolean/object	no	Sprite image config. Object is passed directly as SpriteConfig.
output_mode	string	no	Files or Index, maps to IndexOption.Mode.
snapshot	object	no	Complete API Snapshot object passthrough.
snapshot_options	object	no	Advanced fields deep-merged into generated Snapshot.

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

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
TOS_UPLOAD_CONNECT_TIMEOUT	TOS upload connect timeout in seconds (default 5)	No
TOS_UPLOAD_READ_TIMEOUT	TOS upload read timeout in seconds (default 600)	No

---

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)