> ## Documentation Index
> Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 API

> 用管理密钥从脚本批量创建 API Key、拉取用量；管理密钥不能调用模型。

Management API 让脚本完成你在 **API Keys** 与**用量日志**页面上的操作：为你的客户或服务创建 Key、设置模型限制与预算、轮换或撤销 Key，以及读取用量。地址为 `https://api.omnirelay.ai/v1/manage/`。

## 管理密钥

Management API 只接受**管理密钥**（`or-mgmt-…`），不接受 API Key。两者刻意分开：能调用模型的 Key 永远不能创建 Key，管理密钥也永远不能调用模型。

| 请求发往 | 使用 API Key | 使用管理密钥 |
| - | - | - |
| `/v1/chat/completions`、`/v1/models` | 正常 | `401 unauthorized` |
| `/v1/manage/*` | `401 management_key_required` | 在权限范围内正常 |

开通完成并核验通过后，在 **API Keys** 页的**管理密钥**中创建；未开通时创建入口禁用。密钥只显示**一次**，服务端只保存其哈希。每个密钥有一个权限范围：

| 范围 | 允许 |
| - | - |
| `read` | 列出 API Key 及其预算，读取用量和请求记录 |
| `write` | `read` 的全部权限，另可创建、修改、轮换和撤销 API Key，并设置 Key 预算 |

只读密钥尝试写操作会返回 `403 insufficient_scope`。管理密钥**以你的身份**操作：它修改的是你的 API Key；用量读取范围按你的账户权限决定，它做的每项修改都会在审计日志中记为 `you@example.com via management key <名称>`。撤销密钥、停用或删除你的账户后，它在下一次调用时即失效。每人最多同时持有 10 个有效的管理密钥。

> [!WARNING]
>
> 读写密钥可以创建会消耗你余额的 API Key。管理密钥只能放在服务端，绝不能放进浏览器；只需读取时请使用 `read` 密钥。

## 接口

每个请求都要带 `Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY`，请求体为 JSON。每个管理密钥每分钟最多 120 次请求。

| 方法与路径 | 范围 | 作用 |
| - | - | - |
| `GET /v1/manage/keys` | read | 列出你的 API Key：名称、前缀、状态、持有人、到期时间、`default_tags`、`allowed_models` |
| `GET /v1/manage/keys/budgets` | read | 每个 Key 的预算、剩余额度、重置周期与已用金额，单位 micro-USD |
| `POST /v1/manage/keys` | write | 创建 API Key，返回的 `key` **只出现一次** |
| `PATCH /v1/manage/keys/{id}` | write | 修改 `name`、`memberName`、`memberEmail`、`expiresAt`、`defaultTags` 或 `allowedModels` |
| `PATCH /v1/manage/keys/{id}/budget` | write | 设置 `budget`、`remaining` 或 `resetPeriod` |
| `POST /v1/manage/keys/{id}/rotate` | write | 更换密钥，保留 Key 的 id 与全部设置。新 `key` 只返回一次 |
| `DELETE /v1/manage/keys/{id}` | write | 撤销该 Key，从下一次调用起失效 |
| `GET /v1/manage/usage` | read | 总计、时间序列与分组汇总，筛选条件与**用量日志**页面一致 |
| `GET /v1/manage/requests` | read | 分页的请求记录，按时间倒序 |

`/v1/manage/` 下的其他路径一律返回 `404`。管理密钥无法触及账单、账户或管理后台的接口。

## 为客户创建 Key

密钥所有者的工作空间必须处于已核验的服务就绪状态，否则 `POST /v1/manage/keys` 返回 `403 activation_required`，不会创建 Key。请在**总览 → 真实模型服务**检查状态并完成开通后再试。已有 Key 的轮换和撤销仍是独立操作。

```bash theme={null}
curl https://api.omnirelay.ai/v1/manage/keys \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme production",
    "defaultTags": {"client": "acme"},
    "allowedModels": ["gpt-6-luna"],
    "budget": 50000000,
    "resetPeriod": "monthly"
  }'
```

```json theme={null}
{ "id": "3f2c…", "key": "or-live-…", "expiresAt": null }
```

