StackVid Docs

Tiếng Việt

English

Tiếng Việt

English

Appearance

Cung Cấp Video & Tải Lên Tệp Tin (Tùy Chọn) ​

Khi xuất bản video lên mạng xã hội qua StackVid API (POST /api/tiktok/upload), bạn cần cung cấp một đường dẫn video trong trường videoUrl.

Hệ thống hỗ trợ 2 phương thức linh hoạt tùy theo hạ tầng hiện có của bạn: Dùng URL có sẵn hoặc Tải file nhị phân lên qua Presigned URL.

1. Lựa Chọn Phương Thức Phù Hợp ​

Phương thứcKhi nào nên dùng?Cần gọi API Upload không?Tạm ứng cọc Credit?
Cách 1: Dùng URL Trực Tiếp (Khuyên dùng)Video đã lưu trữ trên CDN, Amazon S3, Google Cloud, máy chủ riêng hoặc link tải công khai.❌ Không cần. Truyền thẳng URL vào API Đăng bài.❌ 0 Credit (Không cọc).
Cách 2: Tải lên Tệp Tin (Binary Upload)Bạn có tệp video .mp4 cục bộ trên máy/server sau khi render và chưa có link lưu trữ công khai.✅ Có. Xin Presigned URL để tải file lên hệ thống.⏳ Tạm ứng 2.000 Credits (Hoàn trả 100% sau khi đăng).

Cách 1: Sử Dụng URL Video Trực Tiếp (Không Cần Upload) ​

Nếu video của bạn đã có một đường dẫn tải trực tiếp công khai (Direct Download URL), bạn hoàn toàn có thể bỏ qua bước upload.

Chỉ cần truyền trực tiếp URL video vào API xuất bản:

bash
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": "Bộ sưu tập hè siêu hot hôm nay! 🔥 #fashion #fyp",
    "targetChannel": "Kênh Thời Trang Hottrend"
  }'
typescript
import axios from 'axios';

await axios.post(
  'https://api.stackvid.dev/api/tiktok/upload',
  {
    videoUrl: 'https://cdn.yourdomain.com/videos/summer-outfit.mp4',
    text: 'Bộ sưu tập hè siêu hot hôm nay! 🔥 #fashion #fyp',
    targetChannel: 'Kênh Thời Trang Hottrend',
  },
  {
    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': 'Bộ sưu tập hè siêu hot hôm nay! 🔥 #fashion #fyp',
        'targetChannel': 'Kênh Thời Trang Hottrend'
    }
)

Cách 2: Tải Lên Tệp Tin Nhị Phân (Binary Upload) ​

Nếu bot hoặc ứng dụng của bạn sinh ra tệp video cục bộ trên máy chủ (ví dụ render từ FFmpeg hoặc mã nguồn tự động) và bạn cần một nơi lưu trữ tạm thời để xuất bản, StackVid cung cấp sẵn luồng Presigned Upload URL tốc độ cao, hỗ trợ tệp lên đến 500MB+.

Bước 1: Yêu Cầu Cấp Presigned Upload URL ​

Gửi thông tin dung lượng và định dạng tệp lên endpoint POST /api/uploads/presigned-url:

bash
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
  }'
typescript
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;

Response mẫu:

json
{
  "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: Đường dẫn dùng riêng cho phương thức PUT để tải tệp nhị phân lên hệ thống (có hiệu lực trong 15 phút).
  • publicUrl: Đường dẫn tệp tin sau khi tải lên thành công, dùng để truyền vào API Đăng bài ở Bước 3.

Bước 2: Đẩy Dữ Liệu Binary Lên uploadUrl ​

Thực hiện lệnh HTTP PUT trực tiếp với dữ liệu nhị phân (không cần gửi API Key hay multipart/form-data):

bash
curl -X PUT "UPLOAD_URL_TỪ_BƯỚC_1" \
  -H "Content-Type: video/mp4" \
  --data-binary "@/path/to/your/video.mp4"
typescript
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'}
    )

