Douyin Image → Video Search API
API tìm video trên Douyin (抖音) bằng hình ảnh: gửi 1 tấm ảnh, nhận về danh sách video liên quan ở tab Tổng hợp (综合) — kèm ảnh bìa, link chia sẻ, tác giả và lượt tương tác. Tích hợp qua HTTP đơn giản.
Base URL
https://apidouyin.autoup.vnĐịnh dạng JSON (UTF-8)
Xác thực
X-API-KeyẢnh tối đa 4 MB (JPEG/PNG/WebP)
1. Xác thực
Mọi request (trừ GET /health) phải kèm API key do chúng tôi cấp, đặt trong header:
X-API-Key: <API_KEY_CỦA_BẠN>Sai/thiếu key →
401 Unauthorized. Vui lòng giữ key bí mật — không nhúng vào ứng dụng client công khai.2. Tìm video bằng ảnh
POST/general Khuyến nghị
Gửi 1 tấm ảnh (base64), nhận về danh sách video Douyin liên quan. Ảnh JPEG / PNG / WebP, tối đa 4 MB.
| Content-Type | application/json |
|---|---|
| Body | { "image_base64": "<ẢNH_BASE64>", "country": "cn" } |
| country | Tùy chọn — chọn box theo quốc gia (mặc định: box rảnh bất kỳ). |
curl -X POST "https://apidouyin.autoup.vn/general" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image_base64":"<ẢNH_BASE64>"}'Chỉ cần phần base64 thuần (không kèm tiền tố
data:image/...;base64,).Cấu trúc kết quả
{
"ok": true,
"search_outcome": "videos",
"video_count": 10,
"videos": [
{
"aweme_id": "6979055735229500684",
"desc": "这个 #折叠小桌子 很实用,床上随手折叠很方便",
"cover": "https://p3-sign.douyinpic.com/....jpeg",
"share_url": "https://www.iesdouyin.com/share/video/6979055735229500684/",
"video_url": "https://www.douyin.com/aweme/v1/play/?video_id=...",
"author": "一点通",
"author_id": "MS4wLjABAAAA....",
"duration": 15000,
"digg_count": 740099,
"play_count": 0
}
]
}| Trường | Kiểu | Mô tả |
|---|---|---|
ok | bool | Request thành công |
search_outcome | string | videos = có video · empty = không có · blocked = bị chặn rủi ro · products/upstream_error |
video_count | int | Số video trả về |
videos[].aweme_id | string | Mã video (định danh duy nhất) |
videos[].desc | string | Tiêu đề / mô tả video |
videos[].cover | string | Ảnh bìa (JPEG, hiển thị được trên web) |
videos[].share_url | string | Link chia sẻ ổn định để mở lại video |
videos[].video_url | string | Link phát trực tiếp (có thể hết hạn theo thời gian) |
videos[].author | string | Tên tác giả |
videos[].author_id | string | Định danh tác giả (sec_uid) |
videos[].duration | int | Thời lượng (mili-giây) |
videos[].digg_count | int | Lượt thích |
videos[].play_count | int | Lượt xem (có thể 0 nếu Douyin ẩn) |
Khi không có video phù hợp:
video_count = 0 và search_outcome là empty hoặc blocked. Hãy thử ảnh khác, rõ nét, chụp thẳng chủ thể.Tìm lại bằng URI ảnh đã tải Nâng cao
Nếu bạn đã có image_query_uri từ lần tìm trước, có thể tìm lại (nhanh hơn, không gửi lại ảnh):
curl -X POST "https://apidouyin.autoup.vn/general" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fields":{"image_uri":"<IMAGE_QUERY_URI>"}}'3. Kiểm tra tình trạng
GET/health Không cần key
Dùng để kiểm tra dịch vụ còn hoạt động.
{ "ok": true, "boxes_online": 1 }4. Mã lỗi
| HTTP | Ý nghĩa | Xử lý |
|---|---|---|
| 200 | Thành công | Đọc videos |
| 400 | Thiếu/sai ảnh (không phải JPEG/PNG/WebP) | Kiểm tra định dạng & base64 |
| 401 | Sai/thiếu API key | Kiểm tra header X-API-Key |
| 413 | Ảnh quá lớn (>4 MB) | Giảm dung lượng ảnh |
| 502 | Douyin trả rỗng / không giải mã được | Thử lại hoặc đổi ảnh |
| 503 | Không có box rảnh phù hợp | Thử lại sau ít giây |
| 504 | Box không phản hồi kịp thời | Thử lại |
Response lỗi có dạng:
{ "detail": "Cần image_base64 (ảnh) hoặc fields.image_uri cho /general" }5. Ví dụ code
Python
Node.js
PHP
import base64, requests
img = base64.b64encode(open("anh.jpg", "rb").read()).decode()
r = requests.post(
"https://apidouyin.autoup.vn/general",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"image_base64": img},
timeout=140,
)
data = r.json()
for v in data.get("videos", []):
print(v["aweme_id"], v["desc"][:40], v["share_url"])import fs from "fs";
const img = fs.readFileSync("anh.jpg").toString("base64");
const res = await fetch("https://apidouyin.autoup.vn/general", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ image_base64: img }),
});
const data = await res.json();
for (const v of data.videos || []) console.log(v.aweme_id, v.share_url);$img = base64_encode(file_get_contents("anh.jpg"));
$ch = curl_init("https://apidouyin.autoup.vn/general");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["image_base64" => $img]),
]);
$data = json_decode(curl_exec($ch), true);
foreach ($data["videos"] as $v) echo $v["aweme_id"]." ".$v["share_url"]."\n";6. Lưu ý
- Ảnh rõ nét, chụp thẳng chủ thể cho kết quả tốt nhất.
- Thời gian phản hồi thường vài giây/tấm — nên đặt timeout ≥ 120 giây.
share_urllà link ổn định để mở lại;video_urlcó thể hết hạn — nếu cần lưu, hãy tải bằngvideo_urlngay khi nhận.coverđã chọn định dạng JPEG hiển thị được trên trình duyệt.- Liên hệ chúng tôi để được cấp/đổi API key và tăng hạn mức.