Tài liệu API

API AI Image Detection

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

Thử trực tiếp không cần code bằng cách truy cập endpoint FastAPI: https://detect-image.truthscan.com/docs

Xác thực

TruthScan dùng API key để truy cập API. Bạn lấy API key tại đầu trang trong developer portal.

TruthScan yêu cầu API key trong body JSON của request (trừ endpoint chỉ ghi header auth, ví dụ check-user-credits):

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

Bạn phải thay YOUR API KEY GOES HERE bằng API key cá nhân của mình.

AI Image Detector

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

Quy trình AI Image Detection gồm các bước sau:

Lấy Pre-signed Upload URL
Upload ảnh
Gửi ảnh để phát hiện (Detect)

1. Lấy Pre-signed Upload URL

Bắt đầu bằng cách yêu cầu pre-signed URL từ API. URL này cho phép upload file ảnh lên storage một cách an toàn.

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

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

Filename

Loại bỏ khoảng trắng trong tên file ảnh khi yêu cầu pre-signed URL.

Với file PDF, chỉ ảnh đầu tiên được phát hiện (luồng single-file).

Dùng tên file .zip trên endpoint này khi bạn định gửi ZIP qua bulk upload.

Query parameters

file_name (bắt buộc) — Tên file gốc; server có thể chuẩn hóa (khoảng trắng và ký tự không an toàn được điều chỉnh). Dùng phần mở rộng .zip cho bulk upload.
expiration (tùy chọn) — Thời gian sống của presigned URL tính bằng giây (mặc định: 3600).

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

Ví dụ request

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

Ví dụ response

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id là UUID mới được tạo cho yêu cầu upload này (để tương quan/logging). id dùng cho /detect hoặc /bulk-upload được gán khi gọi các endpoint đó trừ khi bạn truyền id tùy chọn trên /detect.

2. Upload ảnh

Dùng presigned_url đã cấp để upload ảnh bằng PUT. Đảm bảo Content-Type đúng theo định dạng ảnh.

Filename

Loại bỏ khoảng trắng trong tên file khi upload.

Đặt Content-Type khớp chính xác với phần mở rộng file

image/jpeg: jpg, jpeg, jfif
image/png: png
image/webp: webp
image/heic: heic
image/heif: heif
image/avif: avif
image/bmp: bmp
image/tiff: tiff, tif
image/gif: gif
image/svg+xml: svg
application/pdf: pdf

Lỗi thường gặp cần tránh

Không dùng image/jpg (sai). Hãy dùng image/jpeg.
Không lệch giữa file và header (ví dụ file .png với image/jpeg).
Không đổi phần mở rộng mà không cập nhật header (hoặc ngược lại).
Không để khoảng trắng trong filename khi request/upload.

Ví dụ request

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Ví dụ upload thêm (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

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

Kích thước tối thiểu: 1KB
Kích thước tối đa: 10MB

Đảm bảo định dạng file nhất quán trong suốt quá trình upload. Upload thành công trả về HTTP 200.

3. Gửi ảnh để AI Detection

Sau khi upload, gửi ảnh để phát hiện bằng cách tham chiếu file_path từ bước trước. Với PDF, chỉ ảnh đầu tiên được phân tích/phát hiện.

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

Ví dụ request

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": true
}'

FILE_PATH là đường dẫn trả về từ bước presigned-URL (ví dụ uploads/...). Ghép full URL với storage host như trong ví dụ.

Tham số tùy chọn

id: Chuỗi UUID tùy chọn. Nếu bỏ qua, server tạo document id mới. Nếu truyền, id không được tồn tại trước; nếu không API trả lỗi.
generate_preview: Đặt true để tạo preview URL cho ảnh (mặc định: true). Đặt false để bỏ qua tạo preview.
document_type: Loại document (mặc định: Image).
email: Email phục vụ xử lý.
generate_analysis_details: Đặt false để bỏ qua phân tích chi tiết (mặc định: true).
generate_heatmap_overlayed: Điều khiển cách tạo ảnh heatmap khi heatmap được sinh (mặc định: true). Khi true, heatmap được blend lên ảnh gốc (overlay chuẩn). Khi false, dịch vụ trả heatmap trong suốt: RGBA với bản đồ kích hoạt màu JET và alpha từ model, nền trong suốt để composite trong UI.
generate_heatmap_normalized: Khi false, tạo heatmap bỏ bước chuẩn hóa cho activation map (mặc định: true). Dùng cùng generate_heatmap_overlayed để điều chỉnh giao diện heatmap.
model: Gợi ý model hoặc routing (mặc định: generic). Ví dụ hỗ trợ: generic, sheerid, hoặc instance_id/model (ví dụ my-instance-id/generic) để gửi job vào queue riêng. instance_id không hợp lệ bị từ chối với 400.
user_agent: Chuỗi tùy chọn lưu kèm document cho analytics/hỗ trợ.

