API 文档

AI 图像检测 API

将 TruthScan 的 AI 图像检测 API 集成到应用中的完整说明。

无需编写代码即可试用，请访问我们的 FastAPI 端点： https://detect-image.truthscan.com/docs

认证

TruthScan 使用 API 密钥访问 API。请在开发者门户页面顶部获取您的 API 密钥.

除文档说明仅使用 Header 认证的端点（例如 check-user-credits）外，API 密钥应以如下 JSON 形式包含在请求体中：

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

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

AI 图像检测器

检测（三步流程）

AI 图像检测工作流包含以下步骤：

获取预签名上传 URL
上传图像
提交图像进行检测

1. 获取预签名上传 URL

首先向 API 请求预签名 URL。该 URL 用于将图像文件安全上传到存储服务器。

支持的文件格式

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

文件名

请求预签名 URL 时，请从图像文件名中移除空格。

对于 PDF，仅检测第一页中的图像（单文件流程）。

若要通过批量上传提交 ZIP，请在本端点使用 .zip 文件名。

Query 参数

file_name（必填）— 原始文件名；服务器可能会规范化（空格与不安全字符会被调整）。批量上传请使用 .zip 扩展名。
expiration（可选）— 预签名 URL 有效期，单位秒（默认：3600）。

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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id 为本上传请求新生成的 UUID（用于关联/日志）。用于 /detect 或 /bulk-upload 的 id 在提交这些端点时分配，除非您在 /detect 上传入可选的 id。

2. 上传图像

使用返回的 presigned_url 通过 PUT 上传图像。请按图像格式设置正确的 Content-Type。

文件名

上传图像时，请从文件名中移除空格。

将 Content-Type 与文件扩展名严格对应

image/jpeg: jpg, jpeg, jfif
image/png: png
image/webp: webp
image/heic: heic
image/heif: heif
image/avif: avif
image/bmp: bmp
image/tiff: tiff, tif
image/gif: gif
image/svg+xml: svg
application/pdf: pdf

常见错误（请避免）

不要使用 image/jpg（错误）。应使用 image/jpeg。
不要使文件与头信息不一致（例如 .png 文件却使用 image/jpeg）。
不要只改扩展名而不更新 Content-Type（反之亦然）。
请求/上传时不要在文件名中包含空格。

请求示例

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

更多上传示例（PNG、PDF、SVG）

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

文件大小限制

最小文件大小：1KB
最大文件大小：10MB

上传过程中请保持文件格式一致。上传成功返回 HTTP 200。

3. 提交图像进行 AI 检测

上传完成后，引用上一步返回的 file_path 提交检测。若上传为 PDF，仅分析/检测第一页图像。

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

FILE_PATH 指预签名步骤返回的路径（例如 uploads/...）。请按示例使用存储主机拼接完整 URL。

可选参数

id: 可选 UUID 字符串。省略时由服务器生成新的 document id。若提供则不得已存在，否则 API 返回错误。
generate_preview: 设为 true 可生成图像预览 URL（默认：true）。设为 false 可跳过预览生成。
document_type: 文档类型（默认：Image）。
email: 处理时使用的电子邮箱。
generate_analysis_details: 设为 false 可跳过生成详细分析（默认：true）。
generate_heatmap_overlayed: 控制生成热力图时的输出方式（默认：true）。为 true 时热力图与原图混合（标准叠加）。为 false 时返回透明热力图：RGBA 图像，含 JET 着色激活图与模型 alpha，背景透明以便在界面中合成。
generate_heatmap_normalized: 为 false 时跳过激活图所用的归一化步骤（默认：true）。可与 generate_heatmap_overlayed 联用以控制热力图外观。
model: 模型或路由提示（默认：generic）。支持例如 generic、sheerid，或 instance_id/model（如 my-instance-id/generic）以将任务发往该实例的专用队列。无效的 instance_id 将返回 400。
user_agent: 可选字符串，随文档保存，用于分析/支持。

响应示例

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

响应包含用于跟踪检测状态的唯一图像 ID。

查询检测状态与结果

使用图像 ID 调用 /query 端点以查看状态并获取结果。

认证：请求体仅含 id；本调用不发送 API 密钥。任何知道 UUID 的人均可能轮询结果——若需限制谁能查看分数，请将 document id 视为敏感信息。

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,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

响应示例（/query，组织已启用 secure URLs）

{
    "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-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

分析结果就绪时的响应示例

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "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/..."
}

