开发者文档

OpenAPI 接口

以程序管理密钥、账户和调用用量。

本页介绍管理类 OpenAPI 的兼容接入约定，面向需要自动化管理的平台用户。模型对话、生成内容等请求，请按快速开始配置模型接口。

接入前确认管理 API 已开通

管理 OpenAPI 需要独立权限和管理密钥。以下为兼容接口说明，不代表所有账户已开通全部端点。如果个人中心没有 OpenAPI 密钥入口，请先联系支持确认可用接口、认证方式和限额；不要使用登录凭证代替管理密钥。

认证与基础地址

项目	说明
管理接口 Base URL	`https://oment.cc/api/v1`
认证请求头	`x-api-key: <你的 OpenAPI 管理密钥>`
请求体格式	`Content-Type: application/json`
模型调用 Base URL	`https://oment.cc/v1`，与本页管理接口不同

只有在控制台提供 OpenAPI 密钥功能且账户已开通时，才可使用上述管理密钥认证。管理密钥具备账户管理能力，请仅存放在可信服务端。

export OMENT_OPENAPI_KEY='替换为你的管理密钥'

curl 'https://oment.cc/api/v1/keys?page=1&page_size=20' \
  -H "x-api-key: $OMENT_OPENAPI_KEY"

响应约定

兼容接口的成功响应使用 code、message 与 data 包装。示例中的数字和文字仅展示结构。

{
  "code": 0,
  "message": "成功",
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "page_size": 20,
    "pages": 0
  }
}

列表接口通常在 data.items 返回当前页记录；请结合 total 和 pages 处理分页。非列表接口的 data 为对应业务对象。实际字段以已开通版本的响应为准。

列出与查看 API Key

GET/keys密钥列表

查询参数	类型	用途
`page / page_size`	integer	页码与每页条数
`search`	string	搜索密钥名称；避免在 URL 中传入完整密钥
`status`	string	`active`、`inactive`、`quota_exhausted` 或 `expired`
`group_id`	integer	按分组筛选

GET/keys/:id单个密钥详情

:id 为密钥记录 ID，不是密钥字符串。返回对象可能包含 id、key、name、group_id、status、quota、quota_used、expires_at、last_used_at、last_used_ip、created_at 和 updated_at。包含密钥的响应不得写入公开日志。

创建 API Key

POST/keys创建密钥

请求字段	类型	说明
`name`	string · 必填	便于识别的名称
`group_id`	integer	通过可用分组接口获取；不要直接照搬示例 ID
`quota`	number	密钥总额度，单位以账户展示为准；兼容约定中 0 表示不单独限额
`expires_in_days`	integer	有效天数；省略时的过期策略以服务端为准
`ip_whitelist`	string[]	允许访问的 IP 或 CIDR
`rate_limit_5h` `rate_limit_1d` `rate_limit_7d`	number	对应时间窗口内的消费上限；0 表示不单独设置该上限

# 先替换为账户实际可用的分组 ID，并确认额度单位。
curl -X POST 'https://oment.cc/api/v1/keys' \
  -H "x-api-key: $OMENT_OPENAPI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: project-demo-create-001' \
  -d '{"name":"project-demo","group_id":1,"quota":50}'

若服务端支持 Idempotency-Key，同一次业务操作重试时应沿用相同的幂等键和请求体；新建另一枚密钥时使用新的幂等键。请先确认幂等支持情况，避免网络重试重复创建。

修改与删除 API Key

PUT/keys/:id修改指定字段

兼容可修改字段包括 name、group_id、status、quota、expires_at、ip_whitelist 和消费窗口限制。仅发送需要变更的字段，状态使用 active 或 inactive，过期时间使用 ISO 8601 格式。

额度是累计上限，不是本次充值金额

将 quota 设置为 150，表示总上限变为 150，而不是增加 150。reset_quota: true 会重置已用额度统计（若接口支持）；不要在常规更新中误传该字段。空的 ip_whitelist 数组表示清空白名单。

curl -X PUT 'https://oment.cc/api/v1/keys/123' \
  -H "x-api-key: $OMENT_OPENAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"quota":150}'

DELETE/keys/:id删除密钥

删除前确认业务已切换到新密钥。删除操作会使依赖旧密钥的调用失败；仅需临时阻止调用时，优先将状态改为 inactive。

账户与分组

方法	路径	用途
GET	`/user/profile`	读取账户信息及可用余额等字段
GET	`/groups/available`	读取账户可使用的分组
GET	`/groups/rates`	查询分组倍率信息

API Key 的额度限制与账户余额并不等同。具体扣费来源、订阅额度和倍率，按所属分组及订单规则执行。

用量查询

方法	路径	用途
GET	`/usage`	分页查询调用明细
GET	`/usage/stats`	查询用量汇总
GET	`/usage/:id`	查看单条调用记录
GET	`/user/api-keys/:id/usage/daily`	按日查看指定密钥用量，参数 `days`
POST	`/usage/dashboard/api-keys-usage`	批量查询，JSON 请求体 `{"api_key_ids":[1,2]}`
GET	`/usage/dashboard/stats`	统计概览
GET	`/usage/dashboard/trend`	用量趋势
GET	`/usage/dashboard/models`	按模型统计
GET	`/usage/dashboard/snapshot-v2`	统计快照

/usage 与 /usage/stats 的兼容筛选参数包括 api_key_id、start_date、end_date 和 model。日期使用 YYYY-MM-DD；列表分页使用 page、page_size。批量条数和日期范围上限以实际接口限制为准。

限流与重试

调用频率与批量上限取决于账户权限及接口类型。收到 429 时，若响应含有 Retry-After，按该字段指示等待；否则采用带随机抖动的退避策略并设置最大重试次数。写入接口重试前应先查询操作结果，并确认幂等机制可用。

错误处理

HTTP 状态	兼容错误码示例	建议处理
400	参数校验错误，详见 `reason`	核对字段类型与取值
401	`INVALID_OPEN_API_KEY` `USER_INACTIVE`	检查管理密钥和账号状态
403	`USER_OPEN_API_DISABLED` `OPEN_API_IP_FORBIDDEN` `OPEN_API_ROUTE_FORBIDDEN`	检查权限、IP 白名单与端点开放情况
404	资源或接口不存在	核对路径、ID 和接口版本
409	`IDEMPOTENCY_KEY_CONFLICT`	同一幂等键不要对应不同请求体
429	`RATE_LIMITED`	降低请求频率，按提示重试
500	`INTERNAL_ERROR`	保留请求 ID，联系支持

请同时检查 HTTP 状态与业务响应。错误信息可能出现在 code、reason 或 message 中，避免只依赖一种固定字段。排障时记录发生时间、路径、状态码、请求 ID 和脱敏后的响应，不记录完整管理密钥。