Tài liệu API
ISO 27001SOC 2 CertifiedGDPR Compliant

API phát hiện ảnh AI

Tài liệu đầy đủ để tích hợp API phát hiện ảnh AI TruthScan vào ứng dụng của bạn.

Thử không cần mã bằng cách truy cập endpoint FastAPI: https://detect-image.truthscan.com/docs

Xác thực

TruthScan dùng API key để cho phép truy cập API. Bạn lấy API key tại đầu trang trong cổng nhà phát triển.

Thông thường TruthScan gửi API key trong phần thân (body) JSON của request theo dạng ví dụ dưới đây. Ngoại lệ: endpoint check-user-credits nhận API key qua header HTTP (không dùng JSON body) — ví dụ `Authorization: Bearer <API_KEY>` hoặc header `apikey` như trong ví dụ curl ở mục Kiểm tra credit người dùng.

{
  "key": "YOUR API KEY GOES HERE"
}

Thay YOUR API KEY GOES HERE bằng API key cá nhân của bạn.

Trình phát hiện ảnh AI

Detect (quy trình 3 bước)

Quy trình phát hiện ảnh AI gồm các bước sau:

  • Lấy URL tải lên đã ký sẵn (pre-signed)
  • Tải lên ảnh
  • Gửi ảnh để phát hiện AI

1. Lấy URL tải lên đã ký sẵn

Yêu cầu URL ký sẵn từ API để tải tệp ảnh lên máy chủ lưu trữ an toàn.

Định dạng được hỗ trợ

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF

Lưu ý

Cần xóa khoảng trắng trong tên tệp ảnh khi yêu cầu URL ký sẵn.

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

Ví dụ yêu cầu

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

Ví dụ phản hồi

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. Tải lên ảnh

Dùng 'presigned_url' để tải lên bằng PUT. Đặt đúng Content-Type theo định dạng ảnh.

Lưu ý

Cần xóa khoảng trắng trong tên tệp khi tải lên.

Ví dụ yêu cầu

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

Giới hạn kích thước

  • Tối thiểu: 1KB
  • Tối đa: 10MB

Giữ nguyên định dạng trong suốt quá trình tải. Tải thành công trả về mã 200.

3. Gửi ảnh để phát hiện AI

Sau khi tải, gửi ảnh phát hiện AI với 'file_path' từ bước trước.

POST https://detect-image.truthscan.com/detect

Ví dụ yêu cầu

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

'FILE_PATH' là đường dẫn từ phản hồi bước 'Lấy URL tải lên đã ký sẵn'.

Tham số tùy chọn

  • generate_preview: Đặt 'true' để tạo URL xem trước ảnh (mặc định: 'false')
  • document_type: Loại tài liệu (mặc định: 'Image')
  • email: Email phục vụ xử lý
  • generate_analysis_details: Đặt 'true' để bật phân tích AI sâu (mặc định: 'false'). Khi bật, phản hồi /query gồm analysis_results_status và analysis_results.

Ví dụ phản hồi

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

Phản hồi gồm ID ảnh duy nhất để theo dõi trạng thái phát hiện.

Truy vấn

Endpoint nhận ID ảnh từ /detect và trả về trạng thái cùng kết quả đầy đủ của phát hiện AI, gồm metadata, OCR và phân tích mô hình ML.

POST https://detect-image.truthscan.com/query

Ví dụ yêu cầu

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "IMAGE-ID-GOES-HERE"
}'

Ví dụ phản hồi

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Cách đọc kết quả

  • result: Điểm 1–100: khả năng ảnh do AI tạo; điểm cao hơn = khả năng AI cao hơn.
  • final_result: Kết luận tổng thể (ví dụ: 'AI Generated', 'Real', 'Digitally Edited', 'AI Edited').
  • confidence: Điểm tin cậy của phát hiện.
  • detection_step: Giai đoạn hoàn tất: 1 = chỉ metadata; 2 = metadata và OCR; 3 = metadata, OCR và ML (đầy đủ nhất).
  • metadata: Thông tin trích từ metadata ảnh (ExifTool và Pillow).
  • ocr: Kết quả OCR phục vụ phát hiện watermark.
  • ml_model: Kết quả từ mô hình học máy.
  • preview_url: URL ảnh xem trước (nếu generate_preview = true).
  • heatmap_status: Trạng thái tạo heatmap ('pending' hoặc 'ready'). Heatmap tạo bất đồng bộ: ban đầu heatmap_status có thể 'pending' và heatmap_url vắng/null; khi sẵn sàng thì 'ready' và có URL.
  • heatmap_url: URL heatmap khi heatmap_status là 'ready'. Chỉ với ảnh có điểm ≥ 20.
  • analysis_results_status: Trạng thái phân tích AI sâu ('pending', 'done', 'skipped' hoặc null). 'pending' = tiếp tục poll /query; 'done' = có analysis_results; 'skipped'/null = không có phân tích sâu.
  • analysis_results: Kết quả phân tích AI sâu (khi analysis_results_status = 'done'): agreement, confidence (0–100), keyIndicators, detailedReasoning, visualPatterns, recommendations.

