Uploads API Reference

Tài liệu chi tiết về endpoint cấp URL tải lên tệp tin nhị phân (Binary Upload) trực tiếp vào hệ thống.

Tính Năng Tùy Chọn (Optional)

Endpoint này chỉ cần thiết khi bạn có tệp tin nhị phân cục bộ (file .mp4, ảnh bìa) cần tải lên hệ thống trước khi đăng bài.

Nếu video của bạn đã có sẵn đường dẫn tải trực tiếp (Direct URL từ CDN, Amazon S3, Google Cloud Storage, máy chủ riêng, v.v.), bạn không cần gọi API này mà có thể truyền thẳng link đó vào trường videoUrl của API Đăng Video TikTok.

1. Xin Presigned Upload URL

POST /api/uploads/presigned-url

Tạo một URL ký trước an toàn cho phép client đẩy tệp video hoặc ảnh bìa trực tiếp lên hệ thống lưu trữ tạm thời qua giao thức HTTP PUT.

Chi phí Credit: Tạm ứng 2.000 Credits làm cọc lưu trữ tạm thời (hành động UPLOAD_DEPOSIT). Khoản cọc này sẽ được tự động hoàn trả 100% (+2.000 Credits) ngay khi bạn xuất bản video thành công qua POST /api/tiktok/upload.

Headers:

Content-Type: application/json
X-API-Key: *** (hoặc Authorization: Bearer ***)

Request Body:

json

{
  "fileType": "VIDEO",
  "contentType": "video/mp4",
  "fileSizeBytes": 25480000
}

Chi tiết tham số:

fileType (Bắt buộc, enum):
- VIDEO: Tệp video (chấp nhận video/mp4, video/quicktime, video/webm). Dung lượng tối đa: 500MB.
- COVER_IMAGE: Tệp ảnh bìa (chấp nhận image/jpeg, image/png, image/webp). Dung lượng tối đa: 10MB.
contentType (Bắt buộc, string): Chuỗi MIME type chính xác của tệp tin.
fileSizeBytes (Bắt buộc, number): Dung lượng tệp tính theo Bytes (dùng để xác thực hạn mức).

Response (201 Created):

json

{
  "uploadUrl": "https://storage.stackvid.dev/uploads/users/usr_123/video-1727182900.mp4?signature=...",
  "publicUrl": "https://media.stackvid.dev/uploads/users/usr_123/video-1727182900.mp4",
  "fileKey": "users/usr_123/video-1727182900.mp4",
  "expiresInSeconds": 900
}

Mô tả trường trả về:

uploadUrl: URL dùng riêng cho lệnh HTTP PUT dữ liệu nhị phân lên hệ thống (có hiệu lực trong 15 phút).
publicUrl: URL tệp tin công khai sau khi upload hoàn tất, dùng để truyền vào trường videoUrl của API Đăng bài.
fileKey: Định danh lưu trữ nội bộ của tệp.
expiresInSeconds: Thời gian hiệu lực của uploadUrl tính theo giây (mặc định 900s = 15 phút).

Uploads API Reference ​

1. Xin Presigned Upload URL ​

Headers: ​

Request Body: ​

Chi tiết tham số: ​

Response (201 Created): ​