# 创建静态 IP 分组

创建本人单层分组，名称 trim 后 1–50 个字符，同账户重名返回 400 / 10700。不支持删除、改名或多级分组。

创建本人单层分组，名称 trim 后 1–50 个字符，同账户重名返回 400 / 10700。不支持删除、改名或多级分组。

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

## 接口与认证

`POST /openapi/v1/static/groups`

使用 HTTPS 和账户 API 令牌。响应包含 Cache-Control: no-store 和 X-Request-Id。

## 请求参数

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| api_key | string | 是 | Query · 唯一非空 | 账户 API 令牌，在受控服务端保存；示例使用占位符。 |

### 请求示例 · application/json

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| name | string | 是 | 最短 1 | 名称去除首尾空白后 1–50 个字符，账户内不得重复；长度以 Unicode 字符计。 |

## 请求示例

```bash
curl --request POST \
  "https://api.zzhttp.com/openapi/v1/static/groups?api_key=${STATIC_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Work"}'
```

请求示例：

```json
{
  "name": "Work"
}
```

## 成功响应

响应不包含代理密码，凭据仅由专用接口返回。

HTTP 200 · 成功响应：成功

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| code | integer | 是 | 固定 200 | 统一数字业务码：HTTP 与业务码成功均为 200；异步受理不代表交付完成。 |
| message | string | 是 | — | 服务端结果说明。 |
| requestId | string | 是 | — | 本次请求的追踪 ID，用于排障，不是业务幂等编号。 |
| data | object | 是 | — | 本接口业务数据。 |
| data.groupId | integer | 是 | 最小 1 | 分组 ID。 |
| data.name | string | 是 | — | 自定义分组名称。 |
| data.createdAt | string | 是 | 格式 date-time | 创建时间，RFC3339。 |
| data.updatedAt | string | 是 | 格式 date-time | 最后更新时间，RFC3339。 |

```json
{
  "code": 200,
  "message": "成功",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "groupId": 12,
    "name": "Work",
    "createdAt": "2026-10-06T08:00:00Z",
    "updatedAt": "2026-10-06T08:00:00Z"
  }
}
```

## 错误与重试

读取请求遇到 429 按 Retry-After 等待；500/503 可有限重试。分组创建结果不明时先查询分组列表；移动同一目标可安全重试。

错误码、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);}