Lưu ý

Heatmap tạo bất đồng bộ. Ban đầu heatmap_status có thể 'pending' và heatmap_url vắng/null; khi sẵn sàng thì 'ready' và có URL. Chỉ tạo heatmap cho ảnh có điểm ≥ 20.

Ví dụ: "result": 90.24 nghĩa là khả năng cao ảnh do AI tạo; "final_result": "AI Generated" là kết luận; "confidence": 90.24 là độ tin cậy. "detection_step": 3 nghĩa đã phân tích đủ (metadata, OCR, ML). "heatmap_status": "ready" và "heatmap_url" cho phép xem vùng được đánh dấu AI.

Kết quả phân tích (phân tích sâu bất đồng bộ)

Khi đặt 'generate_analysis_details' thành 'true' trong /detect, TruthScan chạy phân tích AI sâu nền sau phát hiện ban đầu. Phản hồi /query đầu có thể đã 'done' với kết quả chính, nhưng analysis_results_status vẫn có thể 'pending'. Bạn có thể dùng kết quả ban đầu ngay và poll thêm để lấy phân tích sâu.

1. Kết quả ban đầu sẵn sàng (phân tích vẫn đang chạy)

Khi gửi với 'generate_analysis_details': true và lần đầu truy vấn đã 'done', các kết quả cốt lõi (result, final_result, confidence) đã sẵn sàng. Tuy nhiên analysis_results_status có thể 'pending' — phân tích AI sâu vẫn đang chạy nền.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

Nên làm gì

Dùng ngay kết quả phát hiện ban đầu (result, final_result, confidence, metadata, ocr, ml_model). Nếu cần phân tích sâu, tiếp tục gọi /query với cùng ID ảnh cho đến khi analysis_results_status không còn 'pending'.

2. Tiếp tục poll để lấy phân tích

Gọi /query với cùng ID ảnh. Kiểm tra analysis_results_status mỗi lần. Khi chuyển từ 'pending' sang 'done', đối tượng analysis_results được điền đầy đủ.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Phân tích hoàn tất — phản hồi đầy đủ

Khi analysis_results_status là 'done', analysis_results chứa phân tích sâu: mức đồng thuận, chỉ báo, lý giải, mẫu thị giác và đề xuất.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Khi không có phân tích sâu

