知识库 · API 接口文档 · 常见问题,从入门到开发接入一站覆盖
注册账号,选购含目标地区节点的套餐,支付后秒级开通。
在用户中心「API 提取」中重置并完整复制 sk- 开头密钥。
使用服务器出口 IP 调用时,先在「IP 白名单」中绑定(最多 10 个)。
用在线生成工具选定格式与参数,或按下文文档自行拼接。
程序定时拉取并解析结果,注意 5 次/秒限流与错误码重试。
https://api.你的域名/v1/nodes鉴权方式(三选一,推荐第一种):
key=sk-xxxx:账户级密钥,提取名下全部有效节点,后端程序调用请用这种方式;token=ext_xxxx:订单级提取链接,仅返回该链接绑定订单的节点,输出格式以链接配置为准;Authorization: Bearer 登录令牌:仅会员中心网页「立即提取」内部调试使用,令牌是登录后颁发的 JWT,不是 sk 密钥(把 sk 密钥放进 Bearer 头会返回 40101)。密钥在用户中心重置后旧密钥立即失效;请妥善保存,只放在自有后端,不要写入网页前端、App 安装包或公开仓库。
频率限制:每个密钥 / 令牌 5 次 / 秒,超限返回 42901;建议本地缓存提取结果,按业务节奏拉取,不要每次使用代理都请求一次接口。
另有账户概览接口 GET /v1/account?key=sk-xxxx,返回余额、有效节点数与当日用量,便于接入监控系统。
| 参数 | 必填 | 说明 | 示例 |
|---|---|---|---|
| key | 二选一 | 用户中心生成的账户级 API 密钥,提取名下全部有效节点 | sk-9f3a... |
| token | 二选一 | 订单级提取链接令牌(ext_ 开头);使用 token 时 format / sep / fields 以链接配置为准,URL 传入不生效 | ext-3b71... |
| format | 选填 | 返回格式,枚举:json(默认)/ text / csv | json |
| protocol | 选填 | 协议筛选,枚举:http / socks5;不传为不限 | socks5 |
| region | 选填 | 地区精确筛选,传入在售城市名;不传为全部地区 | 上海 |
| isp | 选填 | 运营商筛选,枚举:电信 / 联通 / 移动 | 电信 |
| num | 选填 | 提取数量,整数 0-200;0 或不传表示全部,单次最多 200 | 10 |
| sep | 选填 | 仅 text 格式生效,行间分隔符:lf(默认,\n)/ crlf(\r\n)/ space(空格)/ pipe(|) | lf |
| fields | 选填 | 仅 text 格式生效,行内字段(逗号分隔,顺序即输出顺序):host,port,user,pass,region,isp,expire;默认 host,port,user,pass,行内以冒号连接 | host,port,region |
{
"code": 0,
"message": "ok",
"data": [
{
"host": "118.126.x.x",
"port": 8888,
"protocol": "http",
"user": "xl_8f21",
"pass": "a1b2c3d4",
"region": "上海",
"isp": "电信",
"expire_at": "2026-10-01"
}
]
}
118.126.x.x:8888:xl_8f21:a1b2c3d4 113.220.x.x:8888:xl_8f21:e5f6g7h8 183.230.x.x:8888:xl_8f21:i9j0k1l2
host,port,protocol,user,pass,region,isp,expire_at 118.126.x.x,8888,http,xl_8f21,a1b2c3d4,上海,电信,2026-10-01 113.220.x.x,8888,socks5,xl_8f21,e5f6g7h8,北京,联通,2026-10-01
注意:业务错误时 HTTP 状态码仍为 200,但响应体为 {"code": 错误码, "message": "..."},请以 code 字段判断成败,不要只判断 HTTP 状态码。
| code | 含义 | 处理建议 |
|---|---|---|
| 0 | 请求成功 | 正常解析 data 字段 |
| 40002 | 请求参数不合法(format/sep/fields 等枚举值非法) | 核对参数取值范围后重试 |
| 40101 | API 密钥无效或已被重置 | 到用户中心确认密钥,更新配置 |
| 40401 | 名下无有效节点(未购买或全部过期) | 购买套餐或续费后再提取 |
| 42901 | 请求过于频繁,触发 5 次/秒限流 | 降低频率并增加本地缓存 |
# pip install requests
import requests
API_URL = "https://api.你的域名/v1/nodes"
API_KEY = "sk-你的密钥"
def get_proxies():
"""提取节点并转换为 requests 可用的代理字典,失败返回空列表"""
resp = requests.get(API_URL, params={
"key": API_KEY,
"format": "json",
"protocol": "http",
"region": "上海",
"num": 10,
}, timeout=10)
data = resp.json()
if data["code"] != 0:
print("提取失败:", data["code"], data["message"])
return []
proxies = []
for n in data["data"]:
url = "http://%s:%s@%s:%s" % (n["user"], n["pass"], n["host"], n["port"])
proxies.append({"http": url, "https": url})
return proxies
for px in get_proxies():
try:
r = requests.get("https://httpbin.org/ip", proxies=px, timeout=8)
print(r.json(), "via", px["http"])
except Exception as e:
print("该节点不可用,跳过:", e)
// JDK 11+ 内置 HttpClient,无需第三方依赖
import java.net.URI;
import java.net.http.*;
public class NodeFetcher {
public static void main(String[] args) throws Exception {
String key = "sk-你的密钥";
String url = "https://api.你的域名/v1/nodes?key=" + key
+ "&format=json&protocol=http&num=10";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.timeout(java.time.Duration.ofSeconds(10))
.GET().build();
HttpResponse response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// 正常时可使用 Jackson/Gson 解析 data 数组
System.out.println(response.body());
}
}
// Go 1.20+,仅使用标准库
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
type apiResp struct {
Code int `json:"code"`
Data []struct {
Host string `json:"host"`
Port int `json:"port"`
User string `json:"user"`
Pass string `json:"pass"`
} `json:"data"`
}
func main() {
url := "https://api.你的域名/v1/nodes?key=sk-你的密钥&format=json&num=10"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var out apiResp
if err := json.Unmarshal(body, &out); err != nil {
panic(err)
}
for _, n := range out.Data {
fmt.Printf("http://%s:%s@%s:%d\n", n.User, n.Pass, n.Host, n.Port)
}
}
<?php
// 需开启 curl 扩展
$apiKey = 'sk-你的密钥';
$url = 'https://api.你的域名/v1/nodes?' . http_build_query([
'key' => $apiKey,
'format' => 'json',
'protocol' => 'http',
'num' => 10,
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$result = curl_exec($ch);
curl_close($ch);
$data = json_decode($result, true);
if ($data['code'] !== 0) {
exit('提取失败: ' . $data['message']);
}
foreach ($data['data'] as $n) {
// 组合代理地址:协议://账号:密码@IP:端口
echo "http://{$n['user']}:{$n['pass']}@{$n['host']}:{$n['port']}\n";
}
不想拼参数?使用官网 API 在线生成工具,勾选参数即可生成链接,并自动同步以上示例代码。
sk- 密钥放进了 Authorization: Bearer 请求头。Bearer 头只接受登录后颁发的网页令牌(JWT),程序调用请把 sk 密钥放在查询参数 key 中;使用订单提取链接则传 token=ext_ 开头的令牌。