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

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

Tham Số Tùy Chọn

  • model: Mô hình phát hiện AI sử dụng (mặc định: 'xlm_ud_detector')
  • retry_count: Số lần thử lại nếu xử lý thất bại (mặc định: 0)
  • generate_analysis_details: Đặt thành 'true' để kích hoạt kết quả phân tích AI chuyên sâu (mặc định: 'false'). Khi được kích hoạt, phản hồi truy vấn sẽ bao gồm các trường analysis_results_status và analysis_results.

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,
    "label": "Human",
    "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,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

Diễn Giải Kết Quả

  • result: Điểm từ 0-100 cho biết khả năng văn bản được tạo bởi AI. Dưới 50 = chắc chắn do con người viết. 50-60 = có thể là AI. Trên 60 = chắc chắn là AI.
  • label: Kết luận tổng thể: 'Human', 'AI' hoặc 'Paraphrase'
  • result_details scores: Điểm ước tính từ các công cụ phát hiện bên thứ ba: GPTZero, OpenAI, Writer, CrossPlag, CopyLeaks, Sapling, ContentAtScale, ZeroGPT (mỗi cái 0, 50 hoặc 100)
  • human: Trung bình của tất cả điểm từ các công cụ phát hiện bên thứ ba cho biết văn bản trông giống con người đến mức nào
  • result_categories.advanced: Danh mục kết quả nâng cao với tính điểm theo bậc (định dạng 1-99)
  • result_categories.standard: Danh mục kết quả tiêu chuẩn
  • analysis_results_status: Trạng thái phân tích AI chuyên sâu ('pending', 'ready', 'skipped' hoặc null). Khi 'pending', tiếp tục truy vấn endpoint /query — phân tích vẫn đang được xử lý trong nền. Khi 'ready', trường analysis_results chứa phân tích đã hoàn thành. Khi 'skipped', null hoặc vắng mặt, phân tích chuyên sâu không khả dụng cho văn bản này.
  • analysis_results: Kết quả phân tích AI chuyên sâu (khả dụng khi analysis_results_status là 'ready'). Bao gồm: agreement (strong/moderate/weak/disagreement), confidence (0-100), keyIndicators (mảng các chỉ báo văn bản tìm thấy), detailedReasoning (giải thích), linguisticPatterns (mảng các mẫu ngôn ngữ quan sát được) và recommendations (các mục có thể thực hiện).

Ở đâ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
}

Kết Quả Phân Tích (Phân Tích Chuyên Sâu Bất Đồng Bộ)

Khi bạn đặt 'generate_analysis_details' thành 'true' trong yêu cầu /detect, TruthScan sẽ chạy phân tích AI chuyên sâu trong nền sau khi phát hiện ban đầu hoàn tất. Phản hồi truy vấn ban đầu sẽ trả về với trạng thái 'done' và kết quả phát hiện sẵn sàng sử dụng, nhưng trường analysis_results_status có thể vẫn là 'pending'. Bạn có thể sử dụng kết quả ban đầu ngay lập tức và tùy chọn truy vấn để chờ phân tích chuyên sâu hoàn thành.

1. Kết Quả Ban Đầu Đã Xác Định (Phân Tích Vẫn Đang Chờ)

Khi bạn gửi với 'generate_analysis_details': true và truy vấn lần đầu với trạng thái 'done', kết quả phát hiện chính (result, label, result_details) đã sẵn sàng. Tuy nhiên, analysis_results_status có thể là 'pending' — điều này có nghĩa là phân tích AI chuyên sâu vẫn đang được xử lý trong nền.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

Cần làm gì

Bạn có thể sử dụng kết quả phát hiện ban đầu (result, label, điểm result_details) ngay lập tức. Nếu bạn cũng cần phân tích chuyên sâu, tiếp tục truy vấn endpoint /query với cùng ID tài liệu cho đến khi analysis_results_status thay đổi từ 'pending'.

2. Tiếp Tục Truy Vấn Kết Quả Phân Tích

Tiếp tục gọi endpoint /query với cùng ID tài liệu. Kiểm tra trường analysis_results_status ở mỗi phản hồi. Khi nó thay đổi từ 'pending' sang 'ready', đối tượng analysis_results sẽ được điền dữ liệu.

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

3. Phân Tích Hoàn Thành — Phản Hồi Đầy Đủ

Khi analysis_results_status là 'ready', đối tượng analysis_results chứa phân tích AI chuyên sâu đầy đủ với mức độ đồng thuận, độ tin cậy, các chỉ báo chính, lý luận chi tiết, mẫu ngôn ngữ và khuyến nghị.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

Khi Phân Tích Không Khả Dụng

Nếu analysis_results_status là 'skipped', null hoặc vắng mặt, phân tích chuyên sâu sẽ không được tạo cho văn bản này. Điều này xảy ra khi 'generate_analysis_details' không được đặt thành 'true' trong yêu cầu /detect, hoặc trong một số tình huống xử lý nhất định. Bạn nên xem kết quả phát hiện ban đầu là cuối cùng.

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Các Trường Kết Quả Phân Tích

  • analysis_results_status: 'pending' = đang xử lý, 'ready' = kết quả khả dụng, 'skipped' / null / vắng mặt = không khả dụng cho văn bản này
  • analysis_results.agreement: Mức độ đồng thuận giữa phân tích chuyên sâu và phát hiện ban đầu (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Điểm tin cậy của phân tích chuyên sâu (0-100)
  • analysis_results.keyIndicators: Mảng các chỉ báo văn bản cụ thể tìm thấy trong văn bản
  • analysis_results.detailedReasoning: Giải thích 2-4 câu về lý do văn bản được phân loại như vậy
  • analysis_results.linguisticPatterns: Mảng các mẫu ngôn ngữ quan sát được (ví dụ: tính nhất quán trong cấu trúc câu, mẫu từ vựng)
  • analysis_results.recommendations: Mảng các khuyến nghị có thể thực hiện để hiểu tính xác thực của văn bản

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.