Nếu analysis_results_status là 'skipped', null hoặc không có, phân tích sâu không được tạo cho ảnh này — thường do không bật 'generate_analysis_details' hoặc loại ảnh/kịch bản không hỗ trợ. Coi kết quả phát hiện ban đầu là cuối cùng.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Các trường trong phân tích sâu

  • analysis_results_status: 'pending' = đang xử lý; 'done' = có kết quả; 'skipped'/null = không áp dụng
  • analysis_results.agreement: Mức đồng thuận với phát hiện ban đầu (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Độ tin cậy phân tích sâu (0–100)
  • analysis_results.keyIndicators: Danh sách bất thường thị giác cụ thể
  • analysis_results.detailedReasoning: Giải thích 2–4 câu về lý do phân loại
  • analysis_results.visualPatterns: Các mẫu phong cách (ví dụ nhiễu đặc trưng mô hình khuếch tán)
  • analysis_results.recommendations: Đề xuất hành động để xác minh thêm

Kiểm tra credit người dùng

Endpoint này nhận API key qua header HTTP (không gửi trong body JSON). Dùng `Authorization: Bearer <API_KEY>` hoặc header `apikey` như trong ví dụ curl bên dưới. Phản hồi trả về chi tiết credit.

GET https://detect-image.truthscan.com/check-user-credits

Ví dụ yêu cầu

curl -X 'GET' \
  'https://detect-image.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Ví dụ phản hồi

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Kiểm tra sức khỏe

Kiểm tra trạng thái dịch vụ phát hiện ảnh AI.

GET https://detect-image.truthscan.com/health

Ví dụ yêu cầu

curl -X 'GET' \
  'https://detect-image.truthscan.com/health' \
  -H 'accept: application/json'

Ví dụ phản hồi

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

Phản hồi "healthy" nghĩa là dịch vụ hoạt động bình thường.

Lỗi

Hầu hết lỗi do tham số gửi sai. Kiểm tra kỹ tham số từng lệnh gọi và thử mã ví dụ.

Mã lỗi chung tuân theo chuẩn REST:

Mã lỗiÝ nghĩa
400Bad Request — Yêu cầu không hợp lệ.
403Forbidden — API key không hợp lệ hoặc không đủ credit xử lý ảnh.
404Not Found — Tài nguyên không tồn tại.
405Method Not Allowed — Truy cập tài nguyên bằng phương thức không hợp lệ.
406Not Acceptable — Định dạng yêu cầu không phải JSON.
410Gone — Tài nguyên tại endpoint này đã bị gỡ.
422Invalid Request Body — Body không đúng định dạng hoặc thiếu tham số.
429Too Many Requests — Gửi quá nhiều yêu cầu, vui lòng chậm lại.
500Internal Server Error — Lỗi máy chủ, thử lại sau.
503Service Unavailable — Bảo trì tạm thời, thử lại sau.

Sự cố thường gặp và cách xử lý

Vấn đề xác thực

"User verification failed" (403)

Nguyên nhân: API key không hợp lệ hoặc hết hạn

Cách xử lý:

  1. Xác minh API key đúng
  2. Kiểm tra API key còn hoạt động trong tài khoản
  3. Thử tạo lại API key

"Not enough credits" (403)

Nguyên nhân: Không đủ credit xử lý ảnh

Cách xử lý:

  1. Kiểm tra credit bằng /check-user-credits
  2. Mua thêm credit nếu cần
  3. Tối ưu kích thước ảnh trước khi tải để tiêu ít credit hơn

Vấn đề xác thực đầu vào

"Unsupported file format" (400)

Nguyên nhân: Định dạng ảnh không hỗ trợ hoặc không hợp lệ

Cách xử lý:

  1. Xác minh định dạng được hỗ trợ (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
  2. Đảm bảo tệp không hỏng
  3. Kiểm tra header Content-Type khi tải lên

"File too large" (400)

Nguyên nhân: Vượt giới hạn 10MB

Cách xử lý:

  1. Thu nhỏ hoặc nén ảnh dưới 10MB
  2. Kiểm tra kích thước trước khi tải
  3. Ưu tiên định dạng hiệu quả như WebP nếu có thể

Vấn đề xử lý

"Request timeout" (WebSocket)

Nguyên nhân: Xử lý ảnh quá lâu

Cách xử lý:

  1. Thử ảnh nhỏ hơn hoặc đơn giản hơn
  2. Kiểm tra máy chủ có tải cao không
  3. Thử lại yêu cầu

Trạng thái tài liệu "failed"

Nguyên nhân: Xử lý thất bại vì nhiều lý do

Cách xử lý:

  1. Kiểm tra ảnh đạt yêu cầu (1KB – 10MB)
  2. Xác minh định dạng được hỗ trợ
  3. Đảm bảo tải lên thành công trước khi gửi phát hiện
  4. Liên hệ hỗ trợ nếu vẫn lỗi

Vấn đề tải lên

"Image upload failed" (403/400)

Nguyên nhân: URL ký sẵn không hợp lệ hoặc hết hạn, hoặc lỗi máy chủ lưu trữ

Cách xử lý:

  1. Dùng URL ký sẵn ngay sau khi nhận (có thể hết hạn)
  2. Kiểm tra Content-Type đúng với định dạng ảnh
  3. Xóa khoảng trắng trong tên tệp trước khi tải
  4. Tạo URL ký sẵn mới nếu URL cũ hết hạn

"Invalid pre-signed URL" (400)

Nguyên nhân: Tên tệp có khoảng trắng hoặc URL ký sẵn hết hạn/hỏng

Cách xử lý:

  1. Xóa mọi khoảng trắng trong tên tệp trước khi yêu cầu URL ký sẵn
  2. Chỉ dùng chữ, số, gạch ngang và gạch dưới trong tên tệp
  3. Tạo URL ký sẵn mới nếu cần

Cần hỗ trợ?

Để biết thêm về API hoặc hỗ trợ kỹ thuật, vui lòng liên hệ chúng tôi.

Câu hỏi thường gặp về API

Câu trả lời cho các thắc mắc phổ biến về API phát hiện ảnh AI.