Tài liệu API

API phát hiện video AI

Tài liệu đầy đủ để tích hợp API phát hiện video 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-video.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 của chúng tôi.

TruthScan yêu cầu API key trong mọi yêu cầu API tới máy chủ, trong body có dạng sau:

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

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

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

Gửi video phát hiện (multipart upload)
Truy vấn job để lấy kết quả

1. Gửi video phát hiện

Tải tệp video trực tiếp lên API. Máy chủ sẽ xác thực tệp.

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

MP4, MOV, AVI, MKV, WEBM

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

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

POST https://detect-video.truthscan.com/detect-file

Ví dụ yêu cầu

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Tham số tùy chọn

document_type: Loại tài liệu (mặc định: 'Video')
email: Email tùy chọn cho xử lý

Ví dụ phản hồi

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

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

2. Truy vấn trạng thái và kết quả phát hiện

Sau khi gửi, gọi /query với ID job để lấy trạng thái và kết quả.

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

Ví dụ yêu cầu

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

Ví dụ phản hồi

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Chi tiết kết quả

status: "pending", "analyzing", "done", hoặc "failed"
result: Điểm vô hướng trong [0.0, 1.0] từ prob_fake của ML
final_stage: Giai đoạn cuối đóng góp kết quả: 'metadata', 'watermark', hoặc 'ml'
metadata: Luôn đặt prediction: 'no_detection' và confidence: 0.0. Status có thể 'reject', 'reencode', hoặc 'ok'
watermark: Heuristic lấy mẫu khung hình và tính pseudo-confidence từ phương sai pixel
ml: Mô hình phân loại trên khung hình mẫu. Trả về prob_fake trong [0.0, 1.0] và nhãn ('ai_generated' nếu prob_fake ≥ 0.5, ngược lại 'no_detection')
latency_sec: Tổng thời gian pipeline

Trường "status" là một trong: "pending" (hàng đợi), "analyzing" (đang phát hiện AI), "done" (có kết quả), "failed" (xử lý thất bại).

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

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

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

Ví dụ yêu cầu

curl -X 'GET' \
  'https://detect-video.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 máy chủ API.

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

Ví dụ yêu cầu

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

Ví dụ phản hồi

{
    "status": "healthy"
}

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, định dạng đúng và thử chạy 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ệ.
403	Forbidden — API key không hợp lệ hoặc không đủ credit xử lý video.
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 — Định dạng yêu cầu 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ủ, thử lại sau.
503	Service 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ý:

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ý video

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

"Unsupported video type" (400)

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

Cách xử lý:

Chuyển sang định dạng được hỗ trợ (MP4, MOV, AVI, MKV, WEBM)
Đảm bảo phần mở rộng và MIME type khớp

"File size exceeds limit" (400)

Nguyên nhân: Tệp video quá lớn

Cách xử lý:

Nén, cắt hoặc mã hóa lại để giảm dung lượng (tối đa 100MB)
Dùng codec/container hiệu quả hơn

"File size is too small" (400)

Nguyên nhân: Dưới kích thước tối thiểu

Cách xử lý:

Dùng tệp lớn hơn (tối thiểu 1KB)
Kiểm tra tệp có bị hỏng khi tải lên

"Invalid file type" (400)

Nguyên nhân: Xác thực loại tệp thất bại (ví dụ MIME sai hoặc tệp hỏng)

Cách xử lý:

Đảm bảo là tệp video hợp lệ
MIME khớp phần mở rộng
Xuất lại hoặc mã hóa lại tệp nếu cần

Vấn đề xử lý

Trạng thái video "failed"

Nguyên nhân: Xử lý thất bại (ví dụ container không đọc được, lỗi giải mã)

Cách xử lý:

Dùng container/codec phổ biến (khuyến nghị H.264/AAC trong MP4)
Mã hóa lại bằng preset chuẩn (ví dụ ffmpeg) và tải lại
Đảm bảo đúng định dạng và kích thước

Trạng thái "timeout" hoặc xử lý lâu

Nguyên nhân: Xử lý lâu hơn dự kiến hoặc hết thời gian

Cách xử lý:

Đợi thêm và kiểm tra lại bằng /query
Đảm bảo tệp đúng định dạng và kích thước
Liên hệ hỗ trợ nếu vẫn lỗi

"User not found"

Nguyên nhân: ID người dùng không hợp lệ

Cách xử lý:

Xác minh API key đúng và gắn tài khoản hoạt động
Đảm bảo tài khoản tích hợp hợp lệ
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 hoặc phân tích được tệp đã tải

Cách xử lý:

Xác minh tải lên hoàn tất
Kiểm tra tệp truy cập được và không hỏng
Thử tải lại

Cần trợ giúp?

Để 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 câu hỏi phổ biến về API phát hiện video AI.