API 参考

短效代理只有一个对外接口：提取代理 IP 列表。

正常使用时不需要手动拼接这个请求——在用户中心【短效代理】→【生成API】里点几下就能生成完整链接（见快速开始指南）。本页面向需要在程序里动态构造请求的场景。

接口地址

GET https://api.beesproxy.com/api/v1/proxies/

请求参数

参数名	类型	必填	说明
`order_id`	string	是	订单号。在用户中心【短效代理】页查看
`user_token`	string	是	用户令牌。在用户中心【总览】页查看
`ip_num`	integer	否	本次提取的 IP 数量。缺省时按订单的 IP 提取数返回
`format`	string	否	返回格式，`json` 或 `text`。接口默认 `json`
`line_split`	string	否	文本格式的换行符，见下方说明。仅在 `format=text` 时有意义

`ip_num`：上限由订单决定

单次可提取的数量上限等于你订单的「IP 提取数」，在【短效代理】订单页可以看到（形如 IP提取数100-提取间隔5秒）。

两个需要注意的行为：

不传 ip_num → 按订单的 IP 提取数返回
传的值超过订单上限 → 静默截断到订单上限，不会报错。你请求 500 个、订单是 100 个，就只会收到 100 个

提取频率：由订单决定，不是固定值

调用间隔等于你订单的「提取间隔」，同样在订单页显示。不同订单的间隔不同（常见有 5 秒、10 秒）。

在间隔内重复调用会返回 21003，错误信息里会明确告诉你该等几秒：

{ "code": 21003, "message": "调用频率过快，请每隔5秒请求一次" }

不要按文档写死一个秒数去轮询——以你自己订单页显示的间隔为准。

`line_split`：只有两个值会生效

取值	换行符
`windows`	`\r\n`
`mac`	`\r`
其他任何值（含不传、含写 `unix`）	`\n`

注意 macOS 换行符的取值是 mac，不是 macOS。

`format`：默认值两边不一致

接口的默认值是 json，但用户中心生成器表单的默认选项是「文本格式」。也就是说，你从生成器复制到的链接里通常带着 &format=text。

建议统一用 json：文本格式在出错时仍会返回 JSON（见下文），响应体格式会在成功与失败之间突变，程序更难处理。

请求示例

https://api.beesproxy.com/api/v1/proxies/?order_id=YOUR_ORDER_ID&user_token=YOUR_TOKEN&format=json&ip_num=10

也可以在用户中心的【生成API】页面可视化生成：/oms/generate/api

响应格式

JSON 格式

format=json 时返回：

{
  "code": 0,
  "result": [
    {
      "host": "222.79.179.194",
      "port": "44966",
      "city_cn": "福建省泉州市石狮市"
    },
    {
      "host": "125.121.152.174",
      "port": "58337",
      "city_cn": "浙江省杭州市"
    }
  ]
}

字段	说明
`code`	`0` 表示成功，非 `0` 表示出错
`result`	代理列表
`result[].host`	代理 IP
`result[].port`	代理端口，字符串类型
`result[].city_cn`	该 IP 的归属地

文本格式

format=text 时返回纯文本，每行一个 host:port，行间以 line_split 指定的换行符分隔：

202.104.185.150:49806
123.190.161.223:48500
183.166.123.204:45710
125.121.152.174:58337
119.102.173.102:52324

文本格式不含归属地信息。

如何判断请求是否成功

这一节请务必读完，它决定了你的错误处理写得对不对。

出错时 HTTP 状态码同样是 200。 接口不会返回 4xx/5xx，因此：

❌ 不要用 resp.raise_for_status() / resp.ok / res.status === 200 判断成败
❌ 不要依赖响应头的 Content-Type 判断响应体是不是 JSON——错误响应不带 Content-Type: application/json
✅ 始终按 JSON 解析响应体，然后检查 code 字段是否为 0

另外一个容易踩的点：即使请求时指定了 format=text，出错时返回的仍然是 JSON。所以用文本格式时，你的解析逻辑要能同时处理「一堆 ip:port 行」和「一个 JSON 错误对象」两种形态。这也是建议直接用 format=json 的原因。

错误响应

{
  "code": 21003,
  "message": "调用频率过快，请每隔5秒请求一次",
  "results": [],
  "resource": "GET /api/v1/proxies/"
}

字段	说明
`code`	错误码，见下表
`message`	错误描述，部分错误码的描述是动态拼接的（会带上具体的秒数、订单号等）
`results`	恒为空数组，出错时无意义
`resource`	出错的接口，排查时可用

错误码说明

错误码	说明	怎么处理
`13000`	缺少 `user_token` 参数	检查 URL 是否漏了 `user_token=`
`18003`	剩余可提取代理数不足	试用订单的累计额度已用尽，购买正式订单
`21000`	用户不存在	订单归属的账号异常，请联系客服
`21001`	订单号不存在	`order_id` 格式合法但查不到该订单，确认是否复制完整
`21002`	`user_token` 不正确	token 抄错，或 token 已被重置——回【总览】页取新 token 并重新生成链接
`21003`	调用频率过快	按订单的提取间隔控制调用节奏，间隔见订单页
`21004`	订单号格式非法	`order_id` 不是合法的订单号格式。抄错订单号时最常见的是这个错误，不是 21001
`21006`	服务已过期	订单已到期，续费后可继续使用。续费不改变订单号

关于返回条数与重复

代理 IP 从代理池中随机抽取，具体行为如下：

单次返回的 IP 之间不会重复
多次提取之间可能重复 —— 接口不记录你上次取过哪些 IP，两次调用拿到相同 IP 属于正常现象
代理池临时不足时，会返回少于 ip_num 条，不会报错

所以你的程序不应假设「一定能拿到 ip_num 个」或「两次的结果一定不同」。需要更多不重复 IP 时，请拉长两次提取的间隔，而不是缩短。

下一步

查看代码示例获取 Python / Node.js / Java 的完整实现
查看白名单配置——提取到 IP 之后，代理能不能用取决于白名单