Base URL https://apidouyin.autoup.vn

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-Typeapplication/json
Body{ "image_base64": "<ẢNH_BASE64>", "country": "cn" }
countryTù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ườngKiểuMô tả
okboolRequest thành công
search_outcomestringvideos = có video · empty = không có · blocked = bị chặn rủi ro · products/upstream_error
video_countintSố video trả về
videos[].aweme_idstringMã video (định danh duy nhất)
videos[].descstringTiêu đề / mô tả video
videos[].coverstringẢnh bìa (JPEG, hiển thị được trên web)
videos[].share_urlstringLink chia sẻ ổn định để mở lại video
videos[].video_urlstringLink phát trực tiếp (có thể hết hạn theo thời gian)
videos[].authorstringTên tác giả
videos[].author_idstringĐịnh danh tác giả (sec_uid)
videos[].durationintThời lượng (mili-giây)
videos[].digg_countintLượt thích
videos[].play_countintLượ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ĩaXử lý
200Thành côngĐọc videos
400Thiếu/sai ảnh (không phải JPEG/PNG/WebP)Kiểm tra định dạng & base64
401Sai/thiếu API keyKiểm tra header X-API-Key
413Ảnh quá lớn (>4 MB)Giảm dung lượng ảnh
502Douyin trả rỗng / không giải mã đượcThử lại hoặc đổi ảnh
503Không có box rảnh phù hợpThử lại sau ít giây
504Box không phản hồi kịp thờiThử 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_url là link ổn định để mở lại; video_url có thể hết hạn — nếu cần lưu, hãy tải bằng video_url ngay 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.