结果字段说明

is_valid: 图像文件是否有效（true/false）。
detection_step: 检测完成阶段：1 = 仅元数据；2 = 元数据 + ocr；3 = 元数据 + ocr + ml_model。
final_result: 总体判定（例如 "AI Generated"、"Real"、"Digitally Edited"、"AI Edited"）。
confidence: 检测置信度分数。
metadata: 使用 ExifTool 与 Pillow 从图像元数据提取的信息。
metadata_basic_source: 可能表明图像由特定手机拍摄、由 AI 工具生成，或经修图软件处理。
ocr: 历史字段名 ocr 下的水印检测结果。二元数组 [label, score]：label 为检测到的水印类别（如 "Gemini"）或 "OCR did not detect AI"；score 为 0–100（不确定时为 0）。有 label 时会在 warnings 中汇总。
ml_model: 机器学习模型的结果。
warnings: 可选的异构警告对象数组（类型如 blur_dark、watermark、screen_recapture 等）。可能为空或省略。
preview_url: 若 generate_preview 为 true 时的预览图 URL。可能是直连存储，或在启用 secure URLs 时为 API 路径如 https://<api-host>/preview/<document_id>。
heatmap_status: pending、ready 或 failed。热力图生成异步进行。
heatmap_url: heatmap_status 为 ready 时的热力图。外观取决于 generate_heatmap_overlayed。可能是直连存储或 API 路径 https://<api-host>/heatmap/<document_id>（secure 时需用 POST /heatmap/{id} 并带 key）。
analysis_results_status: pending、ready、skipped、failed 或 analyzing。若 generate_analysis_details 为 false 则可能省略或为 null。
analysis_results: 启用时的详细文字分析；见下文「分析结果说明」。

分析结果说明

analysis_results 就绪时通常包含：agreement（strong | moderate | weak | disagreement）、imageTags（最多五个短标签）、confidence（0–100）、keyIndicators、detailedReasoning、visualPatterns、recommendations。

说明

热力图异步生成。请轮询 /query 获取 heatmap_status 与 heatmap_url。
除非 generate_analysis_details=false，详细分析异步完成。请轮询 analysis_results_status 与 analysis_results。
Secure URLs：启用时 heatmap_url 与 preview_url 可能指向 API 主机；需用 POST /heatmap/{id} 与 POST /preview/{id} 并带密钥获取（见「安全热力图与预览资源」）。
主分数就绪后请继续轮询 /query，以便在热力图与分析完成后获取对应字段。

热力图与叠加行为

heatmap_url 指向的文件反映 /detect（或 /bulk-upload）请求中的 generate_heatmap_overlayed 与 generate_heatmap_normalized：默认叠加（true）为普通叠加图；false 通常为带透明通道的 PNG，便于界面合成。

示例：result 约 90.24、final_result 为 AI Generated、detection_step 为 3 表示元数据、OCR 与 ML 管线均已完成。

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

当 /detect 中 generate_analysis_details 为 true 时，详细分析可能在主分数之后完成。请轮询 /query 直至 analysis_results_status 为 ready（或 skipped/failed）。

1. 初始结果可能先于分析就绪

核心检测（result、final_result、confidence）可在 analysis_results_status 仍为 pending 时返回。

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

建议

可立即使用核心字段；若需要 analysis_results 请继续轮询。

2. 持续轮询

使用相同 id 调用 /query，直至 analysis_results_status 不再是 pending。

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

3. 分析完成

当 analysis_results_status 为 ready 时，analysis_results 含 agreement、imageTags、confidence、keyIndicators、detailedReasoning、visualPatterns、recommendations。

{
    "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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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/..."
}

分析不可用的情况

若 analysis_results_status 为 skipped、failed 或缺失，或 generate_analysis_details 为 false，则以核心检测为最终结果。

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

分析结果字段

analysis_results_status: pending | ready | skipped | failed | analyzing
analysis_results.agreement: strong | moderate | weak | disagreement
analysis_results.imageTags: 简短描述标签
analysis_results.confidence: 0–100
analysis_results.keyIndicators: 具体线索
analysis_results.detailedReasoning: 简要说明
analysis_results.visualPatterns: 更广泛的模式
analysis_results.recommendations: 后续建议

批量上传（ZIP）

通过上传 ZIP 在一次请求中提交多张图。流程与单图一致：预签名（ZIP 名）→ PUT ZIP → POST /bulk-upload → 轮询 /query。

