# 账户令牌 GET 提取接口

公开动态 API 的认证、参数和响应字段说明。

使用账户 API 令牌或历史 API Link 认证；实际来源 IPv4 必须在本人启用白名单，提取校验实名和协议匹配权益。GET/POST 提取为 兼容格式，不支持会话、州省和城市参数。

所有示例为合成数据与占位凭据，仅展示结构；接口合同不代表目标环境已开放。

## 接口与认证

`GET /openapi/v1/proxy/extract`

使用 HTTPS；api_key Query、X-API-Key 或 Authorization: Bearer 支持同值认证，冲突值拒绝。实际来源白名单仍须有效。

## 请求参数

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| api_key | string | 否 | Query · 或认证请求头 | 账户 API 令牌，在受控服务端保存；示例使用占位符。 |
| num | integer | 是 | query · 最小 1；最大 100 | 提取条数。 |
| regions | string | 否 | query · 默认 GLOBAL | 国家代码，来自国家目录；兼容 country 别名，同时传入须一致。 |
| protocol | string | 否 | query · 默认 http；枚举 http / socks5 | HTTP 代理可 CONNECT 访问 HTTPS 目标；不接受 https。 |
| return_type | string | 否 | query · 默认 json；枚举 json / txt | 返回格式。 |
| lb | string | 否 | query · 默认 1；枚举 1 / 2 / 3 / 4 / 5 / 6 | TXT 分隔符：1 CRLF、2 /br、3 CR、4 LF、5 TAB、6 自定义 sb。 |
| sb | string | 否 | query · — | lb=6 必填，非空且 UTF-8 字节长度最多 32。 |
| request_id | string | 否 | query · — | 可选幂等请求号，省略读取 X-Request-Id 或服务端生成。 |

无请求体。

## 请求示例

```bash
curl --request GET \
  "https://api.zzhttp.com/openapi/v1/proxy/extract?api_key=${API_KEY}&num=1&regions=GLOBAL&protocol=http"
```

## 成功响应

响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。

HTTP 200 · JSON：成功或逐项批量结果，请同时核对业务码。

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| code | integer | 是 | 固定 0 | 兼容成功码为 0，与静态 API 成功码 200 不同。 |
| success | boolean | 是 | 固定 true | 成功标记。 |
| msg | string | 是 | — | 结果说明。 |
| data | object | 是 | — | 本接口业务数据。 |
| data.ip | string | 是 | — | 代理网关 IP 或主机名。 |
| data.port | integer | 是 | — | 代理网关端口。 |
| request_ip | string | 是 | — | 服务端识别的真实调用来源 IPv4。 |

```json
{
  "code": 0,
  "success": true,
  "msg": "Successfully obtained",
  "data": [
    {
      "ip": "203.0.113.20",
      "port": 7878
    }
  ],
  "request_ip": "198.51.100.10"
}
```

HTTP 200 · TXT：return_type=txt 的纯文本响应，按 lb/sb 分隔。

```text
203.0.113.20:7878
```

## 错误与重试

请求中断复用原 requestId/request_id；部分返回通过 X-Proxy-Requested-Count、X-Proxy-Returned-Count 与 X-Proxy-Partial 判断。资源不足按 Retry-After 等待，国家目录可有限重试读取。

错误码、HTTP 状态及错误响应字段统一见[错误码与处理建议](/developers/errors/error-codes)。

html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}