Deterministic image, video, and audio transforms

Live. This area is documented as current, user-reliable behavior.

Goal

Produce repeatable media derivatives whose cache identity includes the canonical definition, source bytes, overlay bytes, and processor revision.

Prerequisites

An asset in the same account
An assets:process token for transforms
A clean, ready source before durable materialization

Workflow

Build a version 2 definition with the source media kind, ordered operations, and one output.

Store it as a named preset when multiple assets use it; set eager=true to materialize after the clean scan gate.

POST the definition or preset to the asset transforms route. Supply exactly one, never both.

Poll the returned Assets job until it completes, then list derivatives and use only an available output.

Definition contract and bounds

version is exactly 2; media_kind is image or video; operation order is significant.
A definition contains 1–24 operations. Output kinds are image, video, audio, or thumbnail.
Final images are limited to 4096×4096 and 16,777,216 pixels. DPR is 0.5–4; blur sigma is greater than 0 and at most 100; output quality is 1–100 and defaults to 82 for image/thumbnail outputs.
Background is transparent or normalized 6/8-digit hex. Rotation is finite and normalized modulo 360.
Video FPS is 1–60. Trim end must exceed start. Trim and thumbnail timestamps are checked against probed source duration during processing.
Image formats are JPEG, PNG, WebP, and AVIF; video is MP4; extracted audio is MP3, AAC, or WAV; thumbnails are JPEG, PNG, or WebP.

Timestamp thumbnail example

const definition = {
  version: 2 as const,
  media_kind: 'video' as const,
  operations: [
    { type: 'trim' as const, start_seconds: 4, end_seconds: 48 },
    { type: 'timestamp' as const, timestamp_seconds: 12.5 },
    { type: 'crop' as const, mode: 'fill' as const, width: 1200, height: 630 },
    { type: 'overlay' as const, asset_id: watermark.id, gravity: 'southeast' as const, opacity: 72, x: 24, y: 24 },
  ],
  output: { kind: 'thumbnail' as const, format: 'webp' as const, quality: 84 },
}

const job = await stackshift.assets.materializeTransform(
  video.id, { definition }, 'thumbnail:video-42:v1',
)
const completed = await stackshift.assets.job(job.job_id)
const { derivatives } = await stackshift.assets.derivatives(video.id)

definition := stackshift.AssetTransformDefinition{
  Version: 2, MediaKind: "video",
  Operations: []stackshift.AssetTransformOperation{
    {Type: "timestamp", TimestampSeconds: 12.5},
    {Type: "crop", Mode: "fill", Width: 1200, Height: 630},
  },
  Output: stackshift.AssetTransformOutput{Kind: "thumbnail", Format: "webp", Quality: 84},
}
job, err := client.Assets.MaterializeTransform(ctx, assetID,
  stackshift.AssetTransformMaterializeInput{Definition: &definition}, "thumbnail:video-42:v1")

job = stackshift.assets.materialize_transform(
    video["id"],
    definition={
        "version": 2, "media_kind": "video",
        "operations": [{"type": "timestamp", "timestamp_seconds": 12.5}],
        "output": {"kind": "thumbnail", "format": "webp", "quality": 84},
    },
    idempotency_key="thumbnail:video-42:v1",
)

$job = $assets->materializeTransform($videoId, [
    'definition' => [
        'version' => 2, 'media_kind' => 'video',
        'operations' => [['type' => 'timestamp', 'timestamp_seconds' => 12.5]],
        'output' => ['kind' => 'thumbnail', 'format' => 'webp', 'quality' => 84],
    ],
], "thumbnail:video-42:v1");

stackshift asset transform-run "$ASSET_ID" --file ./thumbnail-v2.json --output json
stackshift asset job "$JOB_ID" --output json
stackshift asset derivatives "$ASSET_ID" --output json

Presets, eager processing, and v1 compatibility

POST /assets/transformations continues to accept the legacy width/height/crop/format/quality fields and signed v1 specs.
For v2, send name, definition, and eager. Stored presets expose definition_version, media_kind, normalized definition/spec, eager, and revision.
POST /assets/{assetID}/transforms accepts {definition} or {preset} and returns an Assets job. If no idempotency key is supplied, the service derives one from asset ID, source checksum, and normalized spec.
For CLI transform-run, the JSON passed to --file is the complete request body: wrap a v2 definition as { "definition": { ... } }, or use { "preset": "name" }.
GET /assets/{assetID}/derivatives returns persisted output kind, MIME type, size, transform hash, dependency checksum, processor revision, and availability state.
The service invokes libvips/FFmpeg/ffprobe through context-bound argument arrays, strips metadata, normalizes color, and marks output deliverable only after durable persistence and replication.

Expected result

Identical source and transform dependencies collapse onto the same durable output, while any source, overlay, definition, or processor change produces a new identity.

Common failures

A request mixes image-only operations such as DPR or radius into a video definition.
A thumbnail omits its single timestamp, or an audio output includes an operation other than trim.
An overlay is remote, belongs to another account, is not clean and ready, or exceeds the four-overlay limit.
The caller treats 202 Accepted as deliverable before the job persists and replicates the output.

Media Workflows visual builder and API

Author editable templates or blank typed DAGs that coordinate asset gates, native StackShift services, bounded Stackie reasoning, and approved external integrations.

Assets REST API reference

The routes, wire fields, response states, and concurrency rules shared by every official Assets SDK.

Video, scanning, and governance

Process video asynchronously, deliver HLS and posters, expose scan gates, quarantine unsafe assets, and enforce account policies.

​Goal

​Prerequisites

​Workflow

​Definition contract and bounds

​Timestamp thumbnail example

​Presets, eager processing, and v1 compatibility

​Expected result

​Common failures

​Related guides

Media Workflows visual builder and API

Assets REST API reference

Video, scanning, and governance

Goal

Prerequisites

Workflow

Definition contract and bounds

Timestamp thumbnail example

Presets, eager processing, and v1 compatibility

Expected result

Common failures

Related guides