API 文档 - 免费公共代理池

所有 API 基于 HTTP 协议，返回 JSON 格式数据（部分接口支持 text 格式）。以下示例中的路径拼接当前访问域名即可使用。

1️⃣ 获取代理列表

GET /api/v1/proxies

获取代理列表，支持按协议、国家、状态筛选，支持 JSON 和纯文本格式输出。

请求参数

参数	类型	默认	说明
protocol	string	—	筛选协议：`http`、`https`、`socks4`、`socks5`
country	string	—	筛选国家代码：`CN`、`US`、`JP` 等
status	string	alive	筛选状态：`alive`（可用）、`dead`（失效）
limit	integer	50	返回条数上限（最大 500）
format	string	json	输出格式：`json`（结构化数据）、`text`（`ip:port`）、`standard`（`protocol://ip:port`）

示例请求

# 获取最近可用的 10 个 HTTP 代理
curl "/api/v1/proxies?protocol=http&limit=10"

# 获取 5 个日本 SOCKS5 代理
curl "/api/v1/proxies?protocol=socks5&country=JP&limit=5"

# 纯文本格式（一行一个 ip:port）
curl "/api/v1/proxies?limit=20&format=text"

# 标准格式（一行一个 protocol://ip:port）
curl "/api/v1/proxies?limit=20&format=standard"
                

查看返回示例

{
  "success": true,
  "total": 10,
  "proxies": [
    {
      "ip": "103.125.31.222",
      "port": 80,
      "protocol": "http",
      "country": "BD",
      "response_time": 0.316,
      "last_checked": "2026-05-08 14:56:38",
      "status": "alive",
      "source": "free-proxy-list"
    }
  ],
  "query": {
    "protocol": "http",
    "country": null,
    "status": "alive",
    "limit": 10
  }
}

🛝 在线测试

2️⃣ 获取统计信息

GET /api/stats

获取免费公共代理池的实时统计数据：可用代理数、总数、平均响应时间、覆盖国家数。

返回字段

字段	类型	说明
`alive`	integer	可用代理数量
`total`	integer	总代理数量
`avg_response_time`	float	平均响应时间 (ms)
`countries`	integer	覆盖国家/地区数

curl "/api/stats"

查看返回示例

{
  "alive": 254,
  "total": 460,
  "avg_response_time": 3.74,
  "countries": 42
}

🛝 在线测试

3️⃣ 导出代理（文本）

GET /api/export

导出可用代理为纯文本文件（自动下载），支持按协议和国家筛选。

请求参数

参数	类型	说明
protocol	string	筛选协议（可选）
country	string	筛选国家（可选）

# 导出所有可用 HTTP 代理
curl "/api/export?protocol=http"
                

4️⃣ 服务状态

GET /api/status

获取服务运行状态和最后刷新时间。

curl "/api/status"

查看返回示例

{
  "status": "running",
  "last_refresh": "2026-05-09 00:50"
}

🛝 在线测试

5️⃣ 获取筛选选项

GET /api/filters

获取可用的协议、国家、状态筛选选项。

curl "/api/filters"

查看返回示例

{
  "protocols": ["http", "https", "socks4", "socks5"],
  "countries": ["CN", "US", "JP", ...],
  "statuses": ["alive", "dead"]
}

6️⃣ 测试代理

GET /api/proxy/<id>

获取单个代理的详细信息。

# 获取 ID 为 1 的代理详情
curl "/api/proxy/1"
                

POST /api/proxy/<id>/test

测试指定代理的连通性（异步，返回后等待几秒刷新可查看结果）。

# 测试 ID 为 1 的代理
curl -X POST "/api/proxy/1/test"
                

POST /api/test_proxy_quick

快速测试代理（同步返回结果），按 IP 和端口测试。

参数	类型	说明
ip	string	代理 IP
port	integer	代理端口
protocol	string	协议（默认 http）
proxy_id	integer	可选，传入后自动更新数据库状态

curl -X POST "/api/test_proxy_quick" \\
  -H "Content-Type: application/json" \\
  -d '{"ip":"8.8.8.8","port":80,"protocol":"http"}'
                

7️⃣ 手动刷新代理池

POST /api/refresh

触发一次完整的代理池刷新（抓取 → 验证 → 存储 → 清理）。此操作可能需要 1-3 分钟。

curl -X POST "/api/refresh"

💡 使用示例

Python

import requests

# API 根路径即当前访问域名，以下使用相对路径
# 如需跨域调用，请替换为实际部署地址

# 获取可用 HTTP 代理
resp = requests.get("/api/v1/proxies",
    params={"protocol": "http", "limit": 10})
data = resp.json()

for p in data["proxies"]:
    print(f"{p['ip']}:{p['port']}")

# 获取标准格式（protocol://ip:port）
resp = requests.get("/api/v1/proxies",
    params={"format": "standard", "limit": 5})
print(resp.text)
                

Shell 脚本

#!/bin/bash
# API 根路径即当前访问域名，以下使用相对路径
# 如需跨域调用，请设置 BASE_URL 为实际部署地址
# BASE_URL="http://your-server:5000"

# 获取可用代理并循环测试
curl -s "/api/v1/proxies?limit=5&format=text" | while read proxy; do
    echo "Testing $proxy..."
    curl -x "http://$proxy" -s -o /dev/null -w "%{http_code}" --max-time 5 "http://httpbin.org/ip"
    echo
done
                

🌐 免费公共代理池 · 开放 API v1

📡 API 文档

1️⃣ 获取代理列表

请求参数

示例请求

2️⃣ 获取统计信息

返回字段

3️⃣ 导出代理（文本）

请求参数

4️⃣ 服务状态

5️⃣ 获取筛选选项

6️⃣ 测试代理

7️⃣ 手动刷新代理池

💡 使用示例

Python

Shell 脚本