API 文档

AI 文本检测 API

用于将 TruthScan AI 检测 API 集成到您的应用中的完整文档

无需编写代码即可体验，请访问我们的 FastAPI 接口： https://detect-text.truthscan.com/docs

认证

TruthScan 使用 API 密钥进行认证，您可以在开发者门户页面顶部.

所有 API 请求必须在请求体中包含 API 密钥

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

请将 YOUR API KEY GOES HERE 替换为您的 API 密钥

对于 WebSocket 场景，需在 URL 中包含 Organization ID，您可以在开发者门户页面顶部.

所有 WebSocket 请求必须在 URL 中包含 Organization ID

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

请将 $ORG_ID 替换为您的 Organization ID

AI 检测

检测

该接口用于提交文本进行 AI 检测，建议至少 200 字以获得最佳准确率

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

阈值说明

result 范围为 1-100：<50 为人工，50-60 为可能 AI，>60 为 AI（准确率 99%+）

其他检测器（如 Writer、Copyleaks）的分数为参考值

换行处理

JSON 中换行需使用 \n

示例请求

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
}'

输入限制为 30,000 字

示例响应

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

返回文档 ID，可通过 /query 查询状态，平均处理时间 2-4 秒

查询

通过 /query 使用 document_id 查询检测结果

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

示例请求

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

示例响应

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

result 越低表示越接近人工文本

查询积分

通过 API Key 查询账户积分

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

示例请求

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'

示例响应

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

句子级 AI 检测

句子级检测基于 WebSocket 实现

流程：

连接 WebSocket
监听事件
发送 document_watch
获取 document_id
提交检测
接收 sentence 结果
接收完成事件

连接 WebSocket

建立 WebSocket 连接

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

示例代码

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

监听事件

监听 WebSocket 返回事件

示例代码

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

发送 document_watch

声明检测请求

示例代码

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

获取 document_id

服务端返回 ID

示例响应

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

提交检测

使用 document_id 提交文本

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

示例请求

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

接收句子结果

返回每句 AI 判断

示例响应

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

完成后返回 document_done

示例响应

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

异常处理

错误时返回 document_error

超时将返回 REQUEST_TIMEOUT

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

取消操作

用户可中断检测

发送 document_halt

示例响应

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

错误说明

大多数错误来自参数问题

遵循 REST 标准

错误码	说明
400	请求错误
403	权限不足或积分不足
404	资源不存在
405	方法错误
406	格式错误
410	资源已删除
422	请求体错误
429	请求过多
500	服务器错误
503	服务不可用

常见问题与解决方案

认证相关问题

"User verification failed" (403)

原因: API 密钥无效或已过期

解决方案:

确认 API 密钥正确
在账户中检查密钥是否有效
必要时重新生成 API 密钥

"Not enough credits" (403)

原因: 文本处理积分不足

解决方案:

使用 /check-user-credits 查询剩余积分
按需购买额外积分
缩短输入文本以减少消耗

输入校验问题

"Input text cannot be empty" (400)

原因: 提交了空文本或仅空白字符

解决方案:

确保文本非空
去除首尾空白
检查文本编码是否正确

"Input email is empty" (400)

原因: 处理 URL 时缺少邮箱

解决方案:

提交 URL 时提供有效邮箱
检查邮箱格式是否正确

处理问题

"Request timeout" (WebSocket)

原因: 文档处理超时（超过 120 秒）

解决方案:

尝试更短的文本输入
检查服务是否负载较高
重试请求

文档状态为 "failed"

原因: 因多种原因处理失败

解决方案:

检查输入是否满足最低要求
确认文本格式受支持
尝试更换模型
若仍失败请联系支持

WebSocket 连接问题

连接中断

原因: 网络问题或服务器断开

解决方案:

检查网络连接
实现自动重连逻辑
确认 WebSocket URL 正确

"User not found" (WebSocket)

原因: WebSocket URL 中的组织 ID 无效

解决方案:

确认组织 ID 正确
确认账户处于有效状态
必要时重新认证

需要帮助？

如需技术支持，请联系我们

联系我们

API 常见问题

关于 AI 文本检测 API 的常见问题