1. 获取预签名上传 URL（ZIP）

对 .zip 文件名使用 get-presigned-url（例如 images.zip）。

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

请求示例

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

2. 上传 ZIP

使用 Content-Type: application/zip 将 ZIP PUT 到预签名 URL。

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

ZIP 限制

ZIP 最大：100MB
每批最多图像数：50
单张限制：最小 1KB，最大 10MB

ZIP 内支持的格式

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

ZIP 内的 PDF 不支持，将被跳过。

SVG 在检测前会转换为 PNG。

3. 提交 ZIP 进行批量检测

POST /bulk-upload，body 含 key 与指向已上传 ZIP 路径的 url。

可选参数

generate_preview: 设为 true 为各图生成预览 URL（默认：false）。
generate_analysis_details: 设为 true 生成详细分析（默认：false）。
generate_heatmap_overlayed: 与 /detect 相同（叠加 vs 透明 RGBA 热力图）。
generate_heatmap_normalized: 与 /detect 相同（默认：true）。
model: 模型域：generic、sheerid，或 instance_id/model 格式。

请求示例

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -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": false,
  "model": "generic"
}'

响应示例

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

返回 id、status pending，以及 expected_count（ZIP 中将分析的图像数量）。

ZIP 批量结果如何更新

提交后 status 为 pending，开始处理后变为 analyzing。
results 列出每张图；未完成时 result 与 result_details 可能为 null。
result_details 内的可选热力图与分析可能仍异步就绪。
results 全部完成后整体 status 为 done；若批次无法完成则可能为 failed。
ZIP 处理完成前也可调用 /query 查看部分结果。

4. 查询批量上传结果

使用 /bulk-upload 返回的 id POST /query。与单图共用端点；响应结构取决于 id 为单图还是 ZIP 批次。

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

响应示例（处理中）

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

响应字段（ZIP 批量）

id — 批量请求 id。
status — pending，随后 analyzing，最后 done 或 failed。
results — 每张待分析图像一条（id、status、result、result_details、filename、可能有 preview_url）。
skipped — 未分析的文件（类型不支持、大小等），status failed，原因在 result_details。

计费：仅对成功分析的图像扣费。SVG 转换失败与跳过的文件不计费。

安全热力图与预览资源

当 /query 中 heatmap_url 或 preview_url 指向 API 主机（非直连对象存储）时，需用 POST 并携带密钥下载字节。

POST /heatmap/{id}

POST /preview/{id}

请求体 JSON：{ "key": "YOUR-API-KEY-GOES-HERE" }

热力图响应（请检查 HTTP 状态与 Content-Type）

200 + 二进制（image/png 等）— 热力图可用。可能含 X-Heatmap-Status。
202 + JSON — heatmap_status 为 pending；请轮询 /query 后重试。
200 + JSON — 无可提供的热力图（可选功能、失败等）；非服务器错误。
500 + JSON — 已存 heatmap_url 但从存储下载失败；请稍后重试。
404 + JSON — 文档 id 不存在。
403 + JSON — API 密钥不拥有该文档。

预览：POST /preview/{id} 返回原始预览字节。未生成预览（generate_preview 为 false）时可能 404 并返回 JSON。

示例

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png

curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

内部：组织用量同步至 Stripe（任务密钥）

仅可信后端任务，非面向普通 API 客户。要求 Header x-job-secret 与服务器 JOB_SECRET 一致。将指定日期范围内 TruthScan 组织的计量用量同步至 Stripe。

POST /organizations/{org_id}/usage/sync-to-stripe

Headers: x-job-secret: <JOB_SECRET>

Body JSON：start_date、end_date，可选 idempotency_id 用于 Stripe 计量幂等。

返回 success、organization_id、total_documents、value_sent_to_stripe、report_date、message。组织非计量或缺少 stripe_customer_id 时 400；密钥无效 401；组织不存在 404；Stripe/配置错误 500。

查询用户额度

本端点通过 Header 接收用户的 apikey，并返回额度详情。

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
}

对外集成场景下，通常仅 credits 字段会有值。

健康检查

检查 API 服务器的健康状态。

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

请求示例

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

响应示例

{
    "status": "healthy"
}

返回 “healthy” 表示服务运行正常。

错误

多数错误源于向 API 传入了错误参数。请逐项核对请求，并参考文档中的示例。

