云病毒查询引擎

云病毒查询引擎通过文件哈希值查询文件是否被活跃检测服务识别为病毒。接口只接收哈希，不上传文件内容，适合在上传前检查、文件分享风控、下载前提示和后台批量巡检等场景中接入。

重要说明

查询结果仅表示指定数据源在查询时刻的检测状态。is_virus: false 表示未被活跃服务检出，不等同于文件绝对安全；仍应结合文件来源、业务规则和本地安全软件作出处理决策。

Endpoint

GET https://virus.api.tqxtu.com/hash_scan

所有请求均使用 HTTPS，并通过查询参数传递平台接口密钥和文件哈希。

适用场景

• 上传前校验：在文件进入存储系统前，根据已计算的哈希进行快速风险检查。
• 分享与下载提示：为命中风险的文件增加拦截、人工复核或下载前风险提示。
• 存量文件巡检：按既有 MD5、SHA-1 或 SHA-256 索引，对历史文件进行批量查询。
• 安全运营联动：将查询结果写入审计日志，再与文件来源、上传账号和下载行为关联分析。

快速开始

将 平台接口密钥 替换为已分配的接口密钥，将 文件的哈希值 替换为待查询文件的哈希。

curl --get 'https://virus.api.tqxtu.com/hash_scan' \
  --data-urlencode 'api_key=平台接口密钥' \
  --data-urlencode 'hash=40fee2a4be91d9d46cc133328ed41a3bdf9099be5084efbc95c8d0535ecee496'

接入建议

如业务系统已在上传、去重或完整性校验时计算 SHA-256，优先复用该结果，避免为查询接口重复读取整份文件。

请求参数

参数	位置	必填	说明
api_key	Query	是	平台接口密钥。仅应保存在服务端环境变量或密钥管理服务中。
hash	Query	是	待查询文件的哈希值。请传入完整原始值，不要附加算法名称、空格或分隔符。

接口返回样例包含 MD5、SHA-1 和 SHA-256。若接入方可选择算法，建议统一使用 SHA-256；服务端对具体哈希格式的校验规则以实际接口返回为准。

判定流程

1. 在可信环境中计算或读取文件哈希。
2. 服务端携带 api_key 调用查询接口。
3. 先确认响应中的 status 为 success，再读取 is_virus。
4. 当 is_virus 为 true 时，按业务策略阻止、隔离或转人工复核。
5. 当 is_virus 为 false 时，可继续业务流程，同时保留来源可信度、文件类型限制等其他安全检查。

计算文件哈希 → 调用 hash_scan → 检查 status → 检查 is_virus → 执行业务处置

响应说明

成功响应使用 JSON 对象。应以 status 和 is_virus 共同判断，不要仅依据 HTTP 成功状态码决定文件是否安全。

字段	类型	说明
status	String	请求处理状态。成功示例中的值为 success。
is_virus	Boolean	true 表示文件被识别为病毒；false 表示未被任何活跃服务检出。
source	String	检测结果来源标识。成功命中示例中的值为 tqcloud。
data	Object	命中病毒时返回的文件哈希及首次、最后观测时间。
data.sha256	String	文件 SHA-256 哈希。
data.md5	String	文件 MD5 哈希。
data.sha1	String	文件 SHA-1 哈希。
data.first_seen	String	首次观测到该文件的时间。
data.last_seen	String	最近一次观测到该文件的时间。
message	String	非病毒结果或其他响应中的提示信息。

病毒命中示例

{
  "status": "success",
  "is_virus": true,
  "source": "tqcloud",
  "data": {
    "sha256": "40fee2a4be91d9d46cc133328ed41a3bdf9099be5084efbc95c8d0535ecee496",
    "md5": "512301c535c88255c9a252fdf70b7a03",
    "sha1": "ca3a1070cff311c0ba40ab60a8fe3266cfefe870",
    "first_seen": "2026-07-13 14:09:10",
    "last_seen": "2026-07-13 14:09:10"
  }
}

建议处置：拦截自动分发；保留哈希、查询时间与来源标识；由安全人员结合业务上下文复核后再决定是否解除限制。

未检出示例

{
  "status": "success",
  "is_virus": false,
  "message": "Not detected by any active service"
}

建议处置：可继续后续流程，但不要将该结果展示为“绝对无毒”或替代终端防护、文件类型校验和权限控制。

业务接入建议

上传链路

对于需要计算哈希的上传服务，可采用以下顺序：

1. 接收文件时流式计算 SHA-256，避免将整份大文件读入内存。
2. 完整性校验通过后，在服务端调用本接口。
3. 若命中病毒，标记文件为隔离状态并阻止公开分享或下载。
4. 若未检出，再进入常规转码、预览、索引或发布流程。

批量巡检

将同一哈希的查询合并为一次请求，并对结果设置短期缓存，可以减少重复调用。缓存键可包含哈希值和数据源标识；具体缓存时长应由业务风险要求决定，风险敏感场景应更频繁地重新查询。

面向用户的提示

推荐使用中性、可行动的文案，例如“该文件被安全检测服务标记为存在风险，暂不可下载。如认为误判，请联系管理员。”避免向普通访问者暴露接口密钥、完整安全审计细节或内部处置规则。

错误处理与兼容性

当前公开样例仅定义了成功响应。接入方应对以下情况进行防御性处理：

• 网络超时、DNS 失败或 TLS 连接失败；
• 非 2xx HTTP 响应；
• 无法解析为 JSON 的响应；
• status 不为 success；
• 缺少 is_virus 字段或字段类型不是布尔值；
• 服务端新增未知字段或补充错误信息。

在上述异常情况下，建议记录请求追踪信息（不含 api_key），并根据业务风险采取“暂缓处理、人工复核或受限放行”等策略。不要把接口异常自动当作“未检出”。

安全与隐私

• 密钥只放服务端：不要在浏览器 JavaScript、移动端安装包、公开仓库或截图中暴露 api_key。
• 使用环境变量：例如 VIRUS_SCAN_API_KEY，由部署环境注入；日志中对密钥进行脱敏。
• 全程 HTTPS：调用地址已经使用 HTTPS，客户端不应降级为不安全传输。
• 最小化记录：按业务需要保存哈希和判定结果；哈希可能与特定文件关联，仍应遵循内部数据访问控制要求。
• 结果不是唯一防线：继续执行文件类型、大小、权限、内容审核及终端防护等既有控制措施。

下一步

• 语言调用示例