IP 列表服务 - 帮助文档

快速开始 鉴权说明 积分说明 API接口 跳转模式 注意事项

快速开始

  1. 获取 API Key：请联系管理员获取
  2. 访问用户面板：/user?key=你的API_KEY
  3. 开始使用 API 接口

鉴权说明

所有 API 接口均支持两种鉴权方式，Token 优先级高于 API Key。

积分（API Key 余额）说明

查询积分余额： 
GET /api/key/balance?key=你的API_KEY
返回示例： 
{
  "balance": 0
}
校验API Key有效性： 
GET /api/check-key?key=你的API_KEY
返回示例： 
{
  "valid": true,
  "balance": 0,
  "msg": "API Key 已用完积分，请充值"
}

API 接口说明

1. 创建任务

请求： 
GET /api/server?key=你的API_KEY&imgurl=图片URL&time=10
参数：
参数类型说明
keystringAPI Key（必填，除非使用token）
tokenstring管理员Token（可选，优先级高于key）
imgurlstring图片URL（可选）
timeint任务时长，单位分钟（可选，默认10）
modestring任务模式，支持jump跳转
jumpurlstring跳转目标URL，配合mode=jump使用
返回示例： 
{
  "taskId": "任务ID",
  "recordUrl": "记录URL"
}
常见错误示例： 
{
  "success": false,
  "code": 10001,
  "message": "Key余额不足，无法开启任务",
  "error": "Key余额不足"
}

2. 获取任务IP列表

请求： 
GET /api/getip/任务ID?key=你的API_KEY
参数：
参数类型说明
keystringAPI Key（必填，除非使用token）
tokenstring管理员Token（可选，优先级高于key）
type4/6获取IPv4或IPv6（可选）
geostring指定IP信息API（可选）
返回示例： 
{
  "ips": [
    {
      "ip": "IP地址",
      "apis": [],
      "created_at": "访问时间"
    }
  ]
}

3. 停止任务

请求： 
GET /api/stop?key=你的API_KEY&id=任务ID
参数：
参数类型说明
keystringAPI Key（必填，除非使用token）
tokenstring管理员Token（可选，优先级高于key）
idstring任务ID（必填）
返回示例： 
{ "success": true }

4. 获取任务列表

请求： 
GET /api/list?key=你的API_KEY
参数：
参数类型说明
keystringAPI Key（必填，除非使用token）
tokenstring管理员Token（可选，优先级高于key）
返回示例： 
{
  "tasks": [
    {
      "id": "任务ID",
      "status": "活跃/暂停",
      "created_at": "创建时间",
      "imgurl": "图片URL",
      "time": "任务时长",
      "ipCount": "IP数量"
    }
  ]
}

跳转模式（mode=jump）

跳转模式允许任务链接被访问时自动302跳转到指定网址，适合推广、统计等场景。
只需创建任务时带上 mode=jump&jumpurl=目标URL 参数。
示例： 
GET /api/server?key=你的API_KEY&mode=jump&jumpurl=https://www.baidu.com
访问任务链接时： 
GET /api/page/任务ID
效果：
浏览器将自动跳转到 jumpurl，并记录访问IP。

注意事项

错误码与返回结构说明

常见HTTP状态码

状态码含义典型场景
200OK请求成功，返回数据
201Created创建资源成功
204No Content操作成功，无返回内容
302Found跳转（如/jump、mode=jump任务）
400Bad Request参数错误、请求格式不合法
401Unauthorized未认证，token/key无效或缺失
403Forbidden无权限，积分不足、账号被封禁等
404Not Found资源不存在
429Too Many Requests触发限流
500Internal Server Error服务器内部错误

返回字段释义

字段类型说明
successboolean是否成功，true/false
codeint业务错误码，0为成功
messagestring结果说明/错误描述
dataobject主要返回数据内容
errorstring错误信息（失败时）
statusintHTTP状态码（部分接口）
建议优先判断 success 字段，或 code==0 代表成功。
部分接口如积分不足、key无效、限流等会返回 403/429，请注意处理。

常见问题 FAQ

Q: 积分为0还能登录和查余额吗？
A: 可以，积分为0时仍可登录、查余额和任务，但无法新建任务、获取IP等。
Q: 如何充值积分？
A: 请联系管理员，提供API Key，由管理员后台充值。
Q: 跳转模式如何用？
A: 创建任务时带上 mode=jump&jumpurl=目标URL，访问任务链接会自动跳转。
Q: 为什么提示"Key无效或余额不足"？
A: 可能是API Key填错、已被删除或积分已用完。请检查Key或联系管理员。
Q: 触发限流怎么办？
A: 请降低请求频率，或联系管理员调整限流参数。