Video Sources & Direct Uploads (Optional)

When publishing videos to social platforms via the StackVid API (POST /api/tiktok/upload), you provide a video download address in the videoUrl field.

StackVid supports two flexible workflows depending on your existing infrastructure: Using an Existing Public URL or Uploading Local Binary Files via Presigned URL.

---

1. Choosing the Right Approach

Workflow	When to use?	Is the Upload API required?	Credit Escrow Deposit?
Method 1: Direct Video URL (Recommended)	Your video is already hosted on a CDN, Amazon S3, Google Cloud, private server, or any public download link.	❌ No. Pass the URL directly to the publishing API.	❌ 0 Credit (No deposit).
Method 2: Local Binary Upload	You generate video files locally (rendered MP4 from FFmpeg or worker scripts) and lack public cloud hosting.	✅ Yes. Request a Presigned URL to upload your binary file.	⏳ 2,000 Credits Escrow (100% refunded after publish).

---

Method 1: Using a Direct Video URL (No Upload Needed)

If your video is already accessible via a public direct download URL, you can completely bypass the upload step.

Simply pass the video URL directly into the video publishing payload:

cURL

curl -X POST https://api.stackvid.dev/api/tiktok/upload \
  -H "X-API-Key: tk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://cdn.yourdomain.com/videos/summer-outfit.mp4",
    "text": "Check out this summer look! 🔥 #fashion #fyp",
    "targetChannel": "US Fashion Channel"
  }'

Node.js

import axios from 'axios';

await axios.post(
  'https://api.stackvid.dev/api/tiktok/upload',
  {
    videoUrl: 'https://cdn.yourdomain.com/videos/summer-outfit.mp4',
    text: 'Check out this summer look! 🔥 #fashion #fyp',
    targetChannel: 'US Fashion Channel',
  },
  {
    headers: { 'X-API-Key': 'tk_live_YOUR_API_KEY' },
  }
);

Python

import requests

requests.post(
    'https://api.stackvid.dev/api/tiktok/upload',
    headers={'X-API-Key': 'tk_live_YOUR_API_KEY'},
    json={
        'videoUrl': 'https://cdn.yourdomain.com/videos/summer-outfit.mp4',
        'text': 'Check out this summer look! 🔥 #fashion #fyp',
        'targetChannel': 'US Fashion Channel'
    }
)

---

Method 2: Uploading Local Binary Files (Optional)

If your pipeline generates MP4 files on your local machine or server and requires temporary hosting before publishing, StackVid provides a high-speed Presigned Upload URL service supporting files up to 500MB+.

Step 1: Request a Presigned Upload URL

Send your file size and MIME type to POST /api/uploads/presigned-url:

cURL

curl -X POST https://api.stackvid.dev/api/uploads/presigned-url \
  -H "X-API-Key: tk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileType": "VIDEO",
    "contentType": "video/mp4",
    "fileSizeBytes": 25480000
  }'

Node.js

import axios from 'axios';

const res = await axios.post(
  'https://api.stackvid.dev/api/uploads/presigned-url',
  {
    fileType: 'VIDEO',
    contentType: 'video/mp4',
    fileSizeBytes: 25480000,
  },
  {
    headers: { 'X-API-Key': 'tk_live_YOUR_API_KEY' },
  }
);

const { uploadUrl, publicUrl } = res.data;

Sample Response:

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

• uploadUrl: Temporary HTTP PUT URL for uploading the binary file directly (valid for 15 minutes).
• publicUrl: Staged public URL returned after upload, passed to the publishing API in Step 3.

---

Step 2: Upload Binary Data to uploadUrl

Execute an HTTP PUT request with your file stream:

cURL

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: video/mp4" \
  --data-binary "@/path/to/your/video.mp4"

Node.js

import fs from 'fs';
import axios from 'axios';

const fileBuffer = fs.readFileSync('./video.mp4');

await axios.put(uploadUrl, fileBuffer, {
  headers: {
    'Content-Type': 'video/mp4',
  },
});

Python

import requests

with open('video.mp4', 'rb') as f:
    requests.put(
        uploadUrl,
        data=f,
        headers={'Content-Type': 'video/mp4'}
    )

---

Step 3: Publish Video Using publicUrl

Send the publicUrl received in Step 1 to the TikTok publishing endpoint:

{
  "videoUrl": "https://media.stackvid.dev/uploads/users/usr_123/video-1727123.mp4",
  "text": "Exciting new announcement! 🔥 #trending",
  "targetChannel": "US Fashion Channel"
}

---

2. Credit Escrow Deposit & 100% Automated Refund

To protect server resources from abusive storage exhaustion through abandoned upload URLs:

1. Upon requesting a Presigned URL: The system escrows a small temporary deposit of 2,000 Credits from your wallet (logged as UPLOAD_DEPOSIT).
2. Upon successful publication: When you call POST /api/tiktok/upload and TikTok accepts the video (200 OK), the system automatically refunds 100% (+2,000 Credits) back into your wallet (logged as UPLOAD_DEPOSIT_REFUND).
3. Net cost: The actual cost of your publication remains exactly 50 Credits as listed in the pricing tier.
4. When using Method 1 (Direct URL): No deposit is held or deducted at any point.

---

3. Video URL Validation & Zero-Risk Safety

StackVid performs comprehensive integrity validation on videoUrl before proceeding:

• Direct Download Links Only: The URL must point directly to raw video binary data (returning video/mp4, video/webm, or video/quicktime).
  • ❌ Do not use: Preview webpages (Google Drive view pages, Dropbox preview links, TikTok web links) which return HTML webpages instead of video streams.
  • ✅ Recommended: Direct download links from CDNs, Amazon S3, Google Cloud Storage, or StackVid Presigned URLs.
• Protocols: Must use http:// or https:// without authentication challenges.
• File Size: Supports files up to 500MB. Empty files (0 bytes) are rejected.
• 100% Risk-Free Guarantee:
  • If the provided videoUrl fails validation (e.g. 404 dead link, origin timeout after 60s, or an HTML webpage returned instead of video bytes), the API returns a detailed 400 Bad Request explaining the issue.
  • The Two-Phase Commit pipeline automatically rolls back and refunds all deducted credits for that publication attempt. You never lose credits due to invalid or broken video URLs!