管理 API

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 个有效的管理密钥。

读写密钥可以创建会消耗你余额的 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 的轮换和撤销仍是独立操作。

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"
  }'

{ "id": "3f2c…", "key": "or-live-…", "expiresAt": null }

budget 单位为 micro-USD（50,000,000 即 50 美元）。defaultTags 遵循标签，allowedModels 遵循模型限制。请立即保存返回的 key，之后不会再显示。

读取用量

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 查询模型列表。创建和轮换的响应包含完整 key，仅返回一次。本文响应为字段示例，ID 与前缀为占位值，不是实际凭据。创建 Key 返回 201；其他成功操作返回 200。

请求字段	规则
`name`	创建时必填，1–60 字符。
`memberName`、`memberEmail`	可选持有人备注；名称最多 80 字符，邮箱须有效。null 或空字符串清除备注。
`expiresAt`	未来的 Unix 毫秒时间戳；null 表示不过期。
`defaultTags`	标签对象，按标签的数量及字符规则校验。
`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 与预算

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。预算响应字段示例：

{
  "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，不是完整密钥。

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

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 }，历史用量保留。

请求记录与分页

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"

{ "requests": [], "total": 0, "next": null, "limit": 50 }

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

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
`GET /v1/manage/keys/budgets`	列出 Key 预算
`POST /v1/manage/keys`	创建 API Key
`PATCH /v1/manage/keys/{id}`	修改 API Key
`PATCH /v1/manage/keys/{id}/budget`	修改 Key 预算
`POST /v1/manage/keys/{id}/rotate`	轮换 API Key
`DELETE /v1/manage/keys/{id}`	撤销 API Key
`GET /v1/manage/usage`	读取用量汇总
`GET /v1/manage/requests`	列出请求记录

管理密钥帮助

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

V1 文档

快速开始

用户手册

概览

LLM

图片

视频

通用

管理密钥

接口

为客户创建 Key

读取用量

调用顺序与字段

列出 Key 与预算

修改 Key 与预算

轮换与撤销 Key

请求记录与分页

错误

API 调用参考

管理密钥帮助

​管理密钥

​接口

​为客户创建 Key

​读取用量

​调用顺序与字段

​列出 Key 与预算

​修改 Key 与预算

​轮换与撤销 Key

​请求记录与分页

​错误

​API 调用参考

​管理密钥帮助

管理密钥

接口

为客户创建 Key

读取用量

调用顺序与字段

列出 Key 与预算

修改 Key 与预算

轮换与撤销 Key

请求记录与分页

错误

API 调用参考

管理密钥帮助