Goal
Add richer discovery, governance, and version control without silently changing the stable current asset URL.Prerequisites
- A clean, replicated asset with moderation marked clean for non-moderation actions
- An account AI provider and API key configured by the operator
- The requested action enabled in the account policy and within the monthly spend cap
Workflow
1
Read the account AI configuration and enable only the actions your product needs.
2
Queue moderation after malware scanning marks the asset clean; wait for moderation to become clean before queueing analysis, transcription, smart crop, or background removal.
3
Review generated annotations, moderation categories/scores, transcripts, and derived outputs before publishing them.
4
Use collections and saved searches for curation and discovery, and use branches and versions for reversible asset changes.
5
Keep the current asset URL for consumers; use version or branch URLs when a consumer must pin a historical or staging object.
Configure and queue AI jobs
The account config reports the provider, whether it is configured, available actions, the policy’s enabled actions and revision, and monthly spend used. The opt-in policy currently enablesanalyze, transcribe, smart_crop, and background_remove; moderation is a separate model-gated operation. Jobs return job_id, status, and status_url, and can be polled or cancelled through the SDK.
AI results and safety behavior
- Analysis returns provider/model/status plus caption, alt text, tags, objects, colors, and raw structured data when available.
- Moderation returns flagged state, category booleans, category scores, status, and a reason; auto-quarantine can turn severe categories into
moderation_status: quarantinedandquarantine_status: policy. - Transcription returns provider/model/status, language, text, and segments for supported audio/video.
- Smart crop and background removal produce derived outputs keyed to the source checksum; they do not overwrite the original.
- A job can fail with an AI evaluation gate, opt-in-required, spend-cap, unavailable-provider, or clean/replica prerequisite error. Treat those as actionable states, not empty metadata.
AI provenance and accounting
The asset AI response includes runs with action, provider, model, prompt version, schema version, status, latency, input/output tokens, image count, cost in micros, failure reason, and any derived output ID. Use this data for auditability and cost attribution instead of inferring model usage from a job name.Collections and saved searches
- Collections are explicit groups of selected assets.
- Saved searches store filters such as query, tag, folder, MIME family, visibility, and checksum.
- Use collections for hand-picked campaigns, galleries, or deliverables.
- Use saved searches for living views such as recent videos, untagged assets, or quarantined items.
Version and branch URLs
Every upload or replace creates a versioned object behind the asset.versions lists the immutable history, createBranch creates a named branch from an optional version, restoreVersion makes a historical version current, and promoteBranch makes a branch the default. A version URL pins version_id; a branch URL follows that branch head. Public URLs still require a ready, non-quarantined object, while private version/branch URLs require a matching token.
Expected result
The library exposes AI results and provenance with explicit job/cap/evaluation failures, while version and branch delivery remains independently addressable.
Related guides
StackShift Assets
A grounded guide to Assets storage, uploads, delivery, imports, BYOB and S2, transformations, OCR, media processing, AI jobs, and DAM controls.
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.
Video, scanning, and governance
Process video asynchronously, deliver HLS and posters, expose scan gates, quarantine unsafe assets, and enforce account policies.