`budget` 单位为 micro-USD（50,000,000 即 50 美元）。`defaultTags` 遵循[标签](https://omnirelay.ai/docs/cn/general/tags.md)，`allowedModels` 遵循[模型限制](https://omnirelay.ai/docs/cn/overview/authentication.md#限定-key-可调用的模型)。请立即保存返回的 `key`，之后不会再显示。

## 读取用量

```bash theme={null}
curl "https://api.omnirelay.ai/v1/manage/usage?range=30d&step=day&tag_key=client&tag_value=acme" \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY"
```

| 参数 | 取值 |
| - | - |
| `range` | `24h`、`7d`、`30d` 或 `90d`，默认 `7d` |
| `step` | `hour`（仅限 `24h` 或 `7d`）或 `day`，默认 `day` |
| `model`、`provider`、`key`、`status` | 限定为某个模型 ID、模型服务方、API Key ID，或 `ok` / `error` |
| `tag_key`、`tag_value` | 只保留带某个标签的调用，或只保留该标签的某个值 |
| `tag_group` | 额外返回 `groups.tag`：按某个标签 key 拆分的汇总，未带该标签的调用单独成行 |

响应包含 `totals`、`previous`（上一周期，用于对比）、`series`，以及按模型、模型服务方、Key、状态的 `groups`。金额单位为 micro-USD，时间为 UTC。

`GET /v1/manage/requests` 支持同样的筛选，另有 `limit`（最多 1,000）和 `before`（上一页返回的 `next` 游标）。

## 调用顺序与字段

先在控制台创建管理密钥，再使用以下接口管理自己的 API Key。`read` 和 `write` 是管理密钥权限；它们不会自动开通模型。推理模型以自己的 Key 查询[模型列表](https://omnirelay.ai/docs/cn/llms/listing-models.md)。

创建和轮换的响应包含完整 `key`，仅返回一次。本文响应为字段示例，ID 与前缀为占位值，不是实际凭据。创建 Key 返回 **201**；其他成功操作返回 **200**。

| 请求字段 | 规则 |
| - | - |
| `name` | 创建时必填，1–60 字符。 |
| `memberName`、`memberEmail` | 可选持有人备注；名称最多 80 字符，邮箱须有效。null 或空字符串清除备注。 |
| `expiresAt` | 未来的 Unix 毫秒时间戳；null 表示不过期。 |
| `defaultTags` | 标签对象，按[标签](https://omnirelay.ai/docs/cn/general/tags.md)的数量及字符规则校验。 |
| `allowedModels` | 1–50 条精确模型 ID 或 `provider/*` 规则；null 表示允许全部已开通模型，空数组无效。白名单不授予新模型权限。 |
| `budget`、`remaining` | 整数微美元，范围 0–1,000,000,000,000；50,000,000 即 50 美元。未设置预算时均为 null。 |
| `resetPeriod` | `none`、`daily`、`weekly`、`monthly`，默认 none。按 UTC 日历重置，每周从周一开始。 |

PATCH 只修改提供的字段。修改 `budget` 不补充已有的 `remaining`，补充时显式设置 `remaining`；周期预算必须大于零。清除预算时一起传 `budget: null`、`remaining: null` 和 `resetPeriod: "none"`。到期时间使用 Key 修改接口，不能传给预算接口。

每人最多 20 个有效 API Key。轮换保留 ID、到期时间、白名单、标签及费用计数，旧密钥立即失效；每人每小时最多轮换 10 次。创建和轮换没有幂等重试约定，网络结果不明确时先查列表并核实状态。

## 列出 Key 与预算

```bash theme={null}
curl https://api.omnirelay.ai/v1/manage/keys \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY"

curl https://api.omnirelay.ai/v1/manage/keys/budgets \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY"
```

Key 列表返回 `{ "keys": [...] }`，包括已撤销项，不包含完整密钥。注意列表字段采用 `expires_at`、`default_tags` 和 `allowed_models`，写入参数采用 `expiresAt`、`defaultTags` 和 `allowedModels`。

预算响应字段示例：

```json theme={null}
{
  "keys": [{
    "id": "example-key-id", "name": "Acme production", "prefix": "or-live-…",
    "status": "active", "spent": 0, "budget": 50000000, "remaining": 50000000,
    "resetPeriod": "monthly", "nextResetAt": 1793491200000,
    "expiresAt": null, "expired": false
  }],
  "budget_unit": "micro-USD", "timezone": "UTC"
}
```

## 修改 Key 与预算

将 `$KEY_ID` 替换为列表或创建响应的 `id`，不是完整密钥。

```bash theme={null}
curl -X PATCH "https://api.omnirelay.ai/v1/manage/keys/$KEY_ID" \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme production","defaultTags":{"client":"acme"},"allowedModels":["gpt-6-luna"]}'

curl -X PATCH "https://api.omnirelay.ai/v1/manage/keys/$KEY_ID/budget" \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budget":50000000,"remaining":50000000,"resetPeriod":"monthly"}'
```

两者成功均返回 `{ "ok": true }`。发生 `409 key_changed` 时，先读取当前预算再决定是否重新修改。

## 轮换与撤销 Key

```bash theme={null}
curl -X POST "https://api.omnirelay.ai/v1/manage/keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X DELETE "https://api.omnirelay.ai/v1/manage/keys/$KEY_ID" \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY"
```

轮换返回 `{ "id": "example-key-id", "key": "or-live-…" }`；立即安全保存新密钥并更新服务配置。撤销返回 `{ "ok": true }`，历史用量保留。

## 请求记录与分页

```bash theme={null}
curl -G https://api.omnirelay.ai/v1/manage/requests \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  --data-urlencode "range=30d" \
  --data-urlencode "limit=50" \
  --data-urlencode "status=error"
```

```json theme={null}
{ "requests": [], "total": 0, "next": null, "limit": 50 }
```

请求按 `created`、`id` 倒序返回，包含失败记录。`limit` 默认 50，范围 1–1,000；`id` 可精确查询 Request ID，并接受带 `chatcmpl-` 前缀的 ID。`next` 非 null 时，保持同样的筛选条件，将其原样传给 `before`：

```bash theme={null}
curl -G https://api.omnirelay.ai/v1/manage/requests \
  -H "Authorization: Bearer $OMNIRELAY_MANAGEMENT_KEY" \
  --data-urlencode "range=30d" \
  --data-urlencode "limit=50" \
  --data-urlencode "status=error" \
  --data-urlencode "before=$NEXT_CURSOR"
```

不要自行拆分或修改游标；`next: null` 表示没有下一页。记录中的 `status` 为 HTTP 状态数值，`tags` 是 JSON 编码的字符串或 null，不是标签对象。`cost` 为已结算费用，不能用它判断是否仍有未结算预留。

用量响应的 `scope` 表示读取范围：所有者具备 `members.read` 权限时可读工作空间统计，否则只能读本人记录；`member` 筛选也需要此权限。Key 列表和修改始终仅限管理密钥所有者的 Key。用量与请求读取另受每个所有者每分钟共 240 次监控读取限制。

## 错误

| 状态码 | 错误码 | 含义 |
| - | - | - |
| 401 | `unauthorized` | 管理密钥缺失、未知或已撤销，或其所有者已被停用 |
| 401 | `management_key_required` | 向 Management API 发送了 API Key |
| 403 | `insufficient_scope` | `read` 密钥尝试写操作 |
| 404 | `not_found` | 路径不存在，或你名下没有该 Key |
| 429 | `rate_limited` | 当前一分钟内超过 120 次请求 |

修改 Key 时的校验错误（`invalid_input`、`invalid_tags`、`invalid_model_rules`、`invalid_key_policy`、`invalid_key_expiry`）与控制台一致。

## API 调用参考

| 方法与路径 | 文档 |
| - | - |
| `GET /v1/manage/keys` | [列出 API Key](https://omnirelay.ai/docs/cn/api-reference/management/list-api-keys.md) |
| `GET /v1/manage/keys/budgets` | [列出 Key 预算](https://omnirelay.ai/docs/cn/api-reference/management/list-key-budgets.md) |
| `POST /v1/manage/keys` | [创建 API Key](https://omnirelay.ai/docs/cn/api-reference/management/create-api-key.md) |
| `PATCH /v1/manage/keys/{id}` | [修改 API Key](https://omnirelay.ai/docs/cn/api-reference/management/update-api-key.md) |
| `PATCH /v1/manage/keys/{id}/budget` | [修改 Key 预算](https://omnirelay.ai/docs/cn/api-reference/management/update-key-budget.md) |
| `POST /v1/manage/keys/{id}/rotate` | [轮换 API Key](https://omnirelay.ai/docs/cn/api-reference/management/rotate-api-key.md) |
| `DELETE /v1/manage/keys/{id}` | [撤销 API Key](https://omnirelay.ai/docs/cn/api-reference/management/revoke-api-key.md) |
| `GET /v1/manage/usage` | [读取用量汇总](https://omnirelay.ai/docs/cn/api-reference/management/read-usage-summary.md) |
| `GET /v1/manage/requests` | [列出请求记录](https://omnirelay.ai/docs/cn/api-reference/management/list-request-records.md) |

## 管理密钥帮助

在**控制台 → API Keys**，点击**管理密钥**标题旁的问号图标，即可打开当前主题帮助。帮助在当前页面展示，API 文档链接保留在说明文字中。管理密钥不授予模型访问权限，推理 Key 也不能调用 Management API。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.