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

API phát hiện văn bản AI

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

TruthScan yêu cầu API key trong body mọi yêu cầu API tới máy chủ, 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.

Với WebSocket, bạn cần gửi Organization ID trong URL. Lấy Organization ID tại đầu trang trong cổng nhà phát triển.

TruthScan yêu cầu Organization ID trong URL mọi yêu cầu WebSocket. Tài liệu có dạng sau:

wss://detect-text.truthscan.com/ws/$ORG_ID

Thay $ORG_ID bằng Organization ID cá nhân của bạn.

Trình phát hiện AI

Detect

Endpoint này cho phép gửi văn bản để phát hiện AI. Khuyến nghị ít nhất 200 từ để độ chính xác tốt nhất.

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

Ngưỡng

Endpoint trả về điểm "result" từ 1–100. Dưới 50 được coi là chắc chắn do người viết; 50–60 có thể là AI; trên 60 là AI rõ ràng. Đây là kết quả chính xác nhất, trên 99%.

Điểm từ detector khác như Writer và Copyleaks là gần đúng và không chính xác bằng điểm "result" chính.

Xuống dòng

Nếu gửi JSON, xuống dòng cần mã hóa dạng \n trong chuỗi.

Ví dụ yêu cầu

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0
}'

Đầu vào phải nhỏ hơn 30.000 từ.

Ví dụ phản hồi

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Phản hồi chứa ID tài liệu do máy chủ gán. Tài liệu được đưa vào hàng đợi xử lý. Dùng /query để kiểm tra trạng thái. Trung bình hoàn tất trong 2–4 giây; có thể lâu hơn tùy số từ.

Query

Endpoint nhận document id từ /detect và trả về trạng thái cùng kết quả phát hiện AI do các detector bên thứ ba xử lý.

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

Ví dụ yêu cầu

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

Ví dụ phản hồi

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0
    },
    "status": "done",
    "retry_count": 0
}

Ở đây "result": 12.0 thể hiện mức "human-ness". Dưới ngưỡng 50% thì văn bản chắc chắn do người. Các giá trị trong result_details cũng phản ánh mức tương tự. Ví dụ "scoreZeroGPT": 50.0 nghĩa là khoảng 50% human theo ZeroGPT.

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

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

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

Ví dụ yêu cầu

curl -X 'GET' \
  'https://detect-text.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
}

Phát hiện AI theo câu

Trình phát hiện theo câu chạy trên giao thức WebSocket.

Các bước cần thiết để có kết quả theo câu:

  • Kết nối WebSocket
  • Lắng nghe mọi sự kiện từ WebSocket
  • Gửi yêu cầu document_watch
  • Nhận sự kiện document_id
  • Dùng id từ document_id và gửi tài liệu phát hiện AI
  • Bắt đầu nhận document_chunk — mỗi sự kiện trả về một câu cùng kết quả theo câu
  • Khi xử lý xong, nhận document_done

Kết nối WebSocket

Endpoint này cho phép thiết lập kết nối WebSocket

wss://detect-text.truthscan.com/ws/$ORG_ID

Ví dụ mã

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

Lắng nghe sự kiện từ WebSocket

Sau khi kết nối, lắng nghe sự kiện gửi qua WebSocket.

Ví dụ mã

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Gửi yêu cầu document_watch

Báo ý định gửi tài liệu bằng document_watch trên WebSocket

Ví dụ mã

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Nhận sự kiện document_id

Sau document_watch, máy chủ trả về document_id.

Ví dụ phản hồi

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Gửi yêu cầu phát hiện AI

Dùng id từ document_id và gửi tài liệu phát hiện AI

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

Ví dụ yêu cầu

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Nhận kết quả theo câu

Nhận document_chunk — mỗi sự kiện trả về một câu và kết quả theo câu

Ví dụ phản hồi

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Khi xử lý xong, nhận document_done.

Ví dụ phản hồi

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

Xử lý trường hợp ngoại lệ

Nếu máy chủ lỗi khi phát hiện AI, document_error được gửi tới client. Client nên xử lý phù hợp (ví dụ hiển thị lỗi trên UI).

Ví dụ: máy chủ gửi REQUEST_TIMEOUT nếu quá 20 giây giữa các sự kiện chunk.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

Hủy

Đôi khi UI cần hủy: người dùng đóng cửa sổ hoặc hủy rõ ràng

Khi đó nên gửi sự kiện document_halt

Ví dụ phản hồi

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

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
400Bad Request — Yêu cầu không hợp lệ.
403Forbidden — API key không hợp lệ hoặc không đủ credit (0,1 mỗi từ).
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, không hợp lệ 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ý văn bản

Cách xử lý:

  1. Kiểm tra credit còn lại bằng /check-user-credits
  2. Mua thêm credit nếu cần
  3. Dùng văn bản ngắn hơn để tiêu ít credit hơn

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

"Input text cannot be empty" (400)

Nguyên nhân: Gửi văn bản rỗng hoặc chỉ khoảng trắng

Cách xử lý:

  1. Đảm bảo đầu vào không rỗng
  2. Xóa khoảng trắng đầu/cuối
  3. Kiểm tra mã hóa văn bản đúng

"Input email is empty" (400)

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

Cách xử lý:

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

Vấn đề xử lý

"Request timeout" (WebSocket)

Nguyên nhân: Xử lý tài liệu quá lâu (>120 giây)

Cách xử lý:

  1. Thử với văn bản ngắn hơn
  2. Kiểm tra dịch vụ 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 văn bản đáp ứng yêu cầu tối thiểu
  2. Xác minh định dạng được hỗ trợ
  3. Thử mô hình khác
  4. Liên hệ hỗ trợ nếu vẫn lỗi

Vấn đề kết nối WebSocket

Mất kết nối

Nguyên nhân: Sự cố mạng hoặc máy chủ ngắt

Cách xử lý:

  1. Kiểm tra kết nối mạng
  2. Triển khai logic kết nối lại
  3. Xác minh URL WebSocket đúng

"User not found" (WebSocket)

Nguyên nhân: Organization ID không hợp lệ trong WebSocket

Cách xử lý:

  1. Xác minh Organization ID đúng
  2. Đảm bảo tài khoản hoạt động
  3. Xác thực lại nếu cần

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 AI.