# 🔌 OpenAPI

EProxies 对外提供 5 个 HTTP 接口(白名单模式的代理提取与白名单管理)。本页是接口清单速查,详细用法见 [API 提取(白名单模式)](https://www.eproxies.io/docs/usage/api-extraction)。

> 机器可读定义:[openapi.json](https://www.eproxies.io/docs/openapi.json) — OpenAPI 3.0 规范,可直接导入 Postman / Swagger UI / Insomnia,或供 AI Agent 加载后自动调用。

## 基础信息

| 项目 | 值 |
| --- | --- |
| Base URL | `https://api.eproxies.net` |
| 认证(提取类) | 请求需从**白名单 IP** 发起,无需账密 |
| 认证(管理类) | 查询参数 `userName` + `userKeyValue`(用户密钥,控制台获取) |
| 代理网关 | `proxy.eproxies.net:23333`(HTTP/HTTPS/SOCKS5,非本 HTTP API) |

## 接口清单

### `GET /gateway_api/extract_ip`

提取代理 — 按条件批量提取代理端点。请求必须从白名单 IP 发起,返回的代理直连使用、无需账密。

**请求参数**

| 字段 | 类型 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- | --- |
| `count` | integer | 是 | `1` ~ N | 提取数量 |
| `country` | string | 否 | `US` `GB` `JP` … / `Global` | 国家码(ISO 3166-1 两位);`Global` 表示不限国家 |
| `protocol` | string | 否 | `http` / `socks5` | 代理协议 |
| `format` | string | 否 | `txt` / `json` | 返回格式;`json` 返回对象数组,`txt` 返回纯文本行 |
| `separator` | string | 否 | `crlf` `br` `cr` `lf` `tab` | `txt` 格式的分隔符:分别对应 `\r\n`、`</br>`、`\r`、`\n`、`\t` |
| `st` | string | 否 | — | 自定义分隔符,填写后替代 `separator` |
| `session` | string | 否 | `sticky` / `random` | IP 类型:`sticky` 复用同一批 IP,`random` 每次随机 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ipAddress` | string | 代理 IP 地址 |
| `portValue` | integer | 代理端口 |

`format=json` 时返回上述字段构成的对象数组;`format=txt` 时按 `separator` 分隔返回 `IP:端口` 文本行。

**示例**

```bash
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"
```

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

### `GET /gateway_api/country-list`

支持的国家列表 — 查询白名单模式下可提取的全部国家。

**请求参数**

无请求参数。

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `country` | string | 国家码(ISO 3166-1 两位),用于 `extract_ip` 的 `country` 参数 |
| `name` | string | 国家名称 |
| `flag_url` | string | 国旗图标地址 |

**示例**

```bash
curl "https://api.eproxies.net/gateway_api/country-list"
```

```json
[
  { "country": "US", "name": "United States", "flag_url": "https://file.eproxies.net/flags/us.png" }
]
```

### `GET /gateway_api/add-ip`

添加白名单 IP — 把一个出口 IP 加入白名单,加入后该 IP 即可免密提取代理。

**请求参数**

| 字段 | 类型 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- | --- |
| `userName` | string | 是 | — | 账号用户名 |
| `userKeyValue` | string | 是 | — | 用户密钥,在控制台获取 |
| `ipAddress` | string | 是 | — | 要加入白名单的 IP 地址 |

**响应字段**

返回操作结果对象,以实际响应为准。

**示例**

```bash
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/del-ip`

删除白名单 IP — 把一个 IP 移出白名单,移出后该 IP 不能再免密提取。

**请求参数**

| 字段 | 类型 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- | --- |
| `userName` | string | 是 | — | 账号用户名 |
| `userKeyValue` | string | 是 | — | 用户密钥,在控制台获取 |
| `ipAddress` | string | 是 | — | 要移除的白名单 IP |

**响应字段**

返回操作结果对象,以实际响应为准。

**示例**

```bash
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/lists-ip`

查询白名单列表 — 查询当前账号下全部白名单条目。

**请求参数**

| 字段 | 类型 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- | --- |
| `userName` | string | 是 | — | 账号用户名 |
| `userKeyValue` | string | 是 | — | 用户密钥,在控制台获取 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ipAddress` | string | 白名单 IP |
| `remarkText` | string | 备注 |

**示例**

```bash
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

## 快速调用

```bash
# 提取 10 个美国 HTTP 代理(JSON 格式,粘性 IP)
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# 把当前服务器 IP 加入白名单
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

## 在 AI Agent 中使用

把规范地址交给 agent,即可让其自动理解全部参数与响应结构:

```
https://www.eproxies.io/docs/openapi.json
```

配合 [Agent 速查表](https://www.eproxies.io/docs/agent-reference)(代理网关的 username 参数语法)即为完整接入信息。