Skip to main content

​
Goal

Choose the right Assets workflow, understand when an asset is deliverable, and know which API or SDK method owns each operation.

​
Prerequisites

  • A StackShift account with access to the selected Assets space
  • For API integrations, an appropriately scoped API key kept on your backend

​
Workflow

1
Create or let the API create a bucket. A bucket supplies defaults for visibility, cache control, versioning, size, MIME policy, and replication.
2
Keep managed storage or attach a verified S3-compatible or native S2 destination. Changing storage affects new writes; use relocation for historical objects.
3
Upload a file with a bucket and key, or create a short-lived upload session for browser and resumable flows.
4
Import provider libraries through a dry run and durable migration, or enable OCR for searchable PDF and image text.
5
Wait for the asset to become ready. Public URLs and signed URLs fail closed while scan, moderation, or replica gates are not satisfied.
6
Deliver the current version with the returned public URL, a signed URL, a named transform, a signed transform, or a version/branch URL.
7
Use revision-aware mutations for rename, visibility, metadata, tags, replace, and delete. Treat delete and AI/media processing as asynchronous where the API returns a job.
8
Use list filters, collections, saved searches, events, webhooks, usage summaries, and lifecycle rules to operate the library at scale.
9
For governed content, complete typed metadata, choose approved rendition references, submit review and publish a channel-specific snapshot.
10
Embed approved publications through the picker, WordPress blocks or a gallery. Store stable IDs and resolve fresh delivery credentials from your backend.

​
Explore the complete Assets workflow

Start with a source image, video or model, create the outputs you need, then review and distribute approved versions. These guides cover the complete implemented media workflow through the WordPress integration. They are organized by task so an editor can follow dashboard steps and a developer can continue into the corresponding API or SDK reference. For a first project, follow the workspace and sample guide. If you are embedding Assets in an application, start with SDK quick start and media SDK workflows.

​
Start here

Workspace and samples Sdk quick start Sdk media workflows

​
Image editing and AI

Image studio and templates Ai image generation and editing Image optimization Deterministic media transforms Ai dam and versioning Ocr and document search

​
Video and player

Video studio Player studio profiles Video scanning and governance Video player captions and analytics

​
3D canvas and product media

3d canvas studio Models ar and galleries 3d product rendering Media galleries

​
Library, review and distribution

Library spaces and sharing Metadata and bucket governance Publications review and rights Creative review and portals Assets analytics

​
Integrations and automation

Wordpress media integration Headless asset picker Embeddable upload widget Media workflows Media workflow security and operations Stackie asset tools and mcp

​
Uploads, storage and access

Upload ux and dam Direct browser uploads Private assets and signed urls Storage connections and byob Cloudinary s3 and s2 migrations

​
API and operator references

Api reference Platform api cli and operations Assets environment reference Assets deployment readiness

​
Example: publish a product campaign

Import a sample or upload a product photo. Use Image Studio to create a square product card and save a reusable template. Edit a short product clip in Video Studio and apply a Player Studio profile. Open the product GLB in 3D Studio, inspect materials, and generate the product images or spin you need. Create publication drafts from the chosen outputs. Complete creative review, publish the approved versions and arrange them in a gallery. Share the campaign through a portal, or connect WordPress and insert a Stackshift media or Stackshift gallery block. Inspect customer analytics after the campaign is viewed. A source, a saved output, a publication, a gallery revision and a player-profile revision are different records. Keep their identities straight when updating a campaign: editing a source or draft does not mean every existing published embed has adopted that edit.

​
Free plan and paid upgrades

Every StackShift account receives the Assets Free plan automatically. It does not expire, require checkout, or require a payment method. An active paid Assets plan replaces the Free allowances for its purchased period; when that period expires, the account returns to the current Free plan without losing stored media. Free includes a 500 MB Assets library, uploads and private delivery, webhooks, image transformations, OCR, native video processing, and AI operations using your own provider key. Monthly processing limits are 100 transformations, 5 OCR jobs, 5 native video jobs, and 10 AI operations. Idempotent retries of the same admitted operation do not consume another unit. Paid plans increase storage and processing limits and can enable advanced transformations, custom domains, workflows, external storage, and provider-backed product rendering. The billing page shows only purchasable paid plans; Free is displayed as the account baseline and cannot be sent through checkout.

​
Video, headless DAM and 3D workflows

