API 文档

AI 视频检测 API

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

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

认证

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

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

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

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

AI 视频检测

检测流程（2 步）

检测流程包括：

提交视频进行检测
查询检测结果

1. 提交视频检测

直接上传视频文件，服务器将进行验证。

支持格式

MP4, MOV, AVI, MKV, WEBM

文件大小限制

最小 1KB
最大 100MB

POST https://detect-video.truthscan.com/detect-file

示例请求

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

可选参数

document_type: 文档类型（默认：Video）
email: 处理通知邮箱

示例响应

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

返回视频 ID 用于后续查询。

2. 查询结果

通过 /query 接口获取检测状态和结果。

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

示例请求

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

示例响应

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

结果说明

status: 状态（pending / analyzing / done / failed）
result: 检测评分（0.0 - 1.0）
final_stage: 最终检测阶段
metadata: 元数据检测
watermark: 水印检测
ml: 模型分析结果
latency_sec: 处理时间

状态包括 pending、analyzing、done、failed。

查询积分

返回账户积分信息。

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

示例请求

curl -X 'GET' \
  'https://detect-video.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
}

健康检查

检查 API 服务状态。

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

示例请求

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

示例响应

{
    "status": "healthy"
}

错误说明

大多数错误由参数问题引起，请检查请求。

错误码遵循 REST 标准：

错误码	说明
400	请求错误
403	权限不足或积分不足
404	资源不存在
429	请求过多
500	服务器错误
503	服务不可用

常见问题与解决方案

认证相关问题

"User verification failed" (403)

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

解决方案:

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

"Not enough credits" (403)

原因: 视频处理积分不足

解决方案:

使用 /check-user-credits 查询剩余积分
按需购买额外积分

输入校验问题

"Unsupported video type" (400)

原因: 文件格式不受支持

解决方案:

转换为受支持格式（MP4、MOV、AVI、MKV、WEBM）
确认扩展名与 MIME 类型一致

"File size exceeds limit" (400)

原因: 视频文件过大

解决方案:

压缩、裁剪或重新编码以减小体积（最大 100MB）
使用更高效的编码或容器格式

"File size is too small" (400)

原因: 文件小于最小大小要求

解决方案:

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

"Invalid file type" (400)

原因: 类型校验失败（例如 MIME 类型错误或文件损坏）

解决方案:

确认文件为有效视频格式
确认 MIME 类型与扩展名一致
必要时重新导出或重新编码

处理问题

视频状态为 "failed"

原因: 处理失败（如容器无法读取、解码错误等）

解决方案:

使用常见支持的容器/编码（建议 MP4 中的 H.264/AAC）
使用标准预设重新编码（如 ffmpeg）后重新上传
确认文件满足格式与大小要求

视频状态为 "timeout" 或处理过久

原因: 处理时间超出预期或已超时

解决方案:

稍等片刻后通过 /query 再次查询状态
确认视频满足格式与大小要求
若问题持续请联系支持

"User not found"

原因: 用户 ID 无效

解决方案:

确认 API 密钥正确且绑定有效账户
确认集成用户有效且处于激活状态
必要时重新认证

"File metadata could not be fetched" (500)

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

解决方案:

确认上传已成功完成
确认文件可访问且未损坏
尝试重新上传文件

需要帮助？

如需支持，请联系我们。

联系我们

常见问题

关于 AI 视频检测 API 的常见问题解答。