API 文档

AI 图像检测 API

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

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

认证

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

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

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

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

AI 图像检测

检测流程（3 步）

流程包括：

获取上传 URL
上传图像
提交检测

1. 获取预签名上传 URL

通过 API 请求预签名 URL，用于安全上传图像。

支持格式

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF

重要提示

文件名不能包含空格。

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

示例请求

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

示例响应

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. 上传图像

使用 presigned_url 通过 PUT 请求上传图像，并确保 Content-Type 正确。

重要提示

上传时文件名不能包含空格。

示例请求

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

文件大小限制

最小 1KB
最大 10MB

上传过程中必须保持文件格式一致，成功上传将返回状态码 200。

3. 提交检测

上传完成后，使用 file_path 提交图像进行 AI 检测。

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

示例请求

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

FILE_PATH 来自第一步返回的路径。

可选参数

generate_preview: 生成预览 URL（默认 false）
document_type: 文档类型（默认 Image）
email: 处理通知邮箱
generate_analysis_details: 开启深度 AI 分析（generate_analysis_details = true）

示例响应

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

返回唯一图像 ID，用于查询检测状态。

查询结果

通过 /query 接口使用图像 ID 查询检测状态与完整结果（包含 metadata、OCR 和 ML 分析）。

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

示例请求

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

示例响应

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

结果说明

result: 1-100 的评分，数值越高表示 AI 生成概率越高
final_result: 最终判断（AI 生成 / 真实 / 编辑）
confidence: 置信度评分
detection_step: 检测阶段（metadata / OCR / ML）
metadata: 图像元数据分析结果
ocr: OCR 水印检测结果
ml_model: 机器学习模型分析结果
preview_url: 预览图 URL（若开启 generate_preview）
heatmap_status: 热力图状态（pending / ready）
heatmap_url: 热力图 URL（score ≥ 20 时可用）
analysis_results_status: 深度分析状态（pending / done / skipped）
analysis_results: 深度分析结果（包含指标、解释与建议）

重要提示

热力图为异步生成，仅在 score ≥ 20 时提供。

result 越高表示 AI 生成概率越高，final_result 提供最终判断，confidence 表示置信度。

深度分析（异步）

开启 generate_analysis_details 后，将在后台执行深度分析。

初始结果

检测完成但深度分析仍在进行中。

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

持续查询

轮询 /query 直到 analysis_results_status = done。

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

分析完成

返回完整深度分析结果。

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

未提供分析

未开启或不支持深度分析。

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

分析字段

analysis_results_status: 状态（pending / done / skipped）
analysis_results.agreement: 一致性（strong / moderate / weak）
analysis_results.confidence: 置信度（0-100）
analysis_results.keyIndicators: 关键视觉异常
analysis_results.detailedReasoning: 详细解释
analysis_results.visualPatterns: 视觉模式
analysis_results.recommendations: 建议操作

查询积分

通过 API Key 查询账户积分。

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

示例请求

curl -X 'GET' \
  'https://detect-image.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 图像检测服务状态。

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

示例请求

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

示例响应

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

返回 healthy 表示服务正常。

错误说明

大多数错误来自参数问题。

错误码遵循 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 查询剩余积分
按需购买额外积分
上传前适当压缩图像以减少消耗

输入校验问题

"Unsupported file format" (400)

原因: 提交了不支持或无效的图像格式

解决方案:

确认格式受支持（JPG、JPEG、PNG、WebP、JFIF、HEIC、HEIF、AVIF、BMP、TIFF、TIF）
确认文件未损坏
上传时检查 Content-Type 是否正确

"File too large" (400)

原因: 文件超过 10MB 限制

解决方案:

将图像压缩或缩放至 10MB 以下
上传前检查文件大小
可尝试使用 WebP 等更高效格式

处理问题

"Request timeout" (WebSocket)

原因: 图像处理耗时过长

解决方案:

尝试更小或更简单的图像
检查服务是否负载较高
稍后重试请求

文档状态为 "failed"

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

解决方案:

确认图像满足大小要求（1KB–10MB）
确认格式受支持
确认上传完成后再提交检测
若仍失败请联系支持

上传问题

"Image upload failed" (403/400)

原因: 预签名 URL 无效或过期，或存储服务异常

解决方案:

获取预签名 URL 后尽快使用（可能过期）
确认 Content-Type 与图像格式一致
上传前移除文件名中的空格
必要时重新获取预签名 URL

"Invalid pre-signed URL" (400)

原因: 文件名含空格，或预签名 URL 过期/损坏

解决方案:

请求预签名 URL 前移除文件名中所有空格
文件名仅使用字母数字、连字符和下划线
必要时重新生成预签名 URL

需要帮助？

如需支持，请联系我们。

联系我们

API 常见问题

关于 AI 图像检测 API 的常见问题。