Ví dụ response

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

Response chứa image ID duy nhất để theo dõi trạng thái detection.

Query trạng thái và kết quả detection

Để kiểm tra trạng thái và lấy kết quả, dùng endpoint /query với image ID.

Authentication: Body chỉ gồm id; API không gửi API key trong lệnh gọi này. Ai biết UUID đều có thể poll kết quả — coi document ID là nhạy cảm nếu cần hạn chế ai xem điểm số.

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

Ví dụ request

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ụ response

{
    "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,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Ví dụ response (/query, bật secure URLs trên org)

{
    "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-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

Ví dụ response khi kết quả phân tích đã sẵn sàng

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "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/..."
}

Chi tiết các trường kết quả

is_valid: Cho biết file ảnh có hợp lệ hay không (true/false).
detection_step: Giai đoạn detection hoàn tất: 1 = chỉ metadata; 2 = metadata và ocr; 3 = metadata, ocr và ml_model.
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 detection.
metadata: Thông tin trích từ metadata ảnh bằng ExifTool và Pillow.
metadata_basic_source: Có thể cho biết ảnh chụp từ model camera di động cụ thể, tạo bởi công cụ AI, hoặc chỉnh sửa bằng phần mềm.
ocr: Kết quả phát hiện watermark dưới tên trường lịch sử ocr. Mảng hai phần tử [label, score]: label là class watermark (ví dụ "Gemini") hoặc "OCR did not detect AI"; score thang 0–100 (hoặc 0 khi không chắc). Tóm tắt trong warnings khi có label.
ml_model: Kết quả từ machine learning model.
warnings: Mảng tùy chọn các object cảnh báo không đồng nhất (type blur_dark, watermark, screen_recapture, v.v.). Có thể rỗng hoặc bị bỏ qua.
preview_url: URL ảnh preview nếu generate_preview là true. Có thể là storage trực tiếp hoặc, khi bật secure URLs, đường dẫn API như https://<api-host>/preview/<document_id>.
heatmap_status: pending, ready hoặc failed. Tạo heatmap là bất đồng bộ.
heatmap_url: Heatmap khi heatmap_status là ready. Giao diện phụ thuộc generate_heatmap_overlayed. Có thể là storage trực tiếp hoặc đường API https://<api-host>/heatmap/<document_id> (dùng POST /heatmap/{id} với key khi secure).
analysis_results_status: pending, ready, skipped, failed hoặc analyzing. Bỏ qua hoặc null khi generate_analysis_details là false.
analysis_results: Phân tích chi tiết khi bật; xem phần Giải thích Analysis Result bên dưới.

Giải thích Analysis Result

Khi analysis_results sẵn sàng, thường gồm: agreement (strong | moderate | weak | disagreement), imageTags (tối đa năm tag ngắn), confidence (0–100), keyIndicators, detailedReasoning, visualPatterns và recommendations.

Ghi chú

Tạo heatmap là bất đồng bộ. Poll /query để lấy heatmap_status và heatmap_url.
Phân tích chi tiết là bất đồng bộ trừ khi generate_analysis_details=false. Poll analysis_results_status và analysis_results.
Secure URLs: Khi bật, heatmap_url và preview_url có thể dùng API host; tải bằng POST /heatmap/{id} và POST /preview/{id} với key (xem Secure heatmap và preview assets).
Poll /query lại sau khi điểm chính sẵn để nhận heatmap và analysis_results khi xong.

Hành vi heatmap và overlay

File tại heatmap_url phản ánh generate_heatmap_overlayed và generate_heatmap_normalized từ /detect (hoặc /bulk-upload): mặc định overlay (true) là ảnh thường có heatmap phủ; false thường là PNG trong suốt để composite.

Ví dụ: result ~90.24 với final_result AI Generated và detection_step 3 nghĩa là pipeline đầy đủ metadata, OCR và ML model đã hoàn tất.

Analysis Results (phân tích sâu bất đồng bộ)

Khi generate_analysis_details là true trong /detect, phân tích chi tiết có thể hoàn tất sau điểm chính. Poll /query đến khi analysis_results_status là ready (hoặc skipped/failed).

1. Kết quả ban đầu có thể sẵn trước khi analysis xong

Core detection (result, final_result, confidence) có thể xong khi analysis_results_status vẫn pending.

{
    "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

Dùng các trường core ngay; tiếp tục poll nếu cần analysis_results.

2. Tiếp tục poll

Gọi /query với cùng id đến khi analysis_results_status đổi khỏi pending.

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. Analysis hoàn tất

Khi analysis_results_status là ready, analysis_results gồm agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns và recommendations.

{
    "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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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ó analysis

Nếu analysis_results_status là skipped, failed hoặc vắng, hoặc generate_analysis_details là false, coi core detection là kết quả cuối.

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

Các trường Analysis Results

analysis_results_status: pending | ready | skipped | failed | analyzing
analysis_results.agreement: strong | moderate | weak | disagreement
analysis_results.imageTags: tag mô tả ngắn
analysis_results.confidence: 0–100
analysis_results.keyIndicators: dấu hiệu cụ thể
analysis_results.detailedReasoning: giải thích ngắn
analysis_results.visualPatterns: pattern rộng hơn
analysis_results.recommendations: bước tiếp theo

Bulk Upload (ZIP)

Gửi nhiều ảnh trong một request bằng cách upload ZIP. Quy trình giống ảnh đơn: presign (tên ZIP) → PUT ZIP → POST /bulk-upload → poll /query.

1. Lấy Pre-signed Upload URL (ZIP)

Dùng get-presigned-url với tên file .zip (ví dụ images.zip).

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

Ví dụ request

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

2. Upload ZIP

PUT file ZIP lên presigned URL với Content-Type: application/zip.

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

Giới hạn ZIP

Kích thước ZIP tối đa: 100MB
Số ảnh tối đa mỗi bulk: 50
Giới hạn mỗi ảnh: tối thiểu 1KB, tối đa 10MB

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

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

PDF trong ZIP không hỗ trợ và sẽ bị bỏ qua.

SVG được chuyển sang PNG trước khi detection.

3. Gửi ZIP để Bulk Detection

POST /bulk-upload với key và url trỏ tới đường dẫn ZIP đã upload.

Tham số tùy chọn

generate_preview: true để tạo preview URL cho ảnh (mặc định: false).
generate_analysis_details: true để tạo phân tích chi tiết (mặc định: false).
generate_heatmap_overlayed: Cùng hành vi như /detect (overlay so với heatmap RGBA trong suốt).
generate_heatmap_normalized: Cùng hành vi như /detect (mặc định: true).
model: Miền model: generic, sheerid, hoặc định dạng instance_id/model.

Ví dụ request

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -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": false,
  "model": "generic"
}'

Ví dụ response

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

Trả về id, status pending và expected_count (số ảnh trong ZIP sẽ được phân tích).

Cách kết quả bulk ZIP cập nhật

Sau khi gửi, status là pending đến khi bắt đầu xử lý, rồi analyzing.
results liệt kê từng ảnh; mục pending có result và result_details null đến khi xong.
Heatmap và chi tiết phân tích tùy chọn có thể vẫn pending trong result_details đến khi ready.
Khi mọi ảnh trong results xong, status tổng thể là done. Nếu batch không hoàn tất, status có thể failed.
Có thể gọi /query trước khi ZIP xong để xem kết quả một phần.

4. Query kết quả Bulk Upload

Dùng POST /query với id từ /bulk-upload. Cùng endpoint với ảnh đơn; hình dạng response phụ thuộc id là ảnh đơn hay batch ZIP.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

Ví dụ response (đang xử lý)

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

Các trường response (bulk ZIP)

id — ID yêu cầu bulk.
status — pending, rồi analyzing, rồi done hoặc failed.
results — Một mục cho mỗi ảnh đang phân tích (id, status, result, result_details, filename, preview_url khi có).
skipped — File không phân tích (loại không hỗ trợ, kích thước, v.v.) với status failed và lý do trong result_details.

Billing: Credit chỉ dùng cho ảnh phân tích thành công. Chuyển SVG thất bại và file bỏ qua không tính phí.

Secure heatmap và preview assets

Khi heatmap_url hoặc preview_url trong /query trỏ tới API host (không phải object storage trực tiếp), tải bytes bằng POST và key.

POST /heatmap/{id}

POST /preview/{id}

Request body JSON: { "key": "YOUR-API-KEY-GOES-HERE" }

Response heatmap (kiểm tra HTTP status và Content-Type)

200 + binary (image/png, v.v.) — File heatmap có sẵn. Có thể có X-Heatmap-Status.
202 + JSON — heatmap_status pending; poll /query và thử lại.
200 + JSON — Không có heatmap để phục vụ (tính năng tùy chọn, failed, v.v.); không phải lỗi server.
500 + JSON — heatmap_url đã lưu nhưng không tải được file từ storage; thử lại sau.
404 + JSON — Không tìm thấy document id.
403 + JSON — API key không sở hữu document này.

Preview: POST /preview/{id} trả bytes preview thô. 404 với JSON nếu không tạo preview (generate_preview false).

Ví dụ

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png

curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

Internal: đồng bộ usage tổ chức sang Stripe (job secret)

Chỉ cho backend job tin cậy, không phải khách hàng API chung. Yêu cầu header x-job-secret khớp JOB_SECRET trên server. Đồng bộ usage metered của tổ chức TruthScan sang Stripe theo khoảng ngày.

POST /organizations/{org_id}/usage/sync-to-stripe

Headers: x-job-secret: <JOB_SECRET>

Body JSON: start_date, end_date, idempotency_id tùy chọn cho idempotency meter Stripe.

Trả success, organization_id, total_documents, value_sent_to_stripe, report_date, message. 400 nếu org không metered hoặc thiếu stripe_customer_id khi cần; 401 secret không hợp lệ; 404 không thấy org; 500 lỗi Stripe/cấu hình.

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

Endpoint này nhận apikey qua header và trả chi tiết credit.

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

Ví dụ request

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ụ response

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

Với tích hợp bên ngoài, chỉ trường credits được điền.

Health Check

Kiểm tra trạng thái sức khỏe của API server.

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

Ví dụ request

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

Ví dụ response

{
    "status": "healthy"
}

Phản hồi "healthy" cho biết dịch vụ đang 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ỹ 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
400	Bad Request — Yêu cầu không hợp lệ.
401	Unauthorized — Job secret không hợp lệ (endpoint internal usage) hoặc lỗi auth tương tự.
403	Forbidden — API key không hợp lệ, bị từ chối truy cập hoặc không đủ credit.
404	Not Found — Tài nguyên không tồn tại.
405	Method Not Allowed — Truy cập tài nguyên bằng phương thức không hợp lệ.
406	Not Acceptable — Yêu cầu định dạng không phải JSON.
410	Gone — Tài nguyên tại endpoint này đã bị gỡ.
422	Invalid Request Body — Body không đúng định dạng, không hợp lệ hoặc thiếu tham số.
429	Too Many Requests — Gửi quá nhiều yêu cầu, vui lòng chậm lại.
500	Internal Server Error — Lỗi máy chủ, vui lòng thử lại sau.
503	Service Unavailable — Tạm ngắt để bảo trì, vui lòng 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ý:

Xác minh API key đúng
Kiểm tra API key còn hoạt động trong tài khoản
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ý:

Kiểm tra credit còn lại bằng /check-user-credits
Mua thêm credit nếu cần

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

"Input URL cannot be empty" (400)

Nguyên nhân: URL rỗng hoặc không hợp lệ

Cách xử lý:

Đảm bảo url không rỗng
Xóa khoảng trắng đầu/cuối tên ảnh
Kiểm tra URL encoding đúng

"Input email is empty" (400)

Nguyên nhân: Thiếu email khi xử lý URL

Cách xử lý:

Cung cấp email hợp lệ khi gửi URL
Kiểm tra định dạng email

"Unsupported image type" (400)

Nguyên nhân: Định dạng file không được hỗ trợ

Cách xử lý:

Chuyển sang định dạng được hỗ trợ (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
Kiểm tra phần mở rộng file đúng

"File size is too small" (400)

Nguyên nhân: File ảnh nhỏ hơn mức tối thiểu

Cách xử lý:

Dùng ảnh lớn hơn (tối thiểu 1KB)
Kiểm tra ảnh không bị hỏng khi upload

"File size exceeds limit" (400)

Nguyên nhân: File ảnh quá lớn

Cách xử lý:

Nén hoặc thu nhỏ ảnh; giới hạn tối đa theo từng deployment (thông báo lỗi API ghi rõ giới hạn MB)
Thử định dạng ảnh khác

"Invalid file type" (400)

Nguyên nhân: Xác thực loại file thất bại

Cách xử lý:

Đảm bảo file là định dạng ảnh hợp lệ
Kiểm tra file không bị hỏng
Kiểm tra MIME type khớp phần mở rộng

Vấn đề xử lý

Trạng thái ảnh "failed"

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

Cách xử lý:

Xác minh URL đúng định dạng được hỗ trợ
Kiểm tra file ảnh hợp lệ và không hỏng
Đảm bảo ảnh đạt yêu cầu kích thước
Liên hệ hỗ trợ nếu vẫn lỗi

"User not found"

Nguyên nhân: User ID không hợp lệ

Cách xử lý:

Xác minh user ID đúng
Đảm bảo tài khoản còn hoạt động
Xác thực lại nếu cần

"File metadata could not be fetched" (500)

Nguyên nhân: Không truy cập được file đã upload

Cách xử lý:

Xác minh file đã upload thành công
Kiểm tra URL file có thể truy cập
Thử upload lại file

Vấn đề upload

"Image upload failed" (403/400)

Nguyên nhân: Pre-signed URL không hợp lệ hoặc hết hạn, hoặc lỗi storage server

Cách xử lý:

Dùng pre-signed URL ngay sau khi nhận
Xác minh Content-Type khớp định dạng file
Xóa khoảng trắng trong tên file trước khi upload
Tạo pre-signed URL mới nếu cần

"Invalid pre-signed URL" (400)

Nguyên nhân: Tên file có khoảng trắng hoặc pre-signed URL hết hạn/hỏng

Cách xử lý:

Xóa khoảng trắng trong tên file trước khi yêu cầu pre-signed URL
Chỉ dùng chữ, số, gạch ngang và gạch dưới
Tạo pre-signed URL mới nếu cần

Vấn đề Bulk Upload

"URL must point to a ZIP file" (400)

Nguyên nhân: URL gửi tới /bulk-upload không trỏ tới file ZIP

Cách xử lý:

Dùng get-presigned-url?file_name=images.zip (hoặc tên .zip khác)
Upload ZIP hợp lệ lên presigned URL
Đảm bảo url trong bulk-upload trỏ đúng ZIP đã upload

"ZIP file too large" (400)

Nguyên nhân: ZIP vượt kích thước tối đa (100MB)

Cách xử lý:

Giảm số ảnh hoặc nén thêm
Chia thành nhiều lần bulk upload

"Too many files" (400)

Nguyên nhân: ZIP chứa hơn 50 ảnh hợp lệ

Cách xử lý:

Giảm xuống tối đa 50 ảnh mỗi ZIP
Chia thành nhiều lần bulk upload

"No valid images found in ZIP" (400)

Nguyên nhân: Mọi file trong ZIP đều bị bỏ qua (định dạng không hỗ trợ, quá nhỏ, đường dẫn không hợp lệ, v.v.)

Cách xử lý:

Dùng định dạng được hỗ trợ (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
PDF không hỗ trợ trong bulk
Mỗi ảnh tối thiểu 1KB và tối đa 10MB
Tránh file ẩn (tên bắt đầu bằng .) và path traversal (..)

"Document is not a bulk upload (image-zip) result" (400)

Nguyên nhân: id không khớp loại upload (ảnh đơn so với batch ZIP)

Cách xử lý:

Dùng id từ /detect cho gửi ảnh đơn
Dùng id từ /bulk-upload cho gửi ZIP

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.

Liên hệ

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.