IPRisk IPRisk
中文|English
API v1

IP 纯净度 API

通过单一接口获取 IP 纯净度评分、网络类型、代理、VPN、Tor、地区与 ASN 等核心结果。网页检测、批量任务和 API 共用同一套 16 源评分引擎。

请求

字段类型必填说明
ipstring公网 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"}'

成功响应

{ "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" } }

响应字段

字段类型说明
ipstring规范化后的公网 IPv4 / IPv6
scorenumber0–100 纯净度评分,分数越高越纯净
cleanliness_levelstringexcellent / good / fair / low / very_low / poor
ip_typestring网络类型,例如 residential、mobile、datacenter
proxy / vpn / torboolean代理、VPN 与 Tor 检测结果
hostingboolean是否为托管或数据中心网络
country / country_code / citystring | null地理位置共识结果
asn / organizationstring | null自治系统编号与网络组织
success_sourcesnumber成功返回的数据源数量,最多 16
checked_atstringISO 8601 检测完成时间
billing.chargedboolean本次是否实际扣除额度
billing.creditsnumber本次扣除额度,只会是 0 或 1

过渡期响应还会保留 risk_level 兼容旧客户端;新集成请使用 cleanliness_level。

计费与结果质量

每次请求会先预留 1 次额度。只有至少 12 个来源成功,并且网络归属、代理/VPN、路由、威胁情报等核心能力覆盖完整时才实际扣费。检测失败或覆盖不完整时自动退回额度,仍然可用的结果会正常返回。缓存命中视为一次有效查询。

评分算法、权重与网页检测完全一致;API 不暴露第三方原始响应。

状态码与处理建议

HTTPcode含义建议
400invalid_ip / unsupported_ipIP 格式无效,或不是公网地址修正请求,不要重试原值
401invalid_api_keyAPI Key 缺失或无效检查 Bearer 密钥
402insufficient_credits额度不足补充额度或升级方案
409query_in_progress同一 IP 正在检测稍后重试
429rate_limited超过方案频率限制降低速率并退避
503engine_busy / backend_unavailable服务暂时繁忙或恢复中指数退避后重试

调用约定

  • 响应头 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 表示当前频率窗口;429 时应按照 Retry-After 稍后重试。
  • 使用 HTTPS,请勿在前端代码、公开仓库或日志中暴露 API Key。
  • request_id 可用于问题排查;联系支持时请提供该值,不要提供 API Key。
  • 响应允许跨域调用,但生产环境建议由你自己的服务端保管并调用 API Key。