# 批量添加动态 IP 白名单

使用账户令牌将最多 100 个海外公网 IPv4 添加到账户白名单。

## 请求

`POST /openapi/v1/proxy/whitelist/add` 使用[账户 API 令牌](/developers/authentication/api-token)认证，`api_key` 作为唯一、非空的查询参数。JSON 请求体含 1–100 个 `items`，每项为 `ip` 和可选 `remark`（最多 255 字符）：

```json
{"items":[{"ip":"203.0.113.10","remark":"office"}]}
```

示例 IP 是文档保留地址，仅说明字段结构；实际提交必须是已获授权的海外公网 IPv4。IPv6、私网、回环、CGNAT、文档、组播及其他保留地址会失败。请求拒绝未知字段和尾随 JSON；新增前校验账户状态与实名认证。

## 返回与错误

每项独立提交。同账户重复、他人占用或正在释放仅使对应项失败，不回滚其他成功项。全部成功时顶层 `code=200`；任一项失败时顶层 `code=10431`，`data` 返回 `success_count`、`failed_count`、`failed_items[]`，失败项含 `ip`、`code`、`reason`。响应不列出成功 IP。

超过 100 项或请求外层结构非法时整批不处理。添加每个令牌最多 10 次/分钟；HTTP `429` 按 `Retry-After` 等待。请求中断或部分失败后先[查询白名单](/developers/api/ip-whitelist-list)，只重试尚未成功的 IP；不要盲目重放全批次。

html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}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 .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);}