Appearance
TikTok General: Tìm Kiếm Video Bằng Hình Ả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 với ảnh đầu vào, dựa trên dữ liệu ảnh Base64.
Thông Tin Endpoint
- Phương thức:
POST - Đường dẫn:
/v1/tiktok/general - Định dạng dữ liệu:
Content-Type: application/json - Xác thực: Header
X-API-Key(Yêu cầu quyền truy cập sàntiktok)
1. Tham Số Request Body (JSON)
| Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|
image_base64 | string | Bắt buộc | Chuỗi ảnh JPEG mã hóa Base64 thuần túy (không chứa tiền tố data:image/...;base64,) |
TIP
Chuẩn hóa chuỗi Base64 trước khi gửi: Nếu chuỗi Base64 của bạn được sinh ra từ trình duyệt dạng Data URL (data:image/jpeg;base64,/9j/4AAQ...), hãy cắt bỏ phần header phía trước:
javascript
const cleanBase64 = rawDataUrl.replace(/^data:image\/\w+;base64,/, '');2. Ví Dụ Request
bash
curl -X POST "https://control.ecomtools.vn/v1/tiktok/general" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJ..."
}'python
import base64
import httpx
API_KEY = "YOUR_API_KEY"
URL = "https://control.ecomtools.vn/v1/tiktok/general"
with open("anh.jpg", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode("ascii")
response = httpx.post(
URL,
headers={"X-API-Key": API_KEY},
json={"image_base64": image_base64},
timeout=60.0,
)
print(response.json())javascript
import fs from "fs";
import axios from "axios";
const imageBase64 = fs.readFileSync("anh.jpg").toString("base64");
const response = await axios.post(
"https://control.ecomtools.vn/v1/tiktok/general",
{ image_base64: imageBase64 },
{
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
timeout: 60000
}
);
console.log(response.data);php
<?php
$imageBase64 = base64_encode(file_get_contents("anh.jpg"));
$ch = curl_init("https://control.ecomtools.vn/v1/tiktok/general");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: YOUR_API_KEY",
],
CURLOPT_POSTFIELDS => json_encode(["image_base64" => $imageBase64]),
]);
echo curl_exec($ch);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ấu trúc dưới đây là minh họa danh sách video tìm thấy:
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
}
}NOTE
Về field videos[]: Danh sách video có thể rỗng (videos: []) nếu upstream không tìm thấy video khớp với ảnh đầu vào — khi đó has_more là false.
4. Mã Lỗi
Gateway chuẩn hóa các lỗi hệ thống theo envelope thống nhất (error.code + error.message), phần mã lỗi nghiệp vụ (nếu có) nằm trong JSON gốc của upstream:
| 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 |
422 | VALIDATION_ERROR | Thiếu image_base64 hoặc để trống |
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ờ |