User Assets

POSThttps://sangtao.ai/api/v2/user-assets/presign

Reference for User Assets.

Upload and manage user media assets (videos, images, audio). Assets are used as intro/outro videos, logos, watermarks, background music, voiceovers, and thumbnails in video creation.

Upload Flow

text

1. POST /user-assets/presign  →  get sasUrl + blobPath
2. PUT  sasUrl (binary)       →  upload file to blob
3. POST /user-assets/confirm  →  register asset in DB

Note: The presign response includes category, maxSizeBytes, and allowedContentTypes — use these for client-side validation before uploading.

Step 1: Presign

POST /api/v2/user-assets/presign

Field	Type	Description
fileName*	string	Original file name (e.g. "logo.png")
contentType*	string	MIME type (e.g. "image/png", "video/mp4")

bash

curl -X POST https://sangtao.ai/api/v2/user-assets/presign \\
  -H "X-Api-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"fileName": "my-logo.png", "contentType": "image/png"}'

json

{
  "success": true,
  "data": {
    "sasUrl": "https://blob.sangtao.ai/...?sv=...&sig=...",
    "blobPath": "d15ed.../user-assets/1e65...png",
    "publicUrl": "https://blob.sangtao.ai/user-assets/...",
    "expiresAt": "2026-06-08T12:30:00Z",
    "category": "image",
    "maxSizeBytes": 52428800,
    "allowedContentTypes": ["image/png", "image/jpeg", "image/webp", "image/svg+xml"]
  }
}

Step 2: Upload to Blob

PUT the file binary directly to the sasUrl with x-ms-blob-type: BlockBlob header.

bash

curl -X PUT "PRESIGNED_SAS_URL" \\
  -H "x-ms-blob-type: BlockBlob" \\
  -H "Content-Type: image/png" \\
  --data-binary @my-logo.png

Step 3: Confirm

POST /api/v2/user-assets/confirm

Field	Type	Description
blobPath*	string	Blob path returned from presign
fileName*	string	Original file name
contentType*	string	MIME type
fileSizeBytes*	number	File size in bytes
purpose	string	Asset purpose (optional — see table below)
label	string	Display label
durationSec	number	Duration in seconds (video/audio)
aspectRatio	string	Aspect ratio (e.g. "16:9")

bash

curl -X POST https://sangtao.ai/api/v2/user-assets/confirm \\
  -H "X-Api-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "blobPath": "d15ed.../user-assets/1e65...png",
    "fileName": "my-logo.png",
    "contentType": "image/png",
    "fileSizeBytes": 245000,
    "purpose": "logo"
  }'

List Assets

GET /api/v2/user-assets

Field	Type	Description
category	string	Filter by category: video, image, audio, document
purpose	string	Filter by purpose (see purpose table)

bash

curl "https://sangtao.ai/api/v2/user-assets?purpose=logo" \\
  -H "X-Api-Key: YOUR_API_KEY"

json

{
  "success": true,
  "data": [
    {
      "id": 42,
      "url": "https://blob.sangtao.ai/user-assets/abc123/my-logo.png",
      "fileName": "my-logo.png",
      "mimeType": "image/png",
      "fileSizeBytes": 245000,
      "category": "image",
      "purpose": "logo",
      "label": "My Brand Logo",
      "thumbnailUrl": null,
      "durationSec": null,
      "aspectRatio": null,
      "hasAudio": false,
      "createdAt": "2026-06-08T10:30:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id*	number	Asset ID
url*	string	Public URL of the asset
fileName*	string	Original file name
mimeType*	string	MIME type (e.g. "video/mp4")
fileSizeBytes*	number	File size in bytes
category*	string	Auto-detected: video, image, audio, document
purpose*	string	Asset purpose
label	string	Display label (nullable)
thumbnailUrl	string	Thumbnail URL (nullable)
durationSec	number	Duration in seconds (video/audio)
aspectRatio	string	Aspect ratio
hasAudio	boolean	Whether file has audio track (video/audio)
createdAt	string	ISO 8601 creation timestamp

Get Asset by ID

GET /api/v2/user-assets/{id}

bash

curl https://sangtao.ai/api/v2/user-assets/42 \\
  -H "X-Api-Key: YOUR_API_KEY"

Update Asset

PUT /api/v2/user-assets/{id}

Field	Type	Description
label	string	New display label
purpose	string	New purpose

bash

curl -X PUT https://sangtao.ai/api/v2/user-assets/42 \\
  -H "X-Api-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"label": "New Label", "purpose": "watermark"}'

Delete Asset

DELETE /api/v2/user-assets/{id}

bash

curl -X DELETE https://sangtao.ai/api/v2/user-assets/42 \\
  -H "X-Api-Key: YOUR_API_KEY"

Bulk Delete

POST /api/v2/user-assets/bulk-delete

bash

curl -X POST https://sangtao.ai/api/v2/user-assets/bulk-delete \\
  -H "X-Api-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"ids": [42, 43, 44]}'

Storage Usage

GET /api/v2/user-assets/usage

bash

curl https://sangtao.ai/api/v2/user-assets/usage \\
  -H "X-Api-Key: YOUR_API_KEY"

json

{
  "success": true,
  "data": {
    "video":    { "count": 3, "maxCount": 20, "storageBytes": 150000000, "maxStorageBytes": 2147483648 },
    "image":    { "count": 12, "maxCount": 100, "storageBytes": 8500000, "maxStorageBytes": 524288000 },
    "audio":    { "count": 2, "maxCount": 30, "storageBytes": 25000000, "maxStorageBytes": 524288000 },
    "document": { "count": 0, "maxCount": 20, "storageBytes": 0, "maxStorageBytes": 209715200 }
  }
}

Purpose Values

Purpose	Used for
outro_video	Appended at end of rendered videos
intro_video	Prepended at start of rendered videos
logo	Overlay logo on video during render
watermark	Watermark overlay in render pipeline
background_music	Custom background music for all video types
voiceover	User-uploaded voice file (replaces TTS)
thumbnail	Custom thumbnail for published jobs
general	General reference files

Category Limits

Category	Content Types	Max Size	Max Items
video	video/mp4, video/webm	500 MB	20
image	image/png, jpeg, webp, svg+xml	50 MB	100
audio	audio/mpeg, wav, ogg, aac	100 MB	30
document	application/pdf, text/csv, application/json	200 MB	20

Error Codes

Code	When
400	Invalid content type or missing required fields
401	Not authenticated
404	Asset not found or doesn't belong to user
409	Conflict — asset with same blobPath already confirmed
429	Max items or storage quota exceeded

PreviousModels NextAssets & References