Media transcode

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

Generic media/video processing capability. Submits transcode jobs (pluggable Stub / FFmpeg backend), extracts technical metadata, generates thumbnails, detects scene boundaries, and extracts audio tracks. Stateless outbound compute; no persistent store.

• Group: Content & media
• Contract: contracts/media-transcode/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/media/transcode

Endpoints

Method	Path	Summary
POST	/v1/transcode	Submit a transcode job (validates output_format ∈ {mp4,webm,hls,dash}, quality ∈ {360p,480p,720p,1080p,4k}).
POST	/v1/metadata	Technical metadata for a video URL.
POST	/v1/thumbnail	Single thumbnail at a timestamp.
POST	/v1/thumbnails	N evenly-spaced thumbnails.
POST	/v1/audio	Extract the audio track.
POST	/v1/scenes	Scene-boundary detection.
GET	/health	Liveness + backend + tenancy posture.
GET	/metrics	Prometheus metrics.

Schemas

VideoRequest

Field	Type	Description
video_url	string
organization_id	string	optional; must match the verified tenant when a JWT is presented

TranscodeRequest

ThumbnailRequest

ThumbnailsRequest

TranscodeResult

Field	Type	Description
job_id	string
status	string
output_url	string

Metadata

Field	Type	Description
duration	number
width	integer
height	integer
codec	string
fps	number
bitrate	integer
size_bytes	integer

Error

Field	Type	Description
error	string
reason	string
detail	object

---

Generated by scripts/gen-capability-docs.py from contracts/media-transcode/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.