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 kiếm sản phẩm bằng hình ảnh trên hai nền tảng thương mại điện tử lớn nhất hiện nay: Shopee và TikTok Shop.

---

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ường	Base URL	Ghi chú
Production / Staging	https://api.yourdomain.com/v1	Hỗ trợ kết nối bảo mật HTTPS

NOTE

Hãy thay thế api.yourdomain.com bằng tên miền hoặc địa chỉ IP máy chủ API do Quản trị viên bàn giao cho bạn.

---

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:

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:

cURL

curl -X GET "https://api.yourdomain.com/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import httpx

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.yourdomain.com/v1"

response = httpx.get(f"{BASE_URL}/me", headers={"X-API-Key": API_KEY})
print(response.json())

JavaScript / Node.js

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.yourdomain.com/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://api.yourdomain.com/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):

  • Yêu cầu: Cần chuỗi ảnh mã hóa Base64.
  • Chi tiết thông số xem tại TikTok Search API Reference.

• 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.

---

3. Checklist Tích Hợp Nhanh

Mục kiểm tra	Trạng thái cần đạt
API Key	Đã cấu hình vào biến môi trường IMAGECORE_API_KEY
Header	Luôn gửi X-API-Key hoặc Authorization: Bearer trong mỗi request
Timeout Client	Cấ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)