VirusTotal API v3是目前官方主推的接口版本，相比旧版本在功能完整性和数据规范性上都有明显提升，其中URL扫描是安全检测场景中非常常用的功能，很多开发者需要基于该接口实现自动化URL安全校验能力。
前期准备工作
在使用VirusTotal API v3之前，需要先完成基础的配置工作，避免后续调用过程中出现权限问题。
- 注册VirusTotal账号，在个人中心获取专属的API Key，免费版接口有每分钟4次、每天500次的调用限制
- 确认接口的基础地址为
https://www.virustotal.com/api/v3/，所有请求都需要携带鉴权信息 - 准备好发送HTTP请求的工具，比如Python的requests库、Postman等，本文以Python为例进行演示
URL扫描的完整流程
第一步：提交URL扫描任务
首先需要将待检测的URL提交到VirusTotal的扫描队列，提交成功后接口会返回一个分析ID，后续需要通过这个ID获取最终的分析报告。
提交请求的示例如下：
import requests
# 替换为自己的VirusTotal API Key
api_key = "your_virustotal_api_key"
# 待检测的URL，需要先进行URL编码处理
target_url = "http://test-domain.com/malicious-page"
# 提交扫描的接口地址
scan_url = "https://www.virustotal.com/api/v3/urls"
headers = {
"x-apikey": api_key,
"Content-Type": "application/x-www-form-urlencoded"
}
# 请求体中的url参数需要是编码后的URL
data = {"url": target_url}
response = requests.post(scan_url, headers=headers, data=data)
# 打印响应状态码和返回数据
print(response.status_code)
print(response.json())
提交成功后，响应数据中会包含data.id字段，这个就是后续查询报告需要的分析ID，格式类似u-xxxxxx。
第二步：轮询获取分析报告
URL提交扫描后不会立即返回完整结果，VirusTotal需要调用多个引擎对URL进行检测，因此需要轮询查询分析状态，直到检测完成。
查询报告的接口地址为https://www.virustotal.com/api/v3/analyses/{分析ID}，请求示例如下：
import time
import requests
api_key = "your_virustotal_api_key"
# 替换为上一步获取到的分析ID
analysis_id = "u-xxxxxx"
# 查询报告的接口地址
report_url = f"https://www.virustotal.com/api/v3/analyses/{analysis_id}"
headers = {
"x-apikey": api_key
}
# 轮询查询，最多查询10次，每次间隔3秒
for i in range(10):
response = requests.get(report_url, headers=headers)
result = response.json()
# 获取当前分析状态
status = result["data"]["attributes"]["status"]
print(f"第{i+1}次查询，当前状态：{status}")
if status == "completed":
print("分析完成，完整报告：")
print(result)
break
# 未完成时等待3秒再查询
time.sleep(3)
第三步：解析分析报告数据
当分析状态为completed时，返回的数据就是完整的URL分析报告，核心字段的含义如下：
| 字段路径 | 含义说明 |
|---|---|
| data.attributes.stats.malicious | 标记为恶意的检测引擎数量 |
| data.attributes.stats.harmless | 标记为无害的检测引擎数量 |
| data.attributes.results | 各个检测引擎的具体检测结果 |
| data.attributes.date | 分析完成的时间戳 |
如果malicious字段的数值大于0，说明该URL被至少一个安全引擎标记为恶意，需要进一步处理。
常见问题与解决方法
请求返回401错误
通常是API Key填写错误或者请求头中x-apikey字段的格式不正确，需要检查API Key是否正确，以及请求头是否携带了该字段。
分析报告一直显示queued状态
说明当前扫描队列任务较多，需要适当延长轮询的间隔时间，或者增加轮询次数，免费版接口的扫描优先级较低，等待时间可能更长。
提交URL后返回400错误
通常是URL格式不正确，需要确保提交的URL包含协议头（http或者https），如果是特殊字符较多的URL，需要先进行URL编码再提交。
注意：不要频繁调用接口，避免触发VirusTotal的限流机制，免费版接口如果超过调用限制，会被暂时封禁IP，需要等待一段时间才能恢复使用。
VirusTotal_API_v3URL扫描分析报告获取API调用修改时间：2026-07-10 20:21:26