教程中心

知识库 · API 接口文档 · 常见问题,从入门到开发接入一站覆盖

全部 代理IP基础 协议配置 测试验收 选型 账号与订单 开发接入

1开发者接入五步

1
注册并购买

注册账号,选购含目标地区节点的套餐,支付后秒级开通。

2
重置密钥

在用户中心「API 提取」中重置并完整复制 sk- 开头密钥。

3
配置白名单

使用服务器出口 IP 调用时,先在「IP 白名单」中绑定(最多 10 个)。

4
生成链接

用在线生成工具选定格式与参数,或按下文文档自行拼接。

5
解析使用

程序定时拉取并解析结果,注意 5 次/秒限流与错误码重试。

2接口地址与鉴权

GEThttps://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,返回余额、有效节点数与当日用量,便于接入监控系统。

3请求参数

参数必填说明示例
key二选一用户中心生成的账户级 API 密钥,提取名下全部有效节点sk-9f3a...
token二选一订单级提取链接令牌(ext_ 开头);使用 token 时 format / sep / fields 以链接配置为准,URL 传入不生效ext-3b71...
format选填返回格式,枚举:json(默认)/ text / csvjson
protocol选填协议筛选,枚举:http / socks5;不传为不限socks5
region选填地区精确筛选,传入在售城市名;不传为全部地区上海
isp选填运营商筛选,枚举:电信 / 联通 / 移动电信
num选填提取数量,整数 0-200;0 或不传表示全部,单次最多 20010
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

4返回示例

{
  "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 状态码。

5错误码说明

code含义处理建议
0请求成功正常解析 data 字段
40002请求参数不合法(format/sep/fields 等枚举值非法)核对参数取值范围后重试
40101API 密钥无效或已被重置到用户中心确认密钥,更新配置
40401名下无有效节点(未购买或全部过期)购买套餐或续费后再提取
42901请求过于频繁,触发 5 次/秒限流降低频率并增加本地缓存

6多语言调用示例

# 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 在线生成工具,勾选参数即可生成链接,并自动同步以上示例代码。

API 密钥在哪里获取?忘记了怎么办?▾
登录用户中心,进入「API 提取」页面点击「重置密钥」,系统会生成新的 sk- 开头完整密钥,仅此一次完整展示,请立即保存。重置后旧密钥立即失效,所有使用旧密钥的程序需同步更新。
为什么返回 40101 密钥无效?▾
通常有三种原因:密钥复制不完整(必须包含 sk- 前缀)、密钥已被重置、密钥拼接到 URL 时被多余字符截断。请重新到用户中心复制完整密钥,并避免在密钥后携带空格。
返回 42901 限流如何处理?▾
每个密钥每秒最多请求 5 次。建议在服务端缓存提取结果(节点有效期内无需频繁拉取),并在收到 42901 时指数退避重试(如等待 0.5 秒、1 秒、2 秒),不要立即高频重放。
TEXT 格式的分隔符和字段怎么定制?▾
通过 sep 参数设置行间分隔符(lf/crlf/space/pipe),通过 fields 参数设置行内字段与顺序(如 fields=host,port,region),行内字段固定以英文冒号连接。JSON 与 CSV 格式不受这两个参数影响。
提取出来的代理在程序里如何填写?▾
标准写法为「协议://账号:密码@IP:端口」,例如 http://xl_8f21:a1b2c3d4@118.126.x.x:8888。SOCKS5 节点把协议头改为 socks5://。若已绑定 IP 白名单,部分客户端可省略账号密码直接填写 IP:端口。
为什么接口有节点、业务软件却连不上?▾
先在「线路检测」页验证 TCP 连通性;再核对软件支持的协议是否与节点一致、本地网络是否能访问该端口、认证信息是否完整。企业网络环境可能存在出站端口限制,可联系网络管理员放行。
可以把密钥放在网页前端或 App 里直接调用吗?▾
不可以。密钥出现在前端会被任何人提取,节点资源可能被盗用。正确做法是由你的后端服务器调用 /v1/nodes,把解析后的代理地址在受控范围内下发。因密钥泄露造成的资源消耗由账户自行承担。
白名单和账号密码鉴权有什么区别?添加后多久生效?▾
账号密码鉴权适用于大多数软件与程序;IP 白名单适用于固定出口 IP 的服务器,绑定后该出口访问节点无需账密,避免账密写进配置。两种方式可同时配置,白名单最多绑定 10 个出口 IPv4,添加后约 1-2 分钟在交付层生效。家庭宽带重启路由器后出口可能变化,需要删除旧 IP 并重新绑定。
L2TP 节点怎么用?预共享密钥在哪里看?▾
C/E/F 区为 L2TP 协议,不需要在软件里填代理地址,而是在 Windows、手机系统自带的 VPN 设置中拨号:类型选 L2TP/IPsec,填写节点地址、账号、密码,「预共享密钥(PSK)」一栏填「我的节点」中该节点显示的「密钥」。详细分步截图说明见本页「协议配置」分类下的 L2TP 教程。
第一次买,有什么低成本的验证方式?到期节点还能找回吗?▾
建议先买 1-3 份「2 小时测试套餐」,在真实软件里跑通后再买日卡 / 月卡及以上。到期前续费可沿用同一节点、出口不变;未及时续费时节点信息一般保留 7 天供续费找回,超期资源可能被释放,建议重要业务提前续费或直接选长周期。
「线路检测」的三种检测模式分别看什么?▾
TCP 连通验证服务器能否连到节点端口(不通多为端口受限或线路故障);SOCKS5 握手验证协议与账密是否有效(TCP 通但握手失败多为账密或协议选错);HTTP 出口会实际经过节点请求公网回显,确认出口 IP 的地区与运营商。单次最多 50 条,支持 host:端口、host:端口:账号:密码、协议://账号:密码@host:端口 三种输入格式,结果为瞬时状态参考,不能替代业务协议层验证。
程序提示 40101,但密钥刚复制的没错,是什么原因?▾
除了密钥复制不完整或被重置,还有一种常见原因:把 sk- 密钥放进了 Authorization: Bearer 请求头。Bearer 头只接受登录后颁发的网页令牌(JWT),程序调用请把 sk 密钥放在查询参数 key 中;使用订单提取链接则传 token=ext_ 开头的令牌。