Skip to content

Tổng Quan & Bắt Đầu Nhanh ​

Chào mừng bạn đến với tài liệu tích hợp ImageCoreAPI. Hệ thống cung cấp API tìm sản phẩm bằng ảnh trên Shopee và TikTok Shop, cùng API tìm video bằng ảnh trên TikTok và Douyin.


1. Thông Tin Base URL ​

Tất cả các yêu cầu API đều gửi tới Base URL chuẩn:

Môi trườngBase URLGhi chú
Productionhttps://control.ecomtools.vn/v1Hỗ trợ kết nối bảo mật HTTPS

NOTE

Các endpoint trong tài liệu này dùng cùng tên miền với trang tài liệu: control.ecomtools.vn.


2. Quy Trình Tích Hợp Trong 3 Bước ​

Bước 1: Nhận API Key từ Quản trị viên ​

Quản trị viên sẽ cấp cho bạn một chuỗi API Key định dạng chuẩn:

text
mkuph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Khóa bắt đầu bằng tiền tố mkuph_.
  • Hãy bảo mật khóa này trong biến môi trường hệ thống (.env), không đưa trực tiếp vào mã nguồn client-side.

Bước 2: Kiểm tra tính hợp lệ của Key ​

Gửi một request GET /v1/me để kiểm tra quyền hạn sàn (shopee, tiktok) và hạn mức của key:

bash
curl -X GET "https://control.ecomtools.vn/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"
python
import httpx

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://control.ecomtools.vn/v1"

response = httpx.get(f"{BASE_URL}/me", headers={"X-API-Key": API_KEY})
print(response.json())
javascript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://control.ecomtools.vn/v1";

const response = await fetch(`${BASE_URL}/me`, {
  headers: { "X-API-Key": API_KEY }
});
console.log(await response.json());
php
<?php
$apiKey  = "YOUR_API_KEY";
$baseUrl = "https://control.ecomtools.vn/v1";

$ch = curl_init("$baseUrl/me");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);

echo $res;

TIP

Việc gọi endpoint /v1/me hoàn toàn miễn phí và không trừ vào hạn mức tìm kiếm hàng ngày của bạn.


Bước 3: Lựa chọn nền tảng tìm kiếm ​

  • Tìm kiếm trên Shopee (POST /v1/shopee/search):

    • Yêu cầu: Cần hình ảnh (image_key, image_url hoặc image_base64) và chuỗi Cookie Shopee hợp lệ.
    • Chi tiết thông số xem tại Shopee API Reference.
  • Tìm kiếm trên TikTok Shop (POST /v1/tiktok/search):

  • Upload ảnh lên CDN TikTok (POST /v1/tiktok/upload):

    • Cho phép tải trực tiếp tệp ảnh vật lý (tối đa 12MB) để lấy URL CDN.
    • Chi tiết thông số xem tại TikTok Upload API Reference.
  • Tìm video TikTok bằng ảnh (POST /v1/tiktok/general):

    • Yêu cầu: Chuỗi ảnh mã hóa Base64; tìm video TikTok nội dung chung (ngoài TikTok Shop).
    • Chi tiết thông số xem tại TikTok General API Reference.
  • Tìm video TikTok bằng tệp ảnh (POST /v1/tiktok/general/upload):

  • Tìm video Douyin bằng ảnh (POST /v1/douyin/vision):


3. Checklist Tích Hợp Nhanh ​

Mục kiểm traTrạng thái cần đạt
API KeyĐã cấu hình vào biến môi trường IMAGECORE_API_KEY
HeaderLuôn gửi X-API-Key hoặc Authorization: Bearer trong mỗi request
Timeout ClientCấu hình timeout tối thiểu 30s – 60s vì tìm kiếm ảnh AI đòi hỏi thời gian xử lý đa dịch vụ
Xử lý mã lỗiĐã bắt các mã lỗi 401 (Key không hợp lệ), 429 (Vượt hạn mức/Rate limit)

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