User Assets

Tạo link upload

Bước 1 khi upload asset: lấy link để upload file lên, và fileKey để xác nhận.

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

Xác thực

X-Api-Keystring · headerbắt buộc
API key của bạn, tạo ở trang API key trong tài khoản.

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.

File ở đây được giữ tới khi bạn xoá, trong hạn mức của từng category. Chỉ cần một ảnh làm tham chiếu cho lần tạo ảnh kế tiếp? Upload ảnh tham chiếu (lưu tạm, tự xoá sau 1 ngày).

Body

fileNamestringbắt buộc
Tên file gốc (ví dụ "logo.png")
contentTypestringbắt buộc
MIME type (ví dụ "image/png", "video/mp4")

Response

uploadUrlstring
Nơi gửi file lên (bước 2). Chỉ ghi được đúng file này; không cần X-Api-Key
methodstring
Method của request đó: "PUT"
headersobject
Gửi đúng các header này kèm file (Content-Type, và x-ms-blob-type khi có) — đọc từ đây, đừng viết cứng trong code
urlstring
Link đọc file sau khi upload xong
fileKeystring
Mã file — gửi lại ở bước xác nhận (bước 3)
expiresInnumber
Số giây tới khi uploadUrl hết hạn (600). Nên dùng trường này.
expiresAtstring
Cùng thời điểm đó, giờ UTC (ISO 8601) — giữ để tương thích.
categorystring
Category suy ra từ contentType
Giá trị có thể:videoimageaudiodocument
maxSizeBytesnumber
Kích thước file tối đa của category này (bytes)
allowedContentTypesstring[]
Các MIME type category này nhận

Mã lỗi

Mã	errorCode	Khi nào
400	UNSUPPORTED_FILE_TYPE	Content type không được nhận cho category này (xem Giới hạn theo Category)
429	QUOTA_EXCEEDED	Đã chạm trần số file hoặc dung lượng của category
500	UPLOAD_FAILED	Không tạo được link upload (lỗi lưu trữ) — thử lại

Luồng Upload

text

1. POST /user-assets/presign  →  uploadUrl, method, headers, fileKey
2. PUT  uploadUrl (the file)  →  with exactly those headers
3. POST /user-assets/confirm  →  fileKey: the file becomes an asset

Presign response có category, maxSizeBytes, allowedContentTypes — dùng để validate phía client trước khi upload.

Bước 2: Upload file

Gửi file lên uploadUrl bằng method và đúng các header mà response presign trả về. Sau đó xác nhận bằng fileKey — chưa xác nhận thì file chưa thành asset.

bash

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

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, gif	50 MB	100
audio	audio/mpeg, wav, ogg, aac	100 MB	30
document	application/pdf, text/csv, application/json	50 MB	20

Bước tiếp theo, khi file đã upload xong: Xác nhận upload để đăng ký file thành asset.

POST/user-assets/presign

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

{
  "success": true,
  "data": {
    "uploadUrl": "https://…/user-assets/1e65….png?sv=…&sig=…",
    "method": "PUT",
    "headers": {
      "Content-Type": "image/png",
      "x-ms-blob-type": "BlockBlob"
    },
    "url": "https://cdn.sangtao.ai/user-assets/1e65….png",
    "fileKey": "d15ed…/user-assets/1e65….png",
    "expiresIn": 600,
    "expiresAt": "2026-06-08T12:30:00Z",
    "category": "image",
    "maxSizeBytes": 52428800,
    "allowedContentTypes": [
      "image/png",
      "image/jpeg",
      "image/webp",
      "image/svg+xml",
      "image/gif"
    ]
  }
}

POST/user-assets/presign

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

{
  "success": true,
  "data": {
    "uploadUrl": "https://…/user-assets/1e65….png?sv=…&sig=…",
    "method": "PUT",
    "headers": {
      "Content-Type": "image/png",
      "x-ms-blob-type": "BlockBlob"
    },
    "url": "https://cdn.sangtao.ai/user-assets/1e65….png",
    "fileKey": "d15ed…/user-assets/1e65….png",
    "expiresIn": 600,
    "expiresAt": "2026-06-08T12:30:00Z",
    "category": "image",
    "maxSizeBytes": 52428800,
    "allowedContentTypes": [
      "image/png",
      "image/jpeg",
      "image/webp",
      "image/svg+xml",
      "image/gif"
    ]
  }
}

Trang trướcGửi lại lần giao Trang sauXác nhận upload