语言调用示例

本页展示云病毒查询引擎的服务端调用方式。示例均以 SHA-256 为例；请将示例中的密钥替换为部署环境注入的真实值，且不要把密钥交给浏览器或移动端。

cURL

bash

curl --get 'https://virus.api.tqxtu.com/hash_scan' \
  --data-urlencode "api_key=$VIRUS_SCAN_API_KEY" \
  --data-urlencode 'hash=40fee2a4be91d9d46cc133328ed41a3bdf9099be5084efbc95c8d0535ecee496'

Node.js

以下示例适用于支持全局 fetch 的 Node.js 运行时。URLSearchParams 会正确编码查询参数。

const endpoint = 'https://virus.api.tqxtu.com/hash_scan'

export async function scanHash(hash) {
  const apiKey = process.env.VIRUS_SCAN_API_KEY
  if (!apiKey) {
    throw new Error('VIRUS_SCAN_API_KEY is not configured')
  }

  const url = new URL(endpoint)
  url.search = new URLSearchParams({ api_key: apiKey, hash }).toString()

  const response = await fetch(url, {
    headers: { accept: 'application/json' },
    signal: AbortSignal.timeout(10_000)
  })

  if (!response.ok) {
    throw new Error(`Virus scan request failed: HTTP ${response.status}`)
  }

  const result = await response.json()
  if (result.status !== 'success' || typeof result.is_virus !== 'boolean') {
    throw new Error('Virus scan returned an unexpected response')
  }

  return result
}

const result = await scanHash('40fee2a4be91d9d46cc133328ed41a3bdf9099be5084efbc95c8d0535ecee496')
console.log(result.is_virus ? '检测到风险' : '未检出')

Python

python

import os
import requests

ENDPOINT = 'https://virus.api.tqxtu.com/hash_scan'

def scan_hash(file_hash: str) -> dict:
    api_key = os.environ.get('VIRUS_SCAN_API_KEY')
    if not api_key:
        raise RuntimeError('VIRUS_SCAN_API_KEY is not configured')

    response = requests.get(
        ENDPOINT,
        params={'api_key': api_key, 'hash': file_hash},
        timeout=10,
    )
    response.raise_for_status()

    result = response.json()
    if result.get('status') != 'success' or not isinstance(result.get('is_virus'), bool):
        raise RuntimeError('Virus scan returned an unexpected response')
    return result

result = scan_hash('40fee2a4be91d9d46cc133328ed41a3bdf9099be5084efbc95c8d0535ecee496')
print('检测到风险' if result['is_virus'] else '未检出')

PHP

php

<?php

function scanHash(string $hash): array
{
    $apiKey = getenv('VIRUS_SCAN_API_KEY');
    if (!$apiKey) {
        throw new RuntimeException('VIRUS_SCAN_API_KEY is not configured');
    }

    $url = 'https://virus.api.tqxtu.com/hash_scan?' . http_build_query([
        'api_key' => $apiKey,
        'hash' => $hash,
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Accept: application/json'],
    ]);

    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($body === false || $status < 200 || $status >= 300) {
        throw new RuntimeException("Virus scan request failed: HTTP {$status}");
    }

    $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (($result['status'] ?? null) !== 'success' || !is_bool($result['is_virus'] ?? null)) {
        throw new RuntimeException('Virus scan returned an unexpected response');
    }

    return $result;
}

文件哈希计算示例

查询接口只接收哈希。以下 Node.js 片段以流式方式计算文件 SHA-256，适合在上传服务或后台任务中使用：

import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'

export function sha256File(filePath) {
  return new Promise((resolve, reject) => {
    const hash = createHash('sha256')
    const stream = createReadStream(filePath)

    stream.on('error', reject)
    stream.on('data', chunk => hash.update(chunk))
    stream.on('end', () => resolve(hash.digest('hex')))
  })
}

前端接入边界

不要从浏览器直接调用该接口，因为查询参数中包含 api_key。正确方式是：浏览器将文件或哈希提交给自己的后端；后端负责计算或校验哈希、调用云病毒查询引擎，并只向前端返回业务允许展示的风险状态。

重试策略

仅在网络临时失败、超时或服务端错误等可恢复异常时进行有限重试，并使用指数退避。对于接口正常返回但 status 非 success、响应结构异常或文件命中风险的情况，不应盲目重试，应记录并转入相应的业务处置流程。

更多字段和判定含义请参考云病毒查询引擎概览。

语言调用示例 ​

cURL ​

Node.js ​

Python ​

PHP ​

文件哈希计算示例 ​

前端接入边界 ​

重试策略 ​