Bước 3: Đăng Video Lên TikTok Bằng publicUrl ​

Sau khi tải tệp lên thành công, truyền publicUrl nhận được từ Bước 1 vào trường videoUrl của API Đăng bài:

json
{
  "videoUrl": "https://media.stackvid.dev/uploads/users/usr_123/video-1727123.mp4",
  "text": "Video siêu phẩm hôm nay! #fyp #trending",
  "targetChannel": "Kênh Thời Trang Hottrend"
}

2. Cơ Chế Tạm Ứng Credit & Hoàn Trả 100% Tự Động ​

Để bảo vệ hạ tầng máy chủ khỏi việc bị spam tạo URL rác mà không đăng tải thực tế, hệ thống áp dụng cơ chế Tạm ứng cọc lưu trữ (Upload Escrow) và Tự động hoàn tiền:

  1. Khi xin Presigned URL: Hệ thống sẽ tạm giữ một khoản cọc nhỏ là 2.000 Credits từ số dư ví của bạn (ghi nhận giao dịch UPLOAD_DEPOSIT).
  2. Khi video được đăng thành công: Khi bạn gọi POST /api/tiktok/upload và video được TikTok tiếp nhận thành công (200 OK), hệ thống sẽ ngay lập tức hoàn trả 100% (+2.000 Credits) vào ví của bạn (ghi nhận giao dịch UPLOAD_DEPOSIT_REFUND).
  3. Thực tế chi phí: Chi phí thực tế bạn chi trả cho 1 bài đăng hoàn chỉnh vẫn chỉ là 50 Credits (bằng đúng bảng giá niêm yết).
  4. Nếu dùng Direct URL có sẵn (Cách 1): Bạn hoàn toàn không mất bất kỳ khoản cọc hay tạm ứng nào.

3. Quy Chuẩn & Cơ Chế Kiểm Tra Video URL An Toàn ​

Hệ thống StackVid tự động xác thực và kiểm tra tính hợp lệ của videoUrl trước khi xử lý nhằm bảo vệ bạn khỏi các sự cố tệp hỏng:

  • Phải là liên kết tải trực tiếp (Direct Download Link): URL phải trỏ thẳng tới tệp tin video thô (trả về định dạng video/mp4, video/webm, video/quicktime).
    • ❌ Không sử dụng: Link trang web xem trước (Google Drive View page, Dropbox preview, link bài viết TikTok, v.v.) vì các link này trả về mã HTML trang web thay vì tệp video.
    • ✅ Nên sử dụng: Direct link tải về trực tiếp từ CDN, Amazon S3, Google Cloud Storage, hoặc link được cấp từ API Presigned URL của StackVid.
  • Giao thức & Truy cập: Bắt buộc sử dụng giao thức http:// hoặc https://. Đường dẫn phải cho phép máy chủ tải về công khai mà không yêu cầu đăng nhập hay giải mã captcha.
  • Dung lượng tệp: Hỗ trợ kích thước video lên tới 500MB. Tệp tin không được là file rỗng (0 bytes).
  • Bảo vệ rủi ro Credit (100% Risk-Free Rollback):
    • Nếu videoUrl bạn cung cấp bị lỗi (link chết 404, server nguồn quá tải timeout sau 60 giây, hoặc URL trả về mã HTML trang web thay vì video), hệ thống sẽ trả về mã lỗi 400 Bad Request kèm thông báo chi tiết lý do.
    • Cơ chế bảo đảm Two-Phase Commit sẽ tự động hủy bỏ lệnh và hoàn trả 100% số credit đã trừ của lượt đăng bài đó về ví của bạn. Bạn không bao giờ bị mất credit do lỗi đường dẫn video!

StackVid - Multi-Platform Video & Social Commerce Automation Platform.

Copyright © 2026 StackVid SaaS. All rights reserved.