---
title: "代理 API 参考：用量、代理列表与 SERP | Proxonym"
description: "Proxonym REST API 参考：API 密钥、速率限制、错误，以及账户、用量、代理列表、IP 白名单、子用户和 SERP API 的端点。"
url: https://proxonym.com/zh/docs/api
updated: 2026-10-02T03:03:46+00:00
---

# Proxonym API 参考

通过 JSON REST API 管理余额、用量、代理列表、IP 白名单和子用户，并通过 SERP API 获取解析好的 Google 搜索结果。

- 基础 URL `https://api.proxonym.com/v1`
- 身份验证 `Authorization: Bearer API_KEY`
- 格式 `JSON`
- 速率限制 `60 / min`

### 目录

API 速览

- **基础 URL**: `api.proxonym.com/v1`
- **身份验证**: `Bearer API_KEY`
- **格式**: `JSON`
- **速率限制**: `60 / min`

端点

- [`GET` /account](https://proxonym.com/zh/docs/api#account)
- [`GET` /usage](https://proxonym.com/zh/docs/api#usage)
- [`GET` /proxies/{product}](https://proxonym.com/zh/docs/api#proxy-lists)
- [`GET POST DEL` /whitelist](https://proxonym.com/zh/docs/api#whitelist)
- [`GET POST PATCH DEL` /sub-users](https://proxonym.com/zh/docs/api#sub-users)
- [`GET` serp…/v1/search](https://proxonym.com/zh/docs/api#serp-api)

**遇到问题？**帮助中心解答计费、错误和账户方面的问题。

[帮助中心](https://proxonym.com/zh/help) [检测代理](https://proxonym.com/zh/proxy-checker)

## 概览

借助 Proxonym API，您可以通过代码管理账户：读取余额和套餐、拉取用量、下载代理列表、编辑 IP 白名单以及管理子用户。Google SERP API（谷歌搜索结果 API）使用独立的主机，以 JSON 格式返回解析好的搜索结果。

### 基础 URL

**文本**

```text
https://api.proxonym.com/v1
```

本参考中的路径均相对于基础 URL。所有请求均使用 HTTPS。SERP API 有自己的基础 URL：`https://serp.proxonym.com/v1`。

### OpenAPI 描述文件

账户 API 另提供 OpenAPI 3.1 描述文件，位于 [/docs/api/openapi.json](https://proxonym.com/docs/api/openapi.json)，可直接用于客户端生成器、API 工具和 AI 智能体。

### 版本控制

主版本号包含在路径中。不兼容的变更会以新版本发布。在 `v1` 内，可能会新增端点、可选参数和响应字段，因此请确保客户端能够忽略无法识别的字段。

### 约定

- **格式：**响应均为 UTF-8 编码的 JSON，响应头带有 `Content-Type: application/json`；使用 `format=txt` 请求的代理列表除外。请求体请以 JSON 格式发送，并带上 `Content-Type: application/json` 请求头。
- **状态码：**成功时返回 `200`，创建资源时返回 `201`。失败情况的说明请见[错误](https://proxonym.com/zh/docs/api#errors)。
- **时间戳：**采用 UTC 时间的 ISO 8601 格式，例如 `2026-10-01T09:30:00Z`。日期参数可接受完整的时间戳，也可接受 `2026-09-24` 这样的日期（按 UTC 零点处理）。
- **流量：**以 GB 为单位，用十进制小数表示，例如 `17.836`。
- **ID：**带类型前缀的字符串，例如子用户 ID `su_3k9x2m7q`。请将其视为不透明的标识符。
- **缺失值：**以 `null` 表示，例如，永不过期的流量包会显示 `"expires_at": null`。
- **产品：** `residential`、`mobile`、`unlimited`、`isp`、`datacenter`、`dedicated` 和 `serp`。

### 端点

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | [`/account`](https://proxonym.com/zh/docs/api#account-get) | 账户、GB 余额和有效套餐 |
| `GET` | [`/usage`](https://proxonym.com/zh/docs/api#usage-get) | 单个产品在一段时间内的用量 |
| `GET` | [`/proxies/{product}`](https://proxonym.com/zh/docs/api#proxy-lists-get) | 数据中心、ISP 或独享代理的代理列表 |
| `GET` | [`/whitelist`](https://proxonym.com/zh/docs/api#whitelist-list) | 列出白名单中的 IP |
| `POST` | [`/whitelist`](https://proxonym.com/zh/docs/api#whitelist-add) | 将 IP 添加到白名单 |
| `DELETE` | [`/whitelist/{ip}`](https://proxonym.com/zh/docs/api#whitelist-remove) | 从白名单中移除 IP |
| `GET` | [`/sub-users`](https://proxonym.com/zh/docs/api#sub-users-list) | 列出子用户 |
| `POST` | [`/sub-users`](https://proxonym.com/zh/docs/api#sub-users-create) | 创建子用户 |
| `PATCH` | [`/sub-users/{id}`](https://proxonym.com/zh/docs/api#sub-users-update) | 更新子用户 |
| `DELETE` | [`/sub-users/{id}`](https://proxonym.com/zh/docs/api#sub-users-delete) | 删除子用户 |
| `GET` | [`https://serp.proxonym.com/v1/search`](https://proxonym.com/zh/docs/api#serp-api-search) | Google 搜索结果（解析后的 JSON） |

### 第一次调用

在控制台中创建 API 密钥，将其导出为环境变量，然后请求账户信息：

**Shell**

```bash
export PROXONYM_API_KEY="your_api_key"

curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

本参考中的示例从 `$PROXONYM_API_KEY` 读取账户 API 密钥，从 `$PROXONYM_SERP_KEY` 读取 SERP API 密钥。

## 身份验证

账户 API 使用 API 密钥对每个请求进行身份验证，密钥以 Bearer 令牌的形式放在 `Authorization` 请求头中发送：

**文本**

```text
Authorization: Bearer <API_KEY>
```

在控制台中创建和撤销密钥。一个密钥对整个账户生效：可以读取用量、下载代理凭据并管理子用户。如果请求中的密钥缺失、格式错误或已被撤销，请求会失败并返回 `401`：

**Shell**

```bash
curl -i https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer wrong_key"
```

**文本**

```text
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}
```

### 妥善保管密钥

- 只从您自己的服务器调用 API。切勿将密钥放进网页、移动应用或公开代码仓库。
- 从环境变量或密钥管理服务中加载密钥，并确保密钥不会出现在日志中。
- 为每个服务使用单独的密钥，这样撤销其中一个时不会影响其他服务。
- API 密钥不是代理凭据。代理连接使用的是您的代理用户名和密码；请参阅[代理身份验证](https://proxonym.com/zh/docs#authentication)。

### 轮换密钥

1. 在控制台中创建新密钥。
2. 将其部署到所有调用 API 的服务。
3. 确认使用新密钥的调用均已成功，然后撤销旧密钥。

请定期轮换密钥；如果密钥可能已泄露，请立即撤销。使用已撤销密钥的请求会失败并返回 `401`。

### SERP API 密钥

SERP API 从 `X-API-Key` 请求头而不是 `Authorization` 读取密钥。详见 [SERP API](https://proxonym.com/zh/docs/api#serp-api)。

## 速率限制

账户 API 每分钟最多接受 60 次请求。每个响应都会告知您当前的额度使用情况：

| 响应头 | 说明 |
| --- | --- |
| `X-RateLimit-Limit` | 每分钟允许的请求数：`60` |
| `X-RateLimit-Remaining` | 当前时间窗口内剩余的请求数 |
| `Retry-After` | 仅出现在 `429` 响应中：发出下一个请求前需要等待的秒数 |

超出限制时，API 会返回 `429`：

**文本**

```text
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 60 requests per minute exceeded. Retry after 18 seconds."
  }
}
```

SERP API 的用量则按套餐的每月请求数计量；请参阅 [SERP API](https://proxonym.com/zh/docs/api#serp-api)。

### 处理 429

等待 `Retry-After` 中指定的秒数后再重试。为避免超出限制：

- 缓存变化缓慢的数据，例如代理列表和白名单。
- 每隔几分钟（而不是几秒）轮询一次用量。最细的统计粒度为一小时。
- 将批量任务（例如创建大量子用户）分散到几分钟内完成。

**Python**

```python
import os
import time

import requests

API = "https://api.proxonym.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"}

def api_get(path, params=None, attempts=5):
    for _ in range(attempts):
        r = requests.get(API + path, headers=HEADERS, params=params, timeout=30)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        time.sleep(int(r.headers.get("Retry-After", "5")))
    raise RuntimeError(f"{path}: still rate limited after {attempts} attempts")

print(api_get("/usage", {"product": "residential", "granularity": "day"}))
```

## 错误

错误使用标准的 HTTP 状态码，并返回一个 JSON 响应体，其中包含稳定、便于程序解析的 `code`，以及便于阅读的 `message`：

**JSON**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}
```

请依据 `code` 编写分支逻辑，切勿依据 `message`：消息文本可能会调整措辞，而错误码保持稳定。

| 状态 | 错误码 | 含义 | 处理方法 |
| --- | --- | --- | --- |
| `400` | `invalid_request` | 请求格式错误：JSON 无效、缺少必填参数，或参数值的类型错误 | 修正请求。重试无济于事 |
| `401` | `invalid_api_key` | API 密钥缺失、格式错误或已被撤销 | 检查请求头和密钥 |
| `403` | `product_not_active`, `quota_exceeded` | 密钥有效，但该产品没有有效套餐，或 SERP 套餐的请求数已用完 | 购买或续费套餐 |
| `404` | `not_found` | 路径、产品、子用户 ID 或白名单 IP 不存在 | 检查路径和 ID |
| `409` | `already_exists` | 该 IP 已在白名单中，或已有其他子用户使用该名称 | 使用现有资源，或改用其他值 |
| `422` | `validation_failed`, `whitelist_full` | 某个值格式正确但不被接受（例如 IP 无效、产品未知或日期范围过长），或者白名单名额已全部占用 | 修正该值，或先从白名单中移除一个 IP |
| `429` | `rate_limited` | 一分钟内的请求超过 60 次 | 等待 `Retry-After` 指定的秒数后重试 |
| `500` | `internal_error` | 服务端出现意外错误 | 使用指数退避重试 |

只有 `429` 和 `500` 值得原样重试。如果 `500` 持续出现，请记下端点、请求时间和完整的错误响应体：如果您使用的是独享数据中心套餐，可通过工单将这些信息发送给我们的团队。

## 账户

读取账户详情、GB 余额和有效套餐。

### 获取账户信息

`GET /account`

返回账户信息、GB 余额以及所有有效套餐。已过期的套餐不包含在内。

#### 参数

无。

#### 请求示例

**Shell**

```bash
curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

**JSON**

```json
{
  "id": "acc_7d3f9k2m",
  "email": "you@company.example",
  "created_at": "2026-03-14T08:21:47Z",
  "credit_usd": 245.5,
  "balances": {
    "residential": {
      "gb_remaining": 37.836,
      "expires_at": "2026-10-12T14:03:51Z",
      "packs": [
        {
          "gb_purchased": 40,
          "gb_remaining": 17.836,
          "purchased_at": "2026-09-12T14:03:51Z",
          "expires_at": "2026-10-12T14:03:51Z"
        },
        {
          "gb_purchased": 20,
          "gb_remaining": 20.0,
          "purchased_at": "2026-08-02T16:40:55Z",
          "expires_at": null
        }
      ]
    },
    "datacenter": {
      "gb_remaining": 687.52,
      "expires_at": "2026-10-18T09:12:40Z"
    }
  },
  "plans": [
    {
      "id": "pl_4k8d2pqm",
      "product": "unlimited",
      "bandwidth_mbps": 200,
      "gateway": "use.unl.proxonym.com",
      "udp": false,
      "started_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-02T10:00:00Z"
    },
    {
      "id": "pl_3n7q1wza",
      "product": "datacenter",
      "ips": 1000,
      "bandwidth_gb": 1000,
      "started_at": "2026-09-18T09:12:40Z",
      "expires_at": "2026-10-18T09:12:40Z"
    },
    {
      "id": "pl_6t2r9exb",
      "product": "isp",
      "ips": 20,
      "started_at": "2026-09-20T15:30:00Z",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "id": "pl_2h5j8kvc",
      "product": "serp",
      "requests_limit": 100000,
      "requests_used": 41827,
      "started_at": "2026-09-08T11:45:19Z",
      "expires_at": "2026-10-08T11:45:19Z"
    }
  ]
}
```

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 账户 ID |
| `email` | string | 账户邮箱地址 |
| `created_at` | string | 账户创建时间 |
| `credit_usd` | number | 以美元计的账户余额，可用于购买套餐。充值金额和奖励额度都会计入其中 |
| `balances` | object | 以产品为键的 GB 余额：`residential`（移动代理与其共用）和 `datacenter`（每月带宽额度）。没有余额的产品不会列出 |
| `balances.{product}.gb_remaining` | number 或 null | 剩余流量（GB）。数据中心代理的不限量档位为 `null` |
| `balances.{product}.expires_at` | string 或 null | 该余额中流量的最早到期时间。如果其中的流量均永不过期，则为 `null` |
| `balances.residential.packs[]` | array | 每个仍有剩余流量的 GB 流量包对应一个条目，包含 `gb_purchased`、`gb_remaining`、`purchased_at` 和 `expires_at`（永不过期的流量包此值为 `null`） |
| `plans[]` | array | 有效套餐。每个套餐都包含 `id`、`product`、`status`（`active`，静态 IP 准备期间则为 `provisioning`）、`started_at` 和 `expires_at` |
| `plans[].bandwidth_mbps`, `gateway`, `udp` | 依次为 integer、string、boolean | 不限流量住宅代理：速度档位、网关服务器，以及 UDP 附加服务是否已开通 |
| `plans[].ips` | integer | ISP、数据中心和独享代理：IP 数量 |
| `plans[].bandwidth_gb` | integer 或 null | 数据中心代理：每月带宽档位（GB），不限量档位为 `null` |
| `plans[].requests_limit`, `requests_used` | integer | SERP API：套餐包含的请求数，以及目前已使用的请求数 |

移动流量从住宅代理余额中扣除，因此没有 `mobile` 余额。住宅代理的 GB 流量包显示在 `balances` 下，而不是 `plans` 下。套餐绝不自动续费：请将 `expires_at` 与当前时间进行比较，以决定何时续费。

#### 示例：余额不足时发出提醒

**Python**

```python
import os

import requests

r = requests.get(
    "https://api.proxonym.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
residential = r.json()["balances"].get("residential")
if residential is None or residential["gb_remaining"] < 5:
    left = residential["gb_remaining"] if residential else 0
    print(f"Residential balance is low: {left:.1f} GB left. Top up before jobs fail with 402.")
```

## 用量

读取您在一段时间内使用的流量或 SERP 请求数。

### 获取用量

`GET /usage`

返回单个产品在某一时间范围内的用量，包括总量和时间序列。

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `product` | string，查询参数 | 是 | `residential`、`mobile`、`unlimited`、`isp`、`datacenter`、`dedicated` 或 `serp` |
| `from` | string，查询参数 | 否 | 时间范围的起点（包含）：UTC 时间的 ISO 8601 日期或时间戳。默认值：`to` 之前 7 天 |
| `to` | string，查询参数 | 否 | 时间范围的终点（不包含）。默认值：当前时间 |
| `granularity` | string，查询参数 | 否 | `day`（默认）或 `hour`。时间桶按 UTC 对齐 |

粒度为 `day` 时，时间范围最长 366 天；粒度为 `hour` 时，最长 31 天。范围超出上限，或 `from` 晚于 `to` 时，将返回 `422`，错误码为 `validation_failed`。移动代理的用量单独统计，但从住宅代理余额中扣除。

#### 请求示例

**Shell**

```bash
curl -G https://api.proxonym.com/v1/usage \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d product=residential \
  -d from=2026-09-24 \
  -d to=2026-10-01 \
  -d granularity=day
```

#### 响应示例

**JSON**

```json
{
  "product": "residential",
  "granularity": "day",
  "from": "2026-09-24T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "total": {
    "traffic_gb": 9.964
  },
  "series": [
    { "timestamp": "2026-09-24T00:00:00Z", "traffic_gb": 1.204 },
    { "timestamp": "2026-09-25T00:00:00Z", "traffic_gb": 1.587 },
    { "timestamp": "2026-09-26T00:00:00Z", "traffic_gb": 0.932 },
    { "timestamp": "2026-09-27T00:00:00Z", "traffic_gb": 1.411 },
    { "timestamp": "2026-09-28T00:00:00Z", "traffic_gb": 1.876 },
    { "timestamp": "2026-09-29T00:00:00Z", "traffic_gb": 1.309 },
    { "timestamp": "2026-09-30T00:00:00Z", "traffic_gb": 1.645 }
  ]
}
```

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `product`, `granularity` | string | 查询所使用的值 |
| `from`, `to` | string | 解析后的时间范围，以 UTC 时间戳表示 |
| `total.traffic_gb` | number | 该范围内的流量（GB）。仅适用于代理产品 |
| `total.requests` | integer | 该范围内的 SERP API 请求数。仅适用于 `serp` |
| `series[]` | array | 每个时间桶一个数据点，按时间顺序排列。没有用量的时间桶返回 `0` |
| `series[].timestamp` | string | 时间桶的起始时间 |
| `series[].traffic_gb` 或 `series[].requests` | number 或 integer | 该时间桶内的用量，单位与 `total` 相同 |

对于 `serp`，总量和数据点统计的是请求数而不是 GB。例如，按小时查询 `?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour` 会返回：

**JSON**

```json
{
  "product": "serp",
  "granularity": "hour",
  "from": "2026-09-30T00:00:00Z",
  "to": "2026-09-30T03:00:00Z",
  "total": {
    "requests": 1854
  },
  "series": [
    { "timestamp": "2026-09-30T00:00:00Z", "requests": 612 },
    { "timestamp": "2026-09-30T01:00:00Z", "requests": 587 },
    { "timestamp": "2026-09-30T02:00:00Z", "requests": 655 }
  ]
}
```

## 代理列表

下载分配给您静态套餐的代理。住宅代理、移动代理和不限流量住宅代理没有列表：它们通过网关连接，详见[端点与端口](https://proxonym.com/zh/docs#endpoints-and-ports)。

### 列出代理

`GET /proxies/{product}`

返回某个产品下所有有效套餐的全部代理，格式为 JSON，或每行一个代理的纯文本。

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `product` | string，路径参数 | 是 | `datacenter`、`isp` 或 `dedicated` |
| `format` | string，查询参数 | 否 | `json`（默认）或 `txt` |
| `country` | string，查询参数 | 否 | 只返回该国家的代理：小写的 ISO 3166-1 alpha-2 代码，例如 `us` |

#### 请求示例

**Shell**

```bash
curl https://api.proxonym.com/v1/proxies/isp \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

此处仅保留三个条目；`count` 为完整数量。

**JSON**

```json
{
  "product": "isp",
  "count": 20,
  "proxies": [
    {
      "ip": "198.51.100.61",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "ip": "198.51.100.62",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "ip": "198.51.100.63",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    }
  ]
}
```

#### 纯文本格式

使用 `format=txt` 时，响应为 `text/plain`，每行一个代理：数据中心代理为 `ip:port`（其中的端口为 HTTP 端口），ISP 和独享代理为 `ip:port:username:password`。

**Shell**

```bash
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
```

**文本**

```text
198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129
```

#### 代理字段

| 字段 | 产品 | 说明 |
| --- | --- | --- |
| `ip` | 全部 | 代理 IP 地址 |
| `port` | ISP、独享 | HTTP 和 SOCKS5 共用的端口 |
| `http_port`, `socks5_port` | 数据中心 | HTTP 端口 `3129`，SOCKS5 端口 `1081` |
| `username`, `password` | ISP、独享 | 该代理的凭据 |
| `country` | 全部 | IP 所在国家，以小写的 ISO 3166-1 alpha-2 代码表示 |
| `location` | ISP | 城市或运营商 IP 池，例如 `New York` 或 `Comcast pool` |
| `expires_at` | ISP、独享 | 该 IP 的到期时间 |

数据中心代理在 JSON 中的条目形如 `{"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}`。如果该产品没有有效套餐，API 会返回 `403`，错误码为 `product_not_active`。对于没有列表的产品（例如 `residential`），则返回 `404`：

**JSON**

```json
{
  "error": {
    "code": "not_found",
    "message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
  }
}
```

## 白名单

白名单允许机器无需凭据即可连接您的共享数据中心代理。每个共享数据中心套餐包含 3 个名额，白名单条目对您的所有数据中心 IP 生效。背景知识：文档中的 [IP 白名单](https://proxonym.com/zh/docs#authentication-ip-whitelist)。

### 列出白名单 IP

`GET /whitelist`

#### 参数

无。

#### 请求示例

**Shell**

```bash
curl https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

**JSON**

```json
{
  "limit": 3,
  "ips": [
    { "ip": "192.0.2.10", "created_at": "2026-09-18T09:20:11Z" },
    { "ip": "192.0.2.57", "created_at": "2026-09-22T17:02:45Z" }
  ]
}
```

`limit` 是您账户的名额数量，`ips` 列出各条目，按添加时间从早到晚排列。

### 添加 IP

`POST /whitelist`

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ip` | string，请求体参数 | 是 | 要连接的机器的公网 IP 地址，例如 `192.0.2.44` |

#### 请求示例

**Shell**

```bash
curl -X POST https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.0.2.44"}'
```

#### 响应示例

状态码 `201`：

**JSON**

```json
{
  "ip": "192.0.2.44",
  "created_at": "2026-10-01T09:30:00Z"
}
```

如果 IP 已在名单中，会返回 `409`，错误码为 `already_exists`；如果地址无效，则返回 `422`，错误码为 `validation_failed`。当所有名额都已占用时，API 返回 `422`：

**JSON**

```json
{
  "error": {
    "code": "whitelist_full",
    "message": "All 3 whitelist slots are in use. Remove an IP before adding another."
  }
}
```

### 移除 IP

`DELETE /whitelist/{ip}`

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ip` | string，路径参数 | 是 | 要移除的白名单 IP |

#### 请求示例

**Shell**

```bash
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

**JSON**

```json
{
  "ip": "192.0.2.10",
  "deleted": true
}
```

此后，来自该 IP 且未携带凭据的请求会失败并返回 `407`。如果 IP 不在名单中，则返回 `404`，错误码为 `not_found`。

## 子用户

子用户是您账户下额外的代理凭据，每个子用户都可以设置可选的流量上限。子用户的流量从您的账户余额中扣除。背景知识：文档中的[子用户](https://proxonym.com/zh/docs#authentication-sub-users)。

### 子用户对象

**JSON**

```json
{
  "id": "su_3k9x2m7q",
  "name": "price-monitor",
  "username": "sub_k3v9q2xd",
  "password": "Qm7vT2xK9pLr4sWz",
  "traffic_limit_gb": 25,
  "traffic_used_gb": 6.412,
  "status": "active",
  "created_at": "2026-09-14T08:05:22Z"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 子用户 ID，用于 API 路径中 |
| `name` | string | 您为子用户设置的标签，在账户内唯一 |
| `username` | string | 系统生成的代理用户名。支持与主用户名相同的选项，例如 `sub_k3v9q2xd-country-us-session-a7k2` |
| `password` | string | 系统生成的代理密码 |
| `traffic_limit_gb` | number 或 null | 最大流量（GB）。`null` 表示除账户余额外不设上限 |
| `traffic_used_gb` | number | 目前已使用的流量（GB） |
| `status` | string | `active` 或 `disabled`。代理会对已停用的子用户返回 `407` |
| `created_at` | string | 子用户的创建时间 |

当 `traffic_used_gb` 达到 `traffic_limit_gb` 时，该子用户的请求会失败并返回 `402`，直到您提高上限为止。

### 列出子用户

`GET /sub-users`

#### 参数

无。

#### 请求示例

**Shell**

```bash
curl https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

**JSON**

```json
{
  "sub_users": [
    {
      "id": "su_3k9x2m7q",
      "name": "price-monitor",
      "username": "sub_k3v9q2xd",
      "password": "Qm7vT2xK9pLr4sWz",
      "traffic_limit_gb": 25,
      "traffic_used_gb": 6.412,
      "status": "active",
      "created_at": "2026-09-14T08:05:22Z"
    },
    {
      "id": "su_8d1f4n6p",
      "name": "qa-team",
      "username": "sub_p8w2n5tf",
      "password": "Hx4bN9cR2vLq7mKs",
      "traffic_limit_gb": null,
      "traffic_used_gb": 1.207,
      "status": "disabled",
      "created_at": "2026-09-20T13:47:09Z"
    }
  ]
}
```

### 创建子用户

`POST /sub-users`

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string，请求体参数 | 是 | 1 到 64 个字符的标签，在账户内唯一 |
| `traffic_limit_gb` | number 或 null，请求体参数 | 否 | 流量上限（GB），必须大于 0。省略或传入 `null` 表示不设上限 |

#### 请求示例

**Shell**

```bash
curl -X POST https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "eu-crawler", "traffic_limit_gb": 10}'
```

#### 响应示例

状态码 `201`，并返回系统生成的用户名和密码：

**JSON**

```json
{
  "id": "su_6v2c8r1t",
  "name": "eu-crawler",
  "username": "sub_t6r1y8bw",
  "password": "Lp3sV8kQ1zXn6wRd",
  "traffic_limit_gb": 10,
  "traffic_used_gb": 0,
  "status": "active",
  "created_at": "2026-10-01T09:30:00Z"
}
```

如果名称已被占用，会返回 `409`，错误码为 `already_exists`。新凭据可立即在网关上使用，并支持常规的用户名选项：

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 \
  -U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
  https://api.ipify.org
```

### 更新子用户

`PATCH /sub-users/{id}`

只需发送要修改的字段。

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string，路径参数 | 是 | 子用户 ID |
| `name` | string，请求体参数 | 否 | 新标签，1 到 64 个字符 |
| `traffic_limit_gb` | number 或 null，请求体参数 | 否 | 新的流量上限（GB），传入 `null` 表示不设上限 |
| `status` | string，请求体参数 | 否 | `active` 或 `disabled` |
| `reset_password` | boolean，请求体参数 | 否 | 传入 `true` 将生成新密码，旧密码立即失效 |

#### 请求示例

提高流量上限并重置密码：

**Shell**

```bash
curl -X PATCH https://api.proxonym.com/v1/sub-users/su_3k9x2m7q \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traffic_limit_gb": 40, "reset_password": true}'
```

#### 响应示例

**JSON**

```json
{
  "id": "su_3k9x2m7q",
  "name": "price-monitor",
  "username": "sub_k3v9q2xd",
  "password": "Wd5nX8qT3vKz6pRm",
  "traffic_limit_gb": 40,
  "traffic_used_gb": 6.412,
  "status": "active",
  "created_at": "2026-09-14T08:05:22Z"
}
```

### 删除子用户

`DELETE /sub-users/{id}`

删除子用户，其凭据立即失效。该子用户已使用的流量仍会保留在您的用量记录中。如果只想暂停子用户，请将其 `status` 设为 `disabled`。

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string，路径参数 | 是 | 子用户 ID |

#### 请求示例

**Shell**

```bash
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### 响应示例

**JSON**

```json
{
  "id": "su_8d1f4n6p",
  "deleted": true
}
```

如果 ID 不存在，则返回 `404`，错误码为 `not_found`。

## SERP API

[Google SERP API](https://proxonym.com/zh/serp-api)（谷歌搜索结果 API）可针对任意国家或城市、桌面端或移动端，以解析后的 JSON 格式返回 Google 搜索结果。每次调用返回一页结果，并计为套餐中的一次请求。

### 搜索

`GET https://serp.proxonym.com/v1/search`

在 `X-API-Key` 请求头中发送您从控制台获取的 SERP API 密钥。错误格式与账户 API 相同：密钥缺失或无效时返回 `401`，错误码为 `invalid_api_key`；没有有效的 SERP 套餐时，API 返回 `403`，错误码为 `product_not_active`；套餐的请求数用完后，返回 `403`，错误码为 `quota_exceeded`。

#### 参数

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 是 | 搜索查询词，需经过 URL 编码 |
| `gl` | string | 否 | 搜索结果所属的国家，以小写的 ISO 3166-1 alpha-2 代码表示。默认值为 `us` |
| `hl` | string | 否 | 界面语言代码，例如 `en` 或 `de`。默认值为 `en` |
| `location` | string | 否 | 城市级位置，格式为 `City,Region`，例如 `Chicago,Illinois`。所填地点须位于 `gl` 指定的国家内 |
| `device` | string | 否 | `desktop`（默认）或 `mobile` |
| `page` | integer | 否 | 结果页码，从 `1`（默认）开始。每一页都是一次单独的请求 |

#### 请求示例

**Shell**

```bash
curl -G https://serp.proxonym.com/v1/search \
  -H "X-API-Key: $PROXONYM_SERP_KEY" \
  --data-urlencode "q=running shoes" \
  -d gl=us \
  -d hl=en \
  --data-urlencode "location=Chicago,Illinois" \
  -d device=desktop \
  -d page=1
```

使用 Python 发送同样的请求：

**Python**

```python
import os

import requests

params = {
    "q": "running shoes",
    "gl": "us",
    "hl": "en",
    "location": "Chicago,Illinois",
    "device": "desktop",
    "page": 1,
}
r = requests.get(
    "https://serp.proxonym.com/v1/search",
    headers={"X-API-Key": os.environ["PROXONYM_SERP_KEY"]},
    params=params,
    timeout=60,
)
r.raise_for_status()
for result in r.json()["organic_results"]:
    print(result["position"], result["title"], result["link"])
```

#### 响应示例

以下内容已做删减：

**JSON**

```json
{
  "search_parameters": {
    "q": "running shoes",
    "gl": "us",
    "hl": "en",
    "location": "Chicago,Illinois",
    "device": "desktop",
    "page": 1
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Running Shoes for Men and Women | Stride Supply",
      "link": "https://www.stridesupply.example/running-shoes",
      "snippet": "Shop road and trail running shoes in every size. Compare cushioning, drop and weight across 40 models."
    },
    {
      "position": 2,
      "title": "How to Choose Running Shoes: A Buyer's Guide",
      "link": "https://www.runnersdesk.example/guides/choosing-running-shoes",
      "snippet": "Gait, arch type and weekly mileage matter more than brand. Here is how to narrow the field."
    },
    {
      "position": 3,
      "title": "Running Shoes in Chicago, IL | Lakeshore Run Co.",
      "link": "https://www.lakeshorerun.example/",
      "snippet": "Gait analysis and fittings at our Lincoln Park store, open 7 days a week."
    }
  ],
  "ads": [
    {
      "position": 1,
      "title": "Running Shoes Sale | Up to 40% Off",
      "link": "https://www.shoeoutlet.example/running",
      "snippet": "Last season's models in stock. Ships in 1 business day."
    }
  ],
  "people_also_ask": [
    {
      "question": "How often should you replace running shoes?",
      "snippet": "Many runners replace their shoes every 300 to 500 miles.",
      "link": "https://www.runnersdesk.example/guides/shoe-lifespan"
    }
  ],
  "related_searches": [
    { "query": "running shoes near me" },
    { "query": "trail running shoes" },
    { "query": "running shoes for flat feet" }
  ],
  "local_results": [
    {
      "position": 1,
      "title": "Lakeshore Run Co.",
      "address": "2312 N Lincoln Ave, Chicago, IL",
      "phone": "(312) 555-0142"
    },
    {
      "position": 2,
      "title": "Windy City Running",
      "address": "845 W Randolph St, Chicago, IL",
      "phone": "(312) 555-0187"
    }
  ]
}
```

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `search_parameters` | object | 本次搜索的参数，已填入默认值 |
| `organic_results[]` | array | 按页面顺序排列的自然搜索结果 |
| `organic_results[].position` | integer | 在页面上的排名，从 1 开始 |
| `organic_results[].title` | string | 结果标题 |
| `organic_results[].link` | string | 结果 URL |
| `organic_results[].snippet` | string | 标题下方显示的文字 |
| `ads[]` | array | 付费结果（广告），包含 `position`、`title`、`link` 和 `snippet` |
| `people_also_ask[]` | array | “相关问题”（People also ask）模块中的问题，包含 `question`、`snippet` 和 `link` |
| `related_searches[]` | array | 相关搜索，每项包含 `query` |
| `local_results[]` | array | 本地商家列表（Local Pack）结果，包含 `position`、`title`、`address` 和 `phone` |

页面上未出现的模块会以空数组返回。如需长期跟踪排名，请参阅[搜索排名跟踪使用场景](https://proxonym.com/zh/use-cases/serp-tracking)，以及我们的指南：[如何抓取 Google 搜索结果](https://proxonym.com/zh/blog/scrape-google-search-results)。

- [文档](https://proxonym.com/zh/docs): 网关、会话、定位、错误
- [集成](https://proxonym.com/zh/integrations): Puppeteer、Playwright、Scrapy 等
