Appearance
TikTok General: Tìm Kiếm Video Bằng Tệp Ảnh
API cho phép tìm kiếm các video TikTok (nội dung chung, ngoài sàn TikTok Shop) có chứa sản phẩm tương đồng, bằng cách tải trực tiếp tệp ảnh vật lý lên (không cần tự mã hóa Base64).
Thông Tin Endpoint
- Phương thức:
POST - Đường dẫn:
/v1/tiktok/general/upload - Định dạng dữ liệu:
multipart/form-data - Xác thực: Header
X-API-Key(Yêu cầu quyền truy cập sàntiktok)
1. Tham Số Form-Data
| Tên trường | Kiểu dữ liệu | Bắt buộc | Giới hạn dung lượng | Định dạng hỗ trợ |
|---|---|---|---|---|
file | binary | Bắt buộc | $\le$ 12MB | JPG, JPEG, PNG, WEBP |
CAUTION
Giới hạn dung lượng 12MB: Nếu file upload vượt quá 12MB, Gateway sẽ ngắt kết nối và phản hồi mã lỗi 413 PAYLOAD_TOO_LARGE nhằm tối ưu băng thông và bộ nhớ. Hãy nén ảnh trước khi tải lên nếu cần.
2. Ví Dụ Upload Tệp
bash
curl -X POST "https://control.ecomtools.vn/v1/tiktok/general/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/duong/dan/anh.jpg"python
import httpx
API_KEY = "YOUR_API_KEY"
URL = "https://control.ecomtools.vn/v1/tiktok/general/upload"
with open("anh.jpg", "rb") as f:
files = {"file": ("anh.jpg", f, "image/jpeg")}
headers = {"X-API-Key": API_KEY}
response = httpx.post(URL, headers=headers, files=files, timeout=60.0)
print(response.json())javascript
import FormData from "form-data";
import fs from "fs";
import axios from "axios";
const form = new FormData();
form.append("file", fs.createReadStream("anh.jpg"));
const response = await axios.post("https://control.ecomtools.vn/v1/tiktok/general/upload", form, {
headers: {
...form.getHeaders(),
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(response.data);3. Cấu Trúc Response Trả Về
Gateway trả về nguyên văn (pass-through) JSON từ dịch vụ upstream TikTok — cùng cấu trúc với endpoint /v1/tiktok/general:
json
{
"code": 0,
"message": "success",
"data": {
"videos": [
{
"video_id": "7492819401234567890",
"title": "Review áo khoác bomber form rộng 2026",
"cover_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/9a8b7c6d5e4f1234567890abcdef.jpg",
"video_url": "https://www.tiktok.com/@shop/video/7492819401234567890",
"author": {
"unique_id": "fashion.studio.vn",
"nickname": "Fashion Studio VN"
}
}
],
"cursor": 20,
"has_more": true
}
}4. Mã Lỗi
| HTTP Status | error.code | Nguyên nhân |
|---|---|---|
401 | INVALID_API_KEY | Key không hợp lệ hoặc thiếu header X-API-Key |
403 | PLATFORM_NOT_ALLOWED | Key không có quyền truy cập sàn tiktok |
413 | PAYLOAD_TOO_LARGE | Tệp upload vượt quá 12MB |
429 | RATE_LIMITED / QUOTA_EXCEEDED | Vượt giới hạn RPM hoặc hạn mức tháng |
502 | UPSTREAM_ERROR | Dịch vụ upstream TikTok lỗi hoặc quá thời gian chờ |