通用错误码遵循 REST 惯例：

错误码	含义
400	Bad Request — 请求无效。
401	Unauthorized — 内部任务密钥无效（internal usage 端点）或类似认证失败。
403	Forbidden — API 密钥无效、拒绝访问，或额度不足以完成操作。
404	Not Found — 指定资源不存在。
405	Method Not Allowed — 使用了不允许的 HTTP 方法。
406	Not Acceptable — 请求了非 JSON 格式。
410	Gone — 该端点资源已移除。
422	Invalid Request Body — 请求体格式错误、无效或缺少参数。
429	Too Many Requests — 请求过于频繁，请降低速率。
500	Internal Server Error — 服务器异常，请稍后重试。
503	Service Unavailable — 服务临时维护或不可用，请稍后重试。

常见问题与解决方案

认证相关问题

"User verification failed" (403)

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

处理办法:

确认 API 密钥正确
在账户中确认密钥处于启用状态
尝试重新生成 API 密钥

"Not enough credits" (403)

原因: 图像处理所需额度不足

处理办法:

使用 /check-user-credits 查看剩余额度
如需请购买额外额度

输入校验问题

"Input URL cannot be empty" (400)

原因: 提交的 URL 为空或无效

处理办法:

确保 url 不为空
去除图像名称首尾空白
检查 URL 编码是否正确

"Input email is empty" (400)

原因: 处理 URL 时缺少 email

处理办法:

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

"Unsupported image type" (400)

原因: 文件格式不受支持

处理办法:

转换为受支持格式（JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF）
检查文件扩展名是否正确

"File size is too small" (400)

原因: 图像文件低于最小大小要求

处理办法:

使用更大的图像文件（最小 1KB）
检查上传过程中文件是否损坏

"File size exceeds limit" (400)

原因: 图像文件过大

处理办法:

压缩或缩放图像；上限按部署配置（API 错误信息会以 MB 标明）
尝试其他图像格式

"Invalid file type" (400)

原因: 文件类型校验失败

处理办法:

确认文件为有效图像格式
确认文件未损坏
确认 MIME 类型与扩展名一致

处理问题

图像状态为 "failed"

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

处理办法:

确认 URL 为受支持格式
确认图像有效且未损坏
确认图像满足大小要求
若问题持续请联系支持

"User not found"

原因: 用户 ID 无效

处理办法:

确认用户 ID 正确
确认账户处于活动状态
必要时重新认证

"File metadata could not be fetched" (500)

原因: 无法访问已上传文件

处理办法:

确认文件已成功上传
确认文件 URL 可访问
尝试重新上传

上传问题

"Image upload failed" (403/400)

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

处理办法:

获取预签名 URL 后尽快使用
确认 Content-Type 与文件格式一致
上传前从文件名中移除空格
必要时重新获取预签名 URL

"Invalid pre-signed URL" (400)

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

处理办法:

请求预签名 URL 前从文件名中移除空格
使用字母数字、连字符与下划线
必要时重新获取预签名 URL

批量上传问题

"URL must point to a ZIP file" (400)

原因: 提供给 /bulk-upload 的 URL 未指向 ZIP 文件

处理办法:

使用 get-presigned-url?file_name=images.zip（或其他 .zip 文件名）
将有效 ZIP 上传到预签名 URL
确认 bulk-upload 请求的 url 指向该已上传 ZIP

"ZIP file too large" (400)

原因: ZIP 超过最大体积（100MB）

处理办法:

减少图像数量或压缩后再打包
拆分为多次批量上传

"Too many files" (400)

原因: ZIP 内有效图像超过 50 张

处理办法:

每个 ZIP 不超过 50 张图像
拆分为多次批量上传

"No valid images found in ZIP" (400)

原因: ZIP 内文件均被跳过（格式不支持、过小、路径无效等）

处理办法:

使用受支持格式（JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG）
批量不支持 PDF
每张图像须介于 1KB 与 10MB 之间
避免隐藏文件（以 . 开头）与路径穿越（..）

"Document is not a bulk upload (image-zip) result" (400)

原因: id 与上传类型不匹配（单图 vs ZIP 批次）

处理办法:

单图提交请使用 /detect 返回的 id
ZIP 提交请使用 /bulk-upload 返回的 id

需要帮助？

如需更多 API 使用说明或技术支持，请联系我们。

联系我们

API 常见问题

关于 TruthScan AI 图像检测 API 的常见问题与解答。