Use the Library to upload and inspect media, Review to manage editorial publications, and Galleries to arrange published images, videos, spins and models. Manage contains typed metadata, bucket governance and collaborator access. Available processing capabilities are reported for the selected space; a disabled capability must be enabled by the platform owner before use. Native video processing and delivery run on StackShift. 3D Studio creates images, 24-frame spins, turntable videos, bounded material variants and AR companions from validated GLB packages. The gallery displays interactive models and launches authorized AR. For native video, use the dedicated video workspace and playback-session contract. Legacy video_status/output helpers and optional AI moderation are not the native package readiness or human-review contract.

​
The product model

Assets is scoped to an owned or explicitly shared Assets space. An API key identifies the actor; assetSpaceId selects an authorized space and does not grant access. A deployed StackShift project ID is not required. The public control-plane API defaults to https://api.stackshift.cloud/api/v1; the CDN URL returned by the SDK defaults to https://cdn.stackshift.cloud. A logical asset is addressed by a bucket and key, but the API returns an opaque asset ID and a revision. Keep the asset ID in your application database. Treat the key as a human-facing namespace, not as a filesystem path.
  • Buckets are policy containers. Uploading to a new bucket name creates it with private visibility and versioning enabled unless an existing bucket says otherwise. The global-3 replication policy is the storage target, not a claim that three deployment servers are currently connected; replication_status reports what is actually available in this installation.
  • Keys are slash-separated names such as users/user_123/avatar.png. The service rejects traversal, empty path segments, NUL bytes, and keys longer than 1,024 characters.
  • Metadata is valid JSON. Tags, metadata, cache control, visibility, original name, and key can be changed after upload, subject to the current revision.
  • Cloudflare can provide the edge and cache layer, but persistent asset bytes remain behind the StackShift Assets origin.

​
Asset readiness and delivery gates

An upload response identifies the asset; it is not a promise that the bytes are immediately public. The service moves the asset through processing, ready, quarantined, failed, deleting, and deleted. Delivery requires status=ready, an available current version, a usable replica, and any configured scan or moderation gates.
  • scan_status: pending, clean, infected, failed, or skipped.
  • replication_status: pending, replicated, degraded, or failed.
  • quarantine_status: none, infected, or policy.
  • video_status: none, pending, processing, ready, failed, or skipped.
  • ai_status: pending, processing, ready, failed, or skipped; moderation has its own pending, processing, clean, flagged, quarantined, and failed states.
  • When a public asset is replaced, its generation and current version change. Version-qualified URLs prevent an old cached byte from being mistaken for the new version.

​
Choose a workflow

  • Small server-side file: assets.upload / Assets.Upload / assets.upload with multipart form data.
  • Browser or unreliable network: create a single or chunked upload session, then PUT to the signed URL. Chunked sessions carry a part size, per-part SHA-256, resume state, completion, and cancellation.
  • Ungoverned public image: use asset.url for the current original, a named transform URL for a reusable preset, or a signed transform URL for a server-selected spec.
  • Ungoverned private file: upload with visibility=private, mint a short-lived signed URL on the server, and pass only the URL to the browser.
  • Governed media: publish reviewed rendition references with channel rights; originals remain private and consumers use the publication resolver.
  • Native video: process a source-version package, use the shared player with renewable playback sessions, and upload WebVTT captions.
  • Interactive 3D: validate a supported GLB, provide a poster, review a model publication and embed it with intent-based loading.
  • Product imagery: estimate and explicitly request a proof, final image, 24-frame spin or turntable from a ready model; review final outputs before publication.
  • Headless CMS: issue an origin-bound picker capability, store selected stable references, and resolve approved delivery from your backend.
  • Media intelligence: enqueue analyze, moderation, transcript, smart-crop, or background-removal work and poll the returned status_url.
  • Provider migration: verify a Cloudinary, S3-compatible, or native S2 source, run inventory first, then import with checksum deduplication and a retained report.
  • Customer storage: attach AWS S3, R2, Wasabi, MinIO, generic S3, or native S2 while keeping the StackShift CDN URL.
  • Embeddable uploads: issue one-session browser capabilities from your backend and render @stackshift-cloud/assets-widget for local, camera, URL, crop, preview, and resumable flows.
  • Document search: run OCR manually or enable it per bucket; ready extracted text joins the existing Assets query search.
  • Deterministic media: use an ordered v2 definition for image/video transforms, audio extraction, timestamp thumbnails, overlays, and eager named presets.
  • Automation: build an editable media workflow, use governed Stackie/MCP asset tools, invoke native StackShift actions, and reserve the restricted HTTP node for approved external integrations.
  • Content operations: use buckets, list filters, revision-aware patches, bulk jobs, collections, saved searches, webhooks, and lifecycle rules rather than rebuilding those controls in the client.

