API v1
IP 纯净度 API
通过单一接口获取 IP 纯净度评分、网络类型、代理、VPN、Tor、地区与 ASN 等核心结果。网页检测、批量任务和 API 使用一致的检测标准。
请求
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ip | string | 是 | 公网 IPv4，最长 15 个字符 |
普通调用API Key + IP
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"}'自动重试Idempotency-Key
IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"
curl -X POST https://iprisk.top/v1/check \
-H "Authorization: Bearer ipr_live_xxx" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"ip":"1.1.1.1"}'同一次查询重试时复用相同的 Idempotency-Key；新查询生成新值。
普通调用API Key + IP
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();自动重试Idempotency-Key
const idempotencyKey = crypto.randomUUID();
const response = await fetch('https://iprisk.top/v1/check', {
method: 'POST',
headers: {
Authorization: 'Bearer ipr_live_xxx',
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({ ip: '1.1.1.1' })
});
const result = await response.json();同一次查询重试时复用相同的 Idempotency-Key；新查询生成新值。
普通调用API Key + IP
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()自动重试Idempotency-Key
import uuid
import requests
idempotency_key = str(uuid.uuid4())
response = requests.post(
'https://iprisk.top/v1/check',
headers={
'Authorization': 'Bearer ipr_live_xxx',
'Idempotency-Key': idempotency_key,
},
json={'ip': '1.1.1.1'},
timeout=60,
)
result = response.json()同一次查询重试时复用相同的 Idempotency-Key；新查询生成新值。
普通调用API Key + IP
<?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);自动重试Idempotency-Key
<?php
$idempotencyKey = bin2hex(random_bytes(16));
$ch = curl_init('https://iprisk.top/v1/check');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ipr_live_xxx',
'Idempotency-Key: ' . $idempotencyKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['ip' => '1.1.1.1']),
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);同一次查询重试时复用相同的 Idempotency-Key；新查询生成新值。
普通调用API Key + IP
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)自动重试Idempotency-Key
idempotencyBytes := make([]byte, 16)
if _, err := rand.Read(idempotencyBytes); err != nil {
log.Fatal(err)
}
idempotencyKey := hex.EncodeToString(idempotencyBytes)
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("Idempotency-Key", idempotencyKey)
req.Header.Set("Content-Type", "application/json")
response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)同一次查询重试时复用相同的 Idempotency-Key；新查询生成新值。
成功响应
{
"success": true,
"request_id": "7f3e8d21-...",
"credits_remaining": 9999,
"data": {
"ip": "1.1.1.1",
"score": 45,
"cleanliness_level": "low",
"ip_type": "datacenter",
"proxy": false,
"vpn": false,
"tor": false,
"hosting": true,
"country": null,
"country_code": null,
"city": null,
"asn": "AS13335",
"organization": "Cloudflare, Inc.",
"checked_at": "2026-09-25T12:00:00.000Z"
}
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| ip | string | 规范化后的公网 IPv4 |
| score / cleanliness_level | number / string | 0–100 纯净度评分及对应等级，分数越高越纯净 |
| ip_type | string | 网络类型，例如 residential、mobile、datacenter |
| proxy / vpn / tor / hosting | boolean | 代理、VPN、Tor 与数据中心检测结果 |
| country / country_code / city | string | null | 地理位置共识结果；Anycast 无唯一位置时返回 null |
| asn / organization | string | null | 自治系统编号与网络组织 |
| checked_at | string | ISO 8601 检测完成时间 |
| credits_remaining | number | null | 本次调用后的剩余额度；不限额账户返回 null |
计费规则
每次成功返回完整结果的 API 请求消耗 1 次额度；检测未完成时返回可重试错误，不扣除额度。
网页检测、批量查询和 API 使用一致的成功标准。
状态码
| HTTP | code | 含义 | 处理 |
|---|---|---|---|
| 200 | — | 检测成功 | 读取 data |
| 400 | invalid_ip / unsupported_ip / invalid_json / invalid_idempotency_key | 请求格式或参数无效 | 修正请求 |
| 401 | invalid_api_key | API Key 无效 | 检查密钥 |
| 402 | insufficient_credits | 额度不足 | 补充额度 |
| 403 | account_inactive / plan_required | 账户或方案不可用 | 检查账户状态 |
| 409 | idempotency_request_in_progress / idempotency_key_reused / idempotency_key_conflict | 幂等键正在处理、已使用或存在冲突 | 处理中稍后重试；新查询生成新值 |
| 413 | payload_too_large | 请求体过大 | 缩小请求体 |
| 429 | rate_limited | 请求频率过高 | 按照 Retry-After 重试 |
| 503 | check_incomplete / engine_busy / engine_recovering / service_restarting / backend_timeout / backend_unavailable / rate_limiter_unavailable / database_error | 检测未完成或服务暂时不可用 | 未扣额度；稍后重试 |
使用说明
- 自动重试时，同一次查询复用相同的 Idempotency-Key；新查询生成新值。
- 收到 429 或可重试错误时，按照 Retry-After 稍后重试。
- 请在服务端安全保存 API Key；排查问题时提供 request_id，不要提供密钥。