获取代理列表
GET /api/v1/proxies
返回当前仍在有效期内、通过验证的代理列表快照。
protocol=http：支持 http、socks4、socks5；https 作为 HTTP CONNECT 别名。limit=20：默认最多 20 条，单次上限 10000 条。
国家和匿名等级元数据暂未提供，不建议使用对应筛选。
DEVELOPER DOCUMENTATION
已验证免费代理列表 API 文档
使用一个有期限的 API key 获取经过应用层验证的公开免费代理列表。订阅费用用于采集、验证和 API 交付；接口返回的是代理元数据，不是转发后的网页内容，也不是开放代理中继。
获取单个代理
GET /api/v1/proxy
使用同样的筛选参数随机返回一个可用记录；没有匹配项时返回 404。
两个接口都需要在请求头中提供 X-API-Key，也兼容 Authorization: Bearer …。
curl -H "X-API-Key: fp_live_..." \
"https://proxylistapi.xyz/api/v1/proxies?protocol=http&limit=20"RESPONSE CONTRACT
让调用方可以判断新鲜度
列表响应包含快照和验证元数据。调用方应在真实请求失败时轮换代理，并检查过期字段。
快照字段
snapshotVersion：当前筛选结果版本，可用于缓存。generatedAt：快照生成时间。validUntil：当前返回记录中最早的过期时间。count、proxies：记录数量和数据数组。
代理字段
protocol、ip、port：连接所需信息。verified、validated_at、expires_at：验证状态和时间。validation_target、validation_latency_ms：验证证据。source、sources、capabilities：来源和能力元数据。
ACCESS LIFECYCLE
key 什么时候失效？
续费成功后自动延长访问时间，原 key 保持不变。取消自动续费后仍可使用至已付费周期结束；扣款失败或订阅失效会返回 401。服务按订阅项目的 current_period_end 校验期限。
Python 获取代理列表示例
在服务端环境变量中设置 FREEPROXY_API_KEY。以下代码仅使用 Python 标准库获取代理记录；使用代理时，请另行配置 HTTP 客户端的代理参数。
import json, os, urllib.request
request = urllib.request.Request(
"https://proxylistapi.xyz/api/v1/proxies?protocol=http&limit=20",
headers={"X-API-Key": os.environ["FREEPROXY_API_KEY"]},
)
with urllib.request.urlopen(request, timeout=15) as response:
snapshot = json.load(response)
for proxy in snapshot["proxies"]:
print(proxy["proxy"], proxy["expires_at"])请求限制与错误处理
每个 key 限制为每秒 3 次请求，突发额度为 3；每个 IP 限制为每秒 1 次请求，突发额度为 1。共享网络出口的用户共用 IP 额度。按需获取记录，单次上限 10000 条。
| 响应 | 处理方式 |
|---|---|
| 200，count: 0 | 没有匹配记录；减少筛选条件或稍后重试。 |
| 304 | ETag 未变化；复用本地快照，并检查每条记录的 expires_at。 |
| 401 | 检查 key 和订阅扣款状态。 |
| /proxy 返回 404 | 没有匹配代理；稍后重试，避免立即循环调用。 |
| 429 | 至少等待 Retry-After 指定时间，使用指数退避并加入随机延迟。 |
| 5xx | 服务暂时失败，退避后重试。 |
“已验证”具体代表什么？
发布的代理通过了应用层可达性检查，且未超过 expires_at。validation_target 表示验证目标，validated_at 是验证时间，validation_latency_ms 是这次检查的耗时。该耗时不是下载速度，也不保证其他网站接受该代理。
如何使用 HTTP 和 SOCKS 代理？
https 筛选对应 HTTP CONNECT 代理，不代表到代理本身使用 TLS。SOCKS4 和 SOCKS5 需要客户端支持相应协议。在本地维护小型列表，丢弃过期记录，连接失败时选择另一条。
如何减少重复请求？
保存列表响应的 ETag，下次使用相同筛选条件时通过 If-None-Match 发送。返回 304 前仍会检查授权和代理有效性。API key 放在请求头中，不要写入 URL。
还没有 API key？
无需注册，付款后从成功页领取。