API v1
IP 纯净度 API
通过单一接口获取 IP 纯净度评分、网络类型、代理、VPN、Tor、地区与 ASN 等核心结果。网页检测、批量任务和 API 共用同一套 16 源评分引擎。
请求
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ip | string | 是 | 公网 IPv4 或 IPv6,最长 64 个字符 |
curl -X POST https://iprisk.top/v1/check -H "Authorization: Bearer ipr_live_xxx" -H "Content-Type: application/json" -d '{"ip":"1.1.1.1"}'const response = await fetch('https://iprisk.top/v1/check', {
method: 'POST',
headers: { Authorization: 'Bearer ipr_live_xxx', 'Content-Type': 'application/json' },
body: JSON.stringify({ ip: '1.1.1.1' })
});
const result = await response.json();import requests
response = requests.post(
'https://iprisk.top/v1/check',
headers={'Authorization': 'Bearer ipr_live_xxx'},
json={'ip': '1.1.1.1'},
timeout=60,
)
result = response.json()<?php
$ch = curl_init('https://iprisk.top/v1/check');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ipr_live_xxx', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['ip' => '1.1.1.1']),
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);requestBody := strings.NewReader(`{"ip":"1.1.1.1"}`)
req, _ := http.NewRequest("POST", "https://iprisk.top/v1/check", requestBody)
req.Header.Set("Authorization", "Bearer ipr_live_xxx")
req.Header.Set("Content-Type", "application/json")
response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)成功响应
{
"success": true,
"request_id": "7f3e8d21-...",
"cached": false,
"credits_remaining": 9999,
"billing": {
"charged": true,
"credits": 1,
"success_sources": 16,
"minimum_sources": 12,
"missing_coverage_groups": []
},
"data": {
"ip": "1.1.1.1",
"score": 45,
"cleanliness_level": "low",
"ip_type": "datacenter",
"proxy": false,
"vpn": false,
"tor": false,
"hosting": true,
"country": "Australia",
"country_code": "AU",
"city": "Sydney",
"asn": "AS13335",
"organization": "Cloudflare, Inc.",
"success_sources": 16,
"checked_at": "2026-09-20T12:00:00.000Z"
}
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| ip | string | 规范化后的公网 IPv4 / IPv6 |
| score | number | 0–100 纯净度评分,分数越高越纯净 |
| cleanliness_level | string | excellent / good / fair / low / very_low / poor |
| ip_type | string | 网络类型,例如 residential、mobile、datacenter |
| proxy / vpn / tor | boolean | 代理、VPN 与 Tor 检测结果 |
| hosting | boolean | 是否为托管或数据中心网络 |
| country / country_code / city | string | null | 地理位置共识结果 |
| asn / organization | string | null | 自治系统编号与网络组织 |
| success_sources | number | 成功返回的数据源数量,最多 16 |
| checked_at | string | ISO 8601 检测完成时间 |
| billing.charged | boolean | 本次是否实际扣除额度 |
| billing.credits | number | 本次扣除额度,只会是 0 或 1 |
过渡期响应还会保留 risk_level 兼容旧客户端;新集成请使用 cleanliness_level。
计费与结果质量
每次请求会先预留 1 次额度。只有至少 12 个来源成功,并且网络归属、代理/VPN、路由、威胁情报等核心能力覆盖完整时才实际扣费。检测失败或覆盖不完整时自动退回额度,仍然可用的结果会正常返回。缓存命中视为一次有效查询。
评分算法、权重与网页检测完全一致;API 不暴露第三方原始响应。
状态码与处理建议
| HTTP | code | 含义 | 建议 |
|---|---|---|---|
| 400 | invalid_ip / unsupported_ip | IP 格式无效,或不是公网地址 | 修正请求,不要重试原值 |
| 401 | invalid_api_key | API Key 缺失或无效 | 检查 Bearer 密钥 |
| 402 | insufficient_credits | 额度不足 | 补充额度或升级方案 |
| 409 | query_in_progress | 同一 IP 正在检测 | 稍后重试 |
| 429 | rate_limited | 超过方案频率限制 | 降低速率并退避 |
| 503 | engine_busy / backend_unavailable | 服务暂时繁忙或恢复中 | 指数退避后重试 |
调用约定
- 响应头 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 表示当前频率窗口;429 时应按照 Retry-After 稍后重试。
- 使用 HTTPS,请勿在前端代码、公开仓库或日志中暴露 API Key。
- request_id 可用于问题排查;联系支持时请提供该值,不要提供 API Key。
- 响应允许跨域调用,但生产环境建议由你自己的服务端保管并调用 API Key。