Volcengine TOS Document Process

Preview and convert office documents stored in Volcengine TOS — PDF/PNG/JPG conversion, page count, HTML preview URL, and page-range export.

Setup (once per environment)

Install dependencies on first use:

cd {baseDir}
pip install -r {baseDir}/requirements.txt

Then run scripts with Python 3.7+:

python3 {baseDir}/scripts/<script>.py <args>

If you see a ModuleNotFoundError for tos, reinstall dependencies.

Environment Variables

This skill relies on the TOS identity declared in the metadata block. Common runtime variables are:

Environment Variable	Required	Description
`TOS_ACCESS_KEY`	Yes	TOS access key ID
`TOS_SECRET_KEY`	Yes	TOS secret access key
`TOS_ENDPOINT`	Yes	TOS endpoint URL
`TOS_REGION`	Yes	TOS region
`TOS_BUCKET`	Yes	Source bucket that stores the document
`TOS_OBJECT_KEY`	No	Source object key of the document. Can be overridden with `--key`
`TOS_SECURITY_TOKEN`	No	STS session token when using temporary credentials

Quick start (common tasks)

# Convert document to PDF
python3 {baseDir}/scripts/doc_preview_pdf.py --key report.docx --output preview.pdf

# Preview page 2 as PNG
python3 {baseDir}/scripts/doc_preview_png.py --key report.docx --page 2 --output page_2.png

# Preview page 2 as JPG
python3 {baseDir}/scripts/doc_preview_jpg.py --key report.docx --page 2 --output page_2.jpg

# Get total page count
python3 {baseDir}/scripts/doc_total_page.py --key report.docx --dest-type pdf

# Resolve HTML preview URL
python3 {baseDir}/scripts/doc_preview_html_url.py --key report.docx

# Batch export page range to TOS
python3 {baseDir}/scripts/doc_preview_process.py --key report.docx \
  --dest-type jpg --img-mode 1 --start-page 1 --end-page 3 \
  --saveas-bucket "output-bucket" --saveas-object "export/page_{Page}.jpg"

# Batch screenshot a PDF page range
python3 {baseDir}/scripts/doc_batch_screenshot.py --key test.pdf \
  --format png --start-page 1 --end-page 3 \
  --saveas-object "skill-test/doc/{Page}.png"

Available scripts

Script	Purpose
`scripts/doc_preview_pdf.py`	Convert document to PDF and save locally.
`scripts/doc_preview_png.py`	Render a single page as PNG.
`scripts/doc_preview_jpg.py`	Render a single page as JPG.
`scripts/doc_total_page.py`	Read total page count via `x-tos-total-page` header.
`scripts/doc_preview_html_url.py`	Resolve the final HTML preview URL (follows redirects and extracts tokens).
`scripts/doc_preview_process.py`	Generic doc-preview with full parameter control; supports TOS-to-TOS export.
`scripts/doc_preview_params.py`	Helper library to build `x-tos-doc-*` query parameters consistently.
`scripts/doc_batch_screenshot.py`	Batch-export PDF pages as images through doc-preview batch mode.

All scripts support --key to override TOS_OBJECT_KEY. Structured scripts also support --json for machine-readable output, and doc_preview_process.py / doc_total_page.py support --dry-run to preview the resolved request. Run any script with -h for full usage.

Out of scope

Editing document contents (this skill is read-only preview/conversion).
Generic object storage tasks unrelated to document preview.
Local office conversion workflows that do not involve TOS.

Rules

Authentication: Authentication is provided by the TOS identity declared in the metadata block above. Object selection can be overridden per script with --key.
Pre-signed URL pattern: Document preview uses pre-signed URLs with x-tos-process=doc-preview and x-tos-doc-* query parameters, not the direct process keyword of get_object. Use doc_preview_params.py to build parameters consistently.
Batch screenshot constraint: doc_batch_screenshot.py currently requires a PDF source object and persists results back to TOS with a {Page} placeholder.
Save-as encoding: For doc-preview query-based save-as, the helper script automatically URL-safe-Base64 encodes x-tos-save-bucket and x-tos-save-object to match backend expectations.
Custom domain note: For buckets created after Jan 03, 2024, online HTML preview may require a custom domain rather than the default TOS domain.
Parameter source of truth: Official Volcengine TOS documentation is authoritative for the full doc-preview parameter matrix. When uncertain, check REFERENCE.md.
Language: Reply in the user's preferred language.

byted-tos-doc-process