API 文档

AI 音频检测 API

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

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

认证

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

所有 API 请求必须在请求体中包含 API 密钥，如下所示：

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

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

AI 音频检测

检测流程（3 步）

AI 音频检测流程包括：

获取上传 URL
上传音频
提交检测

1. 获取预签名上传 URL

通过 API 请求预签名 URL，用于安全上传音频文件。

支持格式

MP3, WAV, M4A, FLAC, OGG, MP4

重要提示

获取 URL 时文件名不能包含空格。

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

示例请求

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

示例响应

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

2. 上传音频

使用 presigned_url 通过 PUT 请求上传音频文件，并确保 Content-Type 正确。

重要提示

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

示例请求

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

文件大小限制

最小 1KB
最大 100MB

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

3. 提交检测

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

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

示例请求

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

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

可选参数

analyzeUpToSeconds: 分析前 N 秒（默认 60）
document_type: 文档类型（默认 Audio）
email: 处理通知邮箱（可选）

示例响应

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

响应中包含唯一 ID，用于查询检测状态。

查询检测状态与结果

通过 /query 接口使用 ID 查询检测状态与结果。

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

示例请求

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

示例响应

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

结果说明

is_valid: 音频是否有效
message: 处理状态信息
original_duration: 音频时长（秒）
is_truncated: 是否被截断
truncated_duration: 实际分析时长
mean_ai_prob: 整体 AI 概率评分
individual_chunks_ai_prob: 分段 AI 概率评分

状态包括："pending"（排队中）、"analyzing"（分析中）、"done"（完成）、"failed"（失败）。

查询用户积分

通过请求头传入 API Key，返回用户积分信息。

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

示例请求

curl -X 'GET' \
  'https://detect-audio.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-audio.truthscan.com/health

示例请求

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

示例响应

{
    "status": "healthy"
}

错误说明

大多数错误来自参数错误，请检查请求格式。

错误码遵循 REST 标准：

错误码	说明
400	请求错误
403	权限不足或积分不足
404	资源不存在
405	请求方法错误
406	不支持的格式（需 JSON）
410	资源已删除
422	请求体错误或缺少参数
429	请求过多
500	服务器错误
503	服务不可用

常见问题与解决方案

认证相关问题

"User verification failed" (403)

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

解决方案:

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

"Not enough credits" (403)

原因: 音频处理积分不足

解决方案:

使用 /check-user-credits 查询剩余积分
按需购买额外积分
使用 analyzeUpToSeconds 仅分析部分时长以降低消耗

输入校验问题

"Unsupported file format" (400)

原因: 提交了不支持或无效的音频格式

解决方案:

确认格式受支持（MP3、WAV、M4A、FLAC、OGG、MP4）
确认文件未损坏
上传时检查 Content-Type 是否正确

"File too large" (400)

原因: 文件超过 100MB 限制

解决方案:

将音频压缩或转换至 100MB 以下
上传前检查文件大小
可尝试使用 MP3 等更高效格式

处理问题

"Audio processing took too long"

原因: 音频处理耗时过长或发生超时

解决方案:

尝试更短或更小的音频文件
使用 analyzeUpToSeconds 仅分析前几秒
检查服务是否负载较高
数分钟后重试

/query 响应中状态为 "failed"

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

解决方案:

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

上传问题

"Audio upload failed" (403/400)

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

解决方案:

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

"Invalid pre-signed URL" (400)

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

解决方案:

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

需要帮助？

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

联系我们

API 常见问题

关于 AI 音频检测 API 的常见问题。