Uploads API Reference

Reference for the direct binary upload endpoints supported by StackVid.

Optional Feature

This endpoint is only required if you have local binary files (e.g. locally rendered .mp4 or thumbnails) that need temporary hosting before publishing.

If your video already has a direct public download URL (from your CDN, Amazon S3, Google Cloud, private server, etc.), you can bypass this API completely and pass your direct link directly into the videoUrl parameter of the TikTok Publishing API.

---

1. Request Presigned Upload URL

POST /api/uploads/presigned-url

Generates a secure presigned PUT URL allowing clients to upload binary video or image assets directly to temporary object storage.

• Credit Cost: 2,000 Credits Escrow Deposit (action: UPLOAD_DEPOSIT). This escrowed deposit is automatically 100% refunded (+2,000 Credits) back to your wallet once the video is successfully published via POST /api/tiktok/upload.

Headers:

• Content-Type: application/json
• X-API-Key: *** (or Authorization: Bearer ***)

Request Body:

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

• fileType (Required, enum): VIDEO (max 500MB) or COVER_IMAGE (max 10MB).
• contentType (Required, string): Valid MIME type (video/mp4, image/jpeg, etc.).
• fileSizeBytes (Required, number): Total file size in bytes.

Response (201 Created):

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

Response Fields:

• uploadUrl: Temporary HTTP PUT URL for uploading binary file data directly (valid for 15 minutes).
• publicUrl: Staged public URL returned after upload, passed to the publishing API.
• fileKey: Internal storage key.
• expiresInSeconds: Validity window in seconds (default: 900s = 15 minutes).