User Assets

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

Tài liệu cho User Assets.

Upload và quản lý media assets (video, hình ảnh, âm thanh). Assets dùng làm intro/outro, logo, watermark, nhạc nền, voiceover, thumbnail trong tạo video.

Luồng Upload

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: Presign response có category, maxSizeBytes, allowedContentTypes — dùng để validate phía client trước khi upload.

Bước 1: Presign

POST /api/v2/user-assets/presign

Field	Type	Description
fileName*	string	Tên file gốc (ví dụ "logo.png")
contentType*	string	MIME type (ví dụ "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"]
  }
}

Bước 2: Upload lên Blob

PUT file binary trực tiếp lên sasUrl với header x-ms-blob-type: BlockBlob.

bash

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

Bước 3: Xác nhận

POST /api/v2/user-assets/confirm

Field	Type	Description
blobPath*	string	Blob path trả về từ presign
fileName*	string	Tên file gốc
contentType*	string	MIME type
fileSizeBytes*	number	Kích thước file (bytes)
purpose	string	Mục đích asset (optional — xem bảng bên dưới)
label	string	Nhãn hiển thị
durationSec	number	Thời lượng giây (video/audio)
aspectRatio	string	Tỷ lệ khung (ví dụ "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"
  }'

Danh sách Assets

GET /api/v2/user-assets

Field	Type	Description
category	string	Lọc theo category: video, image, audio, document
purpose	string	Lọc theo purpose (xem bảng purpose)

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"
    }
  ]
}

Các field response

Field	Type	Description
id*	number	ID của asset
url*	string	URL công khai của asset
fileName*	string	Tên file gốc
mimeType*	string	MIME type (ví dụ "video/mp4")
fileSizeBytes*	number	Kích thước (bytes)
category*	string	Tự phát hiện: video, image, audio, document
purpose*	string	Mục đích asset
label	string	Nhãn hiển thị (nullable)
thumbnailUrl	string	URL thumbnail (nullable)
durationSec	number	Thời lượng (video/audio)
aspectRatio	string	Tỷ lệ khung
hasAudio	boolean	File có audio track không (video/audio)
createdAt	string	Thời điểm tạo (ISO 8601)

Lấy Asset theo ID

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

bash

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

Cập nhật Asset

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

Field	Type	Description
label	string	Nhãn mới
purpose	string	Mục đích mới

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"}'

Xóa 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"

Xóa nhiều

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]}'

Dung lượng sử dụng

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 }
  }
}

Giá trị Purpose

Purpose	Dùng cho
outro_video	Ghép cuối video khi render
intro_video	Ghép đầu video khi render
logo	Overlay logo lên video khi render
watermark	Watermark overlay trong render pipeline
background_music	Nhạc nền tùy chỉnh cho tất cả loại video
voiceover	File giọng nói do user upload (thay TTS)
thumbnail	Thumbnail tùy chỉnh cho job đã publish
general	File tham khảo chung

Giới hạn theo Category

Category	Content Types	Tối đa	Số lượng
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

Mã lỗi

Mã	Khi nào
400	Content type không hợp lệ hoặc thiếu trường bắt buộc
401	Chưa xác thực
404	Asset không tồn tại hoặc không thuộc user
409	Conflict — blobPath đã được confirm
429	Đã đạt giới hạn số lượng hoặc dung lượng

Trang trướcModels Trang sauTài nguyên