Assets SDK quick start

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

Goal

Upload a file from a trusted backend, persist its ID and revision, and use the returned delivery URL only after the asset is ready.

Prerequisites

A StackShift API key stored in STACKSHIFT_API_KEY or your server secret manager
Node.js, Python, Go, or PHP installed for the matching official SDK

Workflow

Install one official SDK and construct its client. The default control-plane and CDN URLs are already configured.

Upload with a stable bucket/key and explicit visibility. Use private visibility unless the file is intended for unauthenticated delivery.

Persist id, revision, checksum_sha256, and the state fields from the response.

If the response is still processing, poll assets.get or subscribe to an asset webhook before rendering the URL.

Pass the current revision to replace, patch, tag, or delete calls; refresh the asset after a 412 conflict.

Install and configure

npm install @stackshift-cloud/sdk
pip install stackshift
go get github.com/stackshiftCloud/assets-go
composer require stackshift/assets

export STACKSHIFT_API_KEY="ss_live_..."
# Keep the key in the backend environment; never bundle it into browser JavaScript.

TypeScript

The JavaScript client uses camelCase options and maps them to the Assets API’s snake_case wire fields. asset.url is optional: it is populated only for a public, ready asset with a current version.

import { StackShift } from '@stackshift-cloud/sdk'

const stackshift = new StackShift({
  apiKey: process.env.STACKSHIFT_API_KEY!,
})

const asset = await stackshift.assets.upload(file, {
  bucket: 'avatars',
  key: 'users/user_123.png',
  visibility: 'public',
  metadata: { userId: 'user_123' },
})

console.log({ id: asset.id, revision: asset.revision, status: asset.status })
if (asset.url) console.log(asset.url)

NestJS

Wrap the SDK in a service and accept files through NestJS Multer interceptors. For larger browser uploads, create signed upload URLs instead of buffering through the NestJS process.

import { Injectable } from '@nestjs/common'
import { StackShift } from '@stackshift-cloud/sdk'

@Injectable()
export class AssetsService {
  private readonly stackshift = new StackShift({
    apiKey: process.env.STACKSHIFT_API_KEY!,
  })

  upload(file: Express.Multer.File) {
    return this.stackshift.assets.upload(
      new Blob([file.buffer], { type: file.mimetype }),
      {
        bucket: 'uploads',
        key: file.originalname,
        visibility: 'private',
        metadata: { originalName: file.originalname },
      },
    )
  }
}

import { Controller, Post, UploadedFile, UseInterceptors } from '@nestjs/common'
import { FileInterceptor } from '@nestjs/platform-express'
import { AssetsService } from './assets.service'

@Controller('assets')
export class AssetsController {
  constructor(private readonly assets: AssetsService) {}

  @Post('upload')
  @UseInterceptors(FileInterceptor('file'))
  upload(@UploadedFile() file: Express.Multer.File) {
    return this.assets.upload(file)
  }
}

React, Next.js, and TanStack Start

Browser apps should never receive the StackShift API key. Create a signed upload URL on a server route, then upload the browser File directly to StackShift Assets.

Server route

import { StackShift } from '@stackshift-cloud/sdk'

const stackshift = new StackShift({
  apiKey: process.env.STACKSHIFT_API_KEY!,
})

export async function createAvatarUpload() {
  return stackshift.assets.signedUploadUrl({
    bucket: 'avatars',
    key: `users/${crypto.randomUUID()}.png`,
    visibility: 'public',
    expiresIn: '10m',
    maxBytes: 5_000_000,
  })
}

Browser client

async function uploadAvatar(file: File) {
  const upload = await fetch('/api/assets/avatar-upload', {
    method: 'POST',
  }).then((response) => response.json())

  await fetch(upload.url, {
    method: upload.method,
    body: file,
    headers: { 'Content-Type': file.type },
  })
}

Python

The Python client returns dictionaries and raises StackShiftAPIError for non-2xx responses. Use asset["revision"] for later mutation calls.

import os
from stackshift import StackShift

stackshift = StackShift(api_key=os.environ["STACKSHIFT_API_KEY"])

asset = stackshift.assets.upload(
    "avatar.png",
    bucket="avatars",
    key="users/user_123.png",
    visibility="public",
    metadata={"user_id": "user_123"},
)

print(asset["id"], asset["revision"], asset["status"])
if asset.get("url"): print(asset["url"])

Go

The Go client returns typed assets. Mutating methods take the current revision explicitly so an older process cannot overwrite a newer change.

import (
    "context"
    "log"
    "os"

    stackshift "github.com/stackshiftCloud/assets-go"
)

client, err := stackshift.New(stackshift.Options{
    APIKey: os.Getenv("STACKSHIFT_API_KEY"),
})

file, _ := os.Open("avatar.png")
defer file.Close()

asset, err := client.Assets.Upload(ctx, stackshift.AssetUpload{
    File: file,
    FileName: "avatar.png",
    Bucket: "avatars",
    Key: "users/user_123.png",
    Visibility: "public",
})

log.Println(asset.URL)

Expected result

Your backend can upload, persist, and safely deliver an asset without exposing the API key or serving a pending/quarantined object.

StackShift Assets

A grounded guide to Assets storage, uploads, delivery, imports, BYOB and S2, transformations, OCR, media processing, AI jobs, and DAM controls.

Direct browser uploads

Upload browser files directly with short-lived sessions, per-part checksums, progress callbacks, retries, resume, and cancellation.

Image optimization

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

AI DAM and versioning

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

​Goal

​Prerequisites

​Workflow

​Install and configure

​TypeScript

​NestJS

​React, Next.js, and TanStack Start

​Python

​Go

​Expected result

​Related guides

StackShift Assets

Direct browser uploads

Image optimization

AI DAM and versioning

Goal

Prerequisites

Workflow

Install and configure

TypeScript

NestJS

React, Next.js, and TanStack Start

Python

Go

Expected result

Related guides