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

输入限制为 30,000 字

可选参数

model: 要使用的AI检测模型（默认：'xlm_ud_detector'）
retry_count: 处理失败时的重试次数（默认：0）
generate_analysis_details: 设置为'true'以启用深度AI分析结果（默认：'false'）。启用后，查询响应将包含analysis_results_status和analysis_results字段。

示例响应

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

结果解读

result: 0-100的分数，表示文本由AI生成的可能性。低于50 = 肯定是人类写的。50-60 = 可能是AI。高于60 = 肯定是AI。
label: 总体判定：'Human'、'AI'或'Paraphrase'
result_details scores: 第三方检测器的近似分数：GPTZero、OpenAI、Writer、CrossPlag、CopyLeaks、Sapling、ContentAtScale、ZeroGPT（每个为0、50或100）
human: 所有第三方检测器分数的平均值，表示文本看起来有多像人类写的
result_categories.advanced: 具有分层评分的高级结果类别（1-99格式）
result_categories.standard: 标准结果类别
analysis_results_status: 深度AI分析状态（'pending'、'ready'、'skipped'或null）。当为'pending'时，继续轮询/query端点——分析仍在后台处理中。当为'ready'时，analysis_results字段包含已完成的分析。当为'skipped'、null或缺失时，此文本的深度分析不可用。
analysis_results: 深度AI分析结果（当analysis_results_status为'ready'时可用）。包含：agreement（strong/moderate/weak/disagreement）、confidence（0-100）、keyIndicators（找到的文本指标数组）、detailedReasoning（解释）、linguisticPatterns（观察到的语言模式数组）和recommendations（可操作的建议）。

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
}

分析结果（异步深度分析）

当您在/detect请求中将'generate_analysis_details'设置为'true'时，TruthScan会在初始检测完成后在后台运行深度AI分析。初始查询响应将以状态'done'返回，您的检测结果可以立即使用，但analysis_results_status字段可能仍为'pending'。您可以立即使用初始结果，并可选地轮询等待深度分析完成。

1. 初始结果已确定（分析仍在等待中）

当您使用'generate_analysis_details': true提交并首次以状态'done'查询时，核心检测结果（result、label、result_details）已准备就绪。但是，analysis_results_status可能为'pending'——这意味着深度AI分析仍在后台处理中。

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

该怎么做

您可以立即使用初始检测结果（result、label、result_details分数）。如果您还需要深度分析，请继续使用相同的文档ID轮询/query端点，直到analysis_results_status从'pending'变更。

2. 继续轮询分析结果

继续使用相同的文档ID调用/query端点。在每次响应中检查analysis_results_status字段。当它从'pending'变为'ready'时，analysis_results对象将被填充。

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. 分析完成——完整响应

当analysis_results_status为'ready'时，analysis_results对象包含完整的深度AI分析，包括一致性级别、置信度、关键指标、详细推理、语言模式和建议。

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

当分析不可用时

如果analysis_results_status为'skipped'、null或缺失，则不会为此文本生成深度分析。这发生在/detect请求中未将'generate_analysis_details'设置为'true'时，或在某些处理场景中。您应将初始检测结果视为最终结果。

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

分析结果字段

analysis_results_status: 'pending' = 仍在处理中，'ready' = 结果可用，'skipped' / null / 缺失 = 此文本不可用
analysis_results.agreement: 深度分析与初始检测的一致程度（strong / moderate / weak / disagreement）
analysis_results.confidence: 深度分析的置信度分数（0-100）
analysis_results.keyIndicators: 在文本中找到的特定文本指标的数组
analysis_results.detailedReasoning: 2-4句解释为什么文本被如此分类
analysis_results.linguisticPatterns: 观察到的语言模式数组（例如，句子结构一致性、词汇模式）
analysis_results.recommendations: 理解文本真实性的可操作建议数组

句子级 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 的常见问题