Skip to content

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àn tiktok)

1. Tham Số Request Body (JSON) ​

Tên trườngKiểu dữ liệuBắt buộcMô tả
image_base64stringBắt buộcChuỗ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 Statuserror.codeNguyên nhân
401INVALID_API_KEYKey không hợp lệ hoặc thiếu header X-API-Key
403PLATFORM_NOT_ALLOWEDKey không có quyền truy cập sàn tiktok
422VALIDATION_ERRORThiếu image_base64 hoặc để trống
429RATE_LIMITED / QUOTA_EXCEEDEDVượt giới hạn RPM hoặc hạn mức tháng
502UPSTREAM_ERRORDịch vụ upstream TikTok lỗi hoặc quá thời gian chờ

ImageCoreAPI — Cổng API tìm kiếm hình ảnh Shopee & TikTok Shop