接口概述
一句话说明
ip.query 是 XAPI 提供的 HTTP 接口，用于返回调用方的公网 IP 地址。
服务端按 X-Forwarded-For → X-Real-IP →
Proxy-Client-IP → WL-Proxy-Client-IP →
remoteAddr 的顺序取第一个有效值，多级代理取逗号分隔的第一段，
因此可正确工作在 Nginx 等反向代理之后。
| 请求地址 | https://api.xujian.tech/openapi/ip/query |
|---|---|
| 请求方式 | GET |
| 鉴权方式 | 请求头 X-API-Key（不做签名与加密） |
| 接口编码 | ip.query |
| 收费类型 | FREE（免费，0 元，不扣费、不消耗余额） |
| 响应格式 | JSON，Content-Type: application/json;charset=UTF-8 |
| 是否需要授权 | 否（免费接口无需单独授权，有 API Key 即可调用） |
| 典型用途 | 出口 IP 探测、代理/NAT 环境验证、服务端白名单自检、爬虫出口 IP 核对 |
快速开始
一行命令即可调用，把 你的APIKey 换成控制台获取的 API Key：
curl -s "https://api.xujian.tech/openapi/ip/query" \
-H "X-API-Key: 你的APIKey"请求参数
该接口无 Query / Body 参数，仅需请求头。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
X-API-Key |
String | 是 | 开发者 API Key，在控制台创建后获取；缺失或无效会返回失败 |
X-Forwarded-For |
String | 否 | 反向代理场景由网关自动追加，服务端优先取该头的第一个 IP |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
code |
int | 状态码，0 表示成功，非 0 表示失败（常见为 500） |
msg |
String | 结果描述，成功为 success，失败为具体原因 |
data |
Object | 业务数据，失败时为 null |
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
ip |
String | 203.0.113.8 | 调用方公网 IP，IPv4 或 IPv6 取决于来源 |
apiCode |
String | ip.query | 接口编码 |
apiName |
String | 查询公网IP | 接口名称 |
chargeType |
String | FREE | 计费类型：FREE 免费 / PER_CALL 按次 / MONTHLY 按月 / YEARLY 按年（本接口后台配置为 FREE） |
balance |
BigDecimal | 0.0000 | 调用后账户余额（元）；免费接口不扣费，余额保持不变 |
costMs |
Long | 3 | 本次调用耗时（毫秒） |
响应示例
成功（code = 0）
{
"code": 0,
"msg": "success",
"data": {
"ip": "203.0.113.8",
"apiCode": "ip.query",
"apiName": "查询公网IP",
"chargeType": "FREE",
"balance": 0.0000,
"costMs": 3
}
}失败（缺少 API Key）
{
"code": 500,
"msg": "缺少请求头 X-API-Key",
"data": null
}错误码与常见失败原因
| code | msg（示例） | 处理建议 |
|---|---|---|
| 0 | success | 调用成功 |
| 500 | 缺少请求头 X-API-Key | 在请求头中补充 X-API-Key |
| 500 | API Key 无效 | 检查 Key 是否正确或已被重新生成 |
| 500 | API Key 已停用 | 在控制台重新启用或新建 Key |
| 500 | 客户不存在或已停用 | 联系平台运营确认账号状态（可联系微信xujian_cq） |
| 500 | 接口不存在或已停用 | 确认接口编码 ip.query 当前是否维护中 |
多语言代码示例
Java（Hutool）
String body = HttpRequest.get("https://api.xujian.tech/openapi/ip/query")
.header("X-API-Key", apiKey)
.timeout(5000)
.execute()
.body();
JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") == 0) {
String ip = json.getJSONObject("data").getStr("ip");
System.out.println("公网 IP：" + ip);
}Python
import requests
resp = requests.get(
"https://api.xujian.tech/openapi/ip/query",
headers={"X-API-Key": API_KEY},
timeout=5,
)
data = resp.json()
if data["code"] == 0:
print("公网 IP：", data["data"]["ip"])JavaScript（浏览器 / Node 18+）
const resp = await fetch("https://api.xujian.tech/openapi/ip/query", {
headers: { "X-API-Key": API_KEY }
});
const { code, data } = await resp.json();
if (code === 0) {
console.log("公网 IP：", data.ip);
}常见问题（FAQ）
ip.query 接口怎么收费？
ip.query 接口完全免费，收费类型为 FREE，调用不扣费、不消耗账户余额，也不需要单独授权，仅需在请求头携带有效的 X-API-Key。
调用 ip.query 需要签名或加密吗？
不需要。XAPI 的接口仅校验请求头 X-API-Key，不做签名、时间戳或加密，直接 HTTP GET 即可。
为什么返回的 IP 和本机 ipconfig 看到的不一样？
本机 ipconfig 通常是内网地址（如 192.168.x.x、10.x.x.x）。接口返回的是服务端看到的出口公网 IP， 两者不一致属于正常现象。
接口支持 IPv6 吗？
支持。若客户端以 IPv6 地址访问，返回的 ip 字段即为 IPv6 地址，格式与调用方来源保持一致。
没有 API Key 可以调用吗？
不可以。缺少 X-API-Key 请求头会返回 code=500、msg=缺少请求头 X-API-Key。 注册开发者账号后可在控制台获取 API Key。
接口有调用频率限制吗？
当前版本未做硬性限流，但请合理调用；高频场景建议本地缓存结果，公网出口 IP 通常不会频繁变化。