​
What the API returns

  • Identity and bytes: id, bucket, key, original_name, mime_type, size, and checksum_sha256.
  • Policy and state: visibility, cache_control, status, replication_status, scan/quarantine/video/AI statuses, and delivery_revoking when a visibility change is being applied.
  • Organization: metadata, tags, generation, revision, created_at, updated_at, and the current version/branch identifiers.
  • Delivery: url only when a public asset is ready; video and AI objects are present when their asynchronous jobs have produced results.
  • Asset responses omit storage node IDs, replica paths and local disk paths. Governed collaboration uses explicitly authorized asset-space IDs; obtain them from assets.dam.spaces() rather than guessing tenant identity.

​
Expected result

You can implement an end-to-end upload and delivery flow without guessing at URL formats, lifecycle states, concurrency rules, or which features are asynchronous.

Assets SDKs: JavaScript, Go, Python and PHP

Configure space-scoped clients and use native video, governed DAM, model rendering, galleries and CMS capabilities in all four SDKs.

Library, spaces, collections and sharing

Find and organize media, switch Assets spaces, invite collaborators with explicit permissions, and handle access changes safely.

Typed metadata and bucket governance

Create and publish metadata schemas, bind exact revisions to buckets, validate asset fields, and migrate existing delivery into governance.

Publications, review and usage rights

Select immutable renditions, capture metadata and rights, submit editorial review, publish by channel, and withdraw delivery.

Embed the headless asset picker

Add JavaScript or React media selection using expiring capabilities, save stable references, and resolve approved media from your backend.

Create and embed media galleries

Arrange published images, video, spins and models with locale, alternate text, approved fallbacks and stable published revisions.

Use Assets in WordPress

Install the StackShift Assets plugin, select approved media in Gutenberg, publish stable gallery references, and maintain revocation-aware delivery.

Assets REST API reference

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

Assets SDK quick start

Install the official SDKs, upload a first asset, and handle the readiness state before you publish its URL.

Image optimization

Use the current transform grammar, named presets, and signed dynamic transforms for predictable image delivery.

Upload UX and DAM

Build a durable upload and digital-asset-management workflow with resumable sessions, revision-safe mutations, search, collections, webhooks, and usage summaries.

Native video processing and secure playback

Version-pinned video packages, scan and review gates, replacement behavior, playback sessions, API routes, and failure recovery.

Video player, captions and analytics

Install the shared player, implement public/private session callbacks, upload immutable WebVTT tracks, and interpret session-scoped telemetry.

Upload, validate and publish 3D models

Prepare supported GLB and supplied USDZ files, inspect validation reports, add posters, review the model and launch authorized device AR.

3D Studio: variants, product media and AR

Prepare a GLB, pin governed texture variants, estimate rendering units, create verified product media and publish 3D or AR experiences.

AI assistance and asset versioning

Use configured asset AI jobs, moderation, transcripts, derived images, collections, saved searches, and branching versions with explicit readiness and spend controls.

Storage connections, BYOB, and StackShift S2

Configure AWS S3, Cloudflare R2, Wasabi, MinIO, generic S3, or native StackShift S2 without exposing customer storage credentials or changing delivery URLs.

Cloudinary, S3, R2, and S2 migrations

Inventory, dry-run, import, deduplicate, retry, cancel, and report durable migrations from Cloudinary or S3-compatible storage into StackShift Assets.

Embeddable Assets upload widget

Install @stackshift-cloud/assets-widget for React or vanilla JavaScript with constrained backend-issued capabilities, resumable chunks, camera and URL input, cropping, previews, progress, retry, and cancellation.

OCR, document intelligence, and DAM search

Extract embedded PDF text or OCR PDF and image pages asynchronously, inspect normalized word geometry, cache by content identity, and search extracted text in the DAM.

Deterministic image, video, and audio transforms

Define ordered v2 transforms for images, video renditions, audio extraction, and timestamp thumbnails; store eager presets or materialize durable derivatives.

Stackie asset tools and MCP

Use the same governed asset actions from Stackie, workflow Stackie nodes, and stateless Streamable HTTP MCP clients.

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.

Media Workflow authority, integrations, and recovery

Operate workflow grants, execution principals, durable waits, restricted HTTP connections, signed inbound hooks, retries, cancellation, and post-publish warnings.