消费者与 API Key

消费者是调用模型网关的逻辑主体。一个消费者可绑定一个套餐并持有多个 API Key；同一消费者下的 API Key 共享该消费者的套餐、路由授权和限流配额。

本页接口用于管理消费者和 API Key，调用平台网关调用时，使用x-keystone-token: 认证。签发的 API Key 用于调用模型网关，请求头格式为 Authorization: bearer <API_KEY>，不能替代本页管理接口所需的 Keystone Token。

创建消费者时同时签发首个 API Key。API Key 明文仅在签发响应中返回一次，后续查询只返回脱敏值 masked，请在收到响应后立即安全保存。

消费者可以暂不绑定套餐，但未绑定套餐时不能通过套餐获得任何模型网关路由访问权限。API Key 能否使用还取决于消费者状态、API Key 状态及有效期、套餐状态和套餐授权路由；禁用消费者会使其下所有 API Key 停止使用。

实时配额接口的 ids 为逗号分隔的 1 至 200 个消费者 ID，重复 ID 会被忽略，响应仅包含调用者可见的消费者。已绑定套餐但无法读取实时配额时仍返回 200，并以 available=false 表示配额信息暂不可用；未绑定套餐时 available=true，但不返回 requests 和 tokens 配额维度。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/consumers	查询 API 消费者
POST	/consumers	创建消费者并签发首个 API Key
GET	/consumers/quota	批量查询消费者实时配额
GET	/consumers/{id}	获取消费者详情
PATCH	/consumers/{id}	更新消费者
DELETE	/consumers/{id}	删除消费者
POST	/consumers/{id}/apikeys	签发新的 API Key
PATCH	/consumers/{id}/apikeys/{keyId}	启用或禁用 API Key
DELETE	/consumers/{id}/apikeys/{keyId}	删除 API Key

查询 API 消费者

功能介绍

查询 API 消费者。

访问要求：有效 Token 和消费者读权限。普通调用方只能查询当前项目中自己创建的消费者；具有消费者所有者管理权限时可查询项目内其他用户的消费者。全局读权限允许跨项目查询，但仍受所有者范围限制，除非同时具有消费者所有者管理权限。

URI

GET /api/v1/consumers

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；建议显式传入，例如 20；省略或传 0 时返回全部匹配项，响应中的 page_size 为 0

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	消费者列表，字段与消费者详情一致，但不包含 keys
total	integer	匹配总数
page	integer	页码，从 1 开始
page_size	integer	每页数量

请求示例

GET https://{endpoint}/api/v1/consumers?page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "con-a1b2c3d4e5f6",
      "name": "示例消费者",
      "description": "",
      "status": "active",
      "projectId": "projectId-example",
      "ownerUserId": "ownerUserId-example",
      "spec": {
        "planId": "plan-id",
        "planKey": "pk-a1b2c3d4e5f6",
        "planName": "标准套餐",
        "status": "active",
        "keyCount": 1
      },
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
500	internal_error	查询消费者列表失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

创建消费者并签发首个 API Key

功能介绍

创建消费者并签发首个 API Key。

访问要求：有效 Token 和当前项目的消费者写权限。绑定本项目套餐时需具有套餐使用权限；绑定其他项目共享的套餐时，还需具有共享套餐使用权限。

URI

POST /api/v1/consumers

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	消费者名称
description	string	否	描述
planId	string	否	绑定的套餐 ID，可暂不绑定；未绑定时不具备套餐授权的路由访问能力。
labels	map<string, string>	否	标签键值对

响应消息

参数	参数类型	描述
consumer	object	新创建的消费者对象，字段与消费者详情一致，但不包含 keys
apiKey	object	同时签发的首个 API Key；明文 key 仅在本次响应中返回
apiKey.id	string	API Key 资源 ID，用于启用、禁用和删除 API Key
apiKey.keyId	string	API Key 标识，可用于用量记录关联；不能代替 apiKey.id 作为管理接口路径参数
apiKey.key	string	API Key 明文，仅本次签发响应返回
apiKey.masked	string	API Key 脱敏值
apiKey.expiresAt	string(date-time) / null	到期时间，RFC3339；未设置有效期时省略

请求示例

POST https://{endpoint}/api/v1/consumers
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "示例消费者",
  "planId": "plan-id"
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "consumer": {
    "id": "con-a1b2c3d4e5f6",
    "name": "示例消费者",
    "description": "",
    "status": "active",
    "projectId": "projectId-example",
    "ownerUserId": "ownerUserId-example",
    "spec": {
      "planId": "plan-id",
      "planKey": "pk-a1b2c3d4e5f6",
      "planName": "标准套餐",
      "status": "active",
      "keyCount": 1
    },
    "createdAt": "2026-09-21T00:00:00Z",
    "updatedAt": "2026-09-21T00:00:00Z"
  },
  "apiKey": {
    "id": "ak-a1b2c3d4e5f6",
    "keyId": "key-a1b2c3d4e5f6",
    "key": "sk-beacon-EXAMPLE-NOT-A-REAL-KEY",
    "masked": "sk-beacon-…-KEY"
  }
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
401	unauthorized	authentication required
400	invalid_request	请求体格式错误、名称无效或指定的套餐不存在
403	forbidden	缺少消费者写权限或共享套餐使用权限
409	conflict	消费者资源冲突，或绑定套餐期间套餐共享关系被撤销
500	internal_error	消费者或首个 API Key 创建失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

批量查询消费者实时配额

功能介绍

批量查询消费者当前限流周期内的请求数和 Token 数配额。多个 API Key 属于同一消费者时，共享这里返回的用量和剩余额度。

访问要求：有效 Token 和消费者读权限，消费者可见范围与查询消费者接口一致。请求中不可见或不存在的消费者 ID 不会出现在响应中。

URI

GET /api/v1/consumers/quota

查询参数

参数	类型	必选	描述
ids	string	是	逗号分隔的消费者 ID，去重后须包含 1 至 200 个非空 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	消费者实时配额列表
items[].consumerId	string	消费者 ID
items[].available	boolean	是否成功获取配额信息；未绑定套餐时也为 true，但不包含 requests 和 tokens
items[].requests	object / null	请求数配额；套餐未限制请求数、未绑定套餐或配额不可用时省略
items[].requests.limit	int64	当前配置周期内的请求数上限
items[].requests.used	int64	当前周期已使用请求数
items[].requests.remaining	int64	当前周期剩余请求数，最小为 0
items[].requests.unit	string	周期单位：minute、hour、day、month 或 year
items[].requests.period	integer	周期倍数
items[].requests.resetAt	string(date-time) / null	当前周期重置时间，RFC3339；尚未形成活跃周期时省略
items[].tokens	object / null	Token 数配额；字段含义与 requests 相同，套餐未限制 Token 数、未绑定套餐或配额不可用时省略

请求示例

GET https://{endpoint}/api/v1/consumers/quota?ids=consumer-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "consumerId": "con-a1b2c3d4e5f6",
      "available": true,
      "requests": {
        "limit": 100,
        "used": 12,
        "remaining": 88,
        "unit": "minute",
        "period": 1,
        "resetAt": "2026-09-21T00:01:00Z"
      },
      "tokens": {
        "limit": 100000,
        "used": 18000,
        "remaining": 82000,
        "unit": "minute",
        "period": 1,
        "resetAt": "2026-09-21T00:01:00Z"
      }
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	ids must contain 1 to 200 consumer ids
401	unauthorized	authentication required
500	internal_error	查询消费者或实时配额失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

获取消费者详情

功能介绍

获取消费者详情及其 API Key 脱敏列表。响应不包含任何 API Key 明文。

访问要求：有效 Token 和消费者读权限。普通调用方只能获取当前项目中自己创建的消费者；具有消费者所有者管理权限时可读取项目内其他用户的消费者。全局读权限允许跨项目读取，但仍受所有者范围限制，除非同时具有消费者所有者管理权限。

URI

GET /api/v1/consumers/{id}

参数	类型	必选	描述
id	string	是	消费者 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	消费者状态：active 表示启用，disabled 表示禁用
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
spec	object	消费者配置快照
spec.planId	string	绑定的套餐 ID；未绑定套餐时为空字符串
spec.planKey	string	套餐内部标识；未绑定套餐时可能省略
spec.planName	string	套餐名称快照；未绑定套餐时可能省略
spec.status	string	消费者状态：active 或 disabled
spec.keyCount	integer	状态为 active 的 API Key 数量，不包含已禁用的 Key；到期但状态仍为 active 的 Key 仍可能计入
spec.ownerEmail	string	创建者登录邮箱；空值时可能省略
keys	array	API Key 脱敏列表；没有 API Key 时可能省略
keys[].id	string	API Key 资源 ID，用于启用、禁用和删除 API Key
keys[].keyId	string	API Key 标识，可用于用量记录关联；不能代替 id 作为管理接口路径参数
keys[].masked	string	API Key 脱敏值，不可用于网关认证
keys[].status	string	API Key 状态：active 或 disabled
keys[].notBefore	string(date-time) / null	生效时间，RFC3339；未设置时省略
keys[].expiresAt	string(date-time) / null	到期时间，RFC3339；未设置时省略
keys[].createdAt	string(date-time)	创建时间，RFC3339
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

GET https://{endpoint}/api/v1/consumers/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "con-a1b2c3d4e5f6",
  "name": "示例消费者",
  "description": "",
  "status": "active",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "spec": {
    "planId": "plan-id",
    "planKey": "pk-a1b2c3d4e5f6",
    "planName": "标准套餐",
    "status": "active",
    "keyCount": 1
  },
  "keys": [
    {
      "id": "ak-a1b2c3d4e5f6",
      "keyId": "key-a1b2c3d4e5f6",
      "masked": "sk-beacon-…-KEY",
      "status": "active",
      "createdAt": "2026-09-21T00:00:00Z"
    }
  ],
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
404	not_found	消费者不存在或调用方不可见
500	internal_error	查询消费者失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

更新消费者

功能介绍

更新消费者名称、绑定套餐或启用状态。变更套餐或消费者状态后，同一消费者下所有 API Key 的网关授权会按新配置重新生效。重新启用消费者不会同时启用此前被单独禁用的 API Key。

访问要求：有效 Token 和当前项目的消费者写权限。普通调用方只能修改自己创建的消费者；具有消费者所有者管理权限的调用方可修改项目内其他用户的消费者。绑定其他项目共享的套餐时，还需具有共享套餐使用权限；不能修改其他项目的消费者。

URI

PATCH /api/v1/consumers/{id}

参数	类型	必选	描述
id	string	是	消费者 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	否	消费者名称；提供时不能为空
planId	string	否	绑定的套餐 ID；传空字符串解除套餐绑定，省略表示不修改；不要传 null，当前实现会将 null 视为未提供
status	string	否	消费者状态：active 表示启用，disabled 表示禁用

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	消费者状态：active 或 disabled
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
spec	object	消费者配置快照，字段含义见获取消费者详情
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PATCH https://{endpoint}/api/v1/consumers/resource-id
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "更新后的名称"
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "con-a1b2c3d4e5f6",
  "name": "更新后的名称",
  "description": "",
  "status": "active",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "spec": {
    "planId": "plan-id",
    "planKey": "pk-a1b2c3d4e5f6",
    "planName": "标准套餐",
    "status": "active",
    "keyCount": 1
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
400	invalid_request	请求体格式错误、名称为空或指定的套餐不存在
403	forbidden	缺少消费者写权限、尝试修改其他项目资源或缺少共享套餐使用权限
404	not_found	消费者不存在或调用方无权访问
409	conflict	消费者资源冲突，或绑定套餐期间套餐共享关系被撤销
500	internal_error	更新消费者失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除消费者

功能介绍

删除消费者及其全部 API Key。删除后，这些 API Key 不能再用于调用模型网关，且无法通过查询接口恢复。

访问要求：有效 Token 和当前项目的消费者写权限。普通调用方只能删除自己创建的消费者；具有消费者所有者管理权限的调用方可删除项目内其他用户的消费者；不能删除其他项目的消费者。

URI

DELETE /api/v1/consumers/{id}

参数	类型	必选	描述
id	string	是	消费者 ID

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/consumers/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	authentication required
403	forbidden	缺少消费者写权限或尝试删除其他项目的消费者
404	not_found	消费者不存在或调用方无权访问
500	internal_error	删除消费者或其 API Key 失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

签发新的 API Key

功能介绍

为指定消费者签发新的 API Key。该操作只新增 Key，不会自动禁用或删除已有 Key；用于密钥轮换时，应在新 Key 验证可用后再禁用或删除旧 Key。

访问要求：有效 Token 和当前项目的消费者写权限。普通调用方只能为自己创建的消费者签发 Key；具有消费者所有者管理权限的调用方可管理项目内其他用户的消费者；不能为其他项目的消费者签发 Key。

URI

POST /api/v1/consumers/{id}/apikeys

参数	类型	必选	描述
id	string	是	消费者 ID

请求消息

请求体可选。提供请求体时，Content-Type 为 application/json。

参数	参数类型	是否必选	描述
expiresInHours	integer	否	密钥有效小时数；大于 0 时设置到期时间，省略、传 0 或负数时不设置到期时间

响应消息

参数	参数类型	描述
id	string	API Key 资源 ID，用于启用、禁用和删除 API Key
keyId	string	API Key 标识，可用于用量记录关联；不能代替 id 作为管理接口路径参数
key	string	API Key 明文，仅本次签发响应返回
masked	string	API Key 脱敏值
expiresAt	string(date-time) / null	到期时间；空值时可能省略

请求示例

POST https://{endpoint}/api/v1/consumers/resource-id/apikeys
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "expiresInHours": 24
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "id": "ak-a1b2c3d4e5f6",
  "keyId": "key-a1b2c3d4e5f6",
  "key": "sk-beacon-EXAMPLE-NOT-A-REAL-KEY",
  "masked": "sk-beacon-…-KEY",
  "expiresAt": "2026-09-22T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
401	unauthorized	authentication required
403	forbidden	缺少消费者写权限或尝试操作其他项目的消费者
404	not_found	消费者不存在或调用方无权访问
500	internal_error	API Key 签发失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

启用或禁用 API Key

功能介绍

启用或禁用指定 API Key。禁用后，该 Key 不能再调用模型网关；重新启用不会更换明文，也不会绕过消费者、套餐和有效期状态检查。

访问要求：有效 Token 和当前项目的消费者写权限。普通调用方只能管理自己创建的消费者下的 Key；具有消费者所有者管理权限的调用方可管理项目内其他用户的消费者；不能操作其他项目的消费者或不属于该消费者的 Key。

URI

PATCH /api/v1/consumers/{id}/apikeys/{keyId}

参数	类型	必选	描述
id	string	是	消费者 ID
keyId	string	是	API Key 资源 ID，对应消费者详情中 keys[].id，而不是 keys[].keyId

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
status	string	是	API Key 状态：active 表示启用，disabled 表示禁用

响应消息

参数	参数类型	描述
id	string	API Key 资源 ID
status	string	API Key 状态：active 或 disabled

请求示例

PATCH https://{endpoint}/api/v1/consumers/con-a1b2c3d4e5f6/apikeys/ak-a1b2c3d4e5f6
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "status": "disabled"
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "ak-a1b2c3d4e5f6",
  "status": "disabled"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
400	invalid_request	请求体格式错误
403	forbidden	缺少消费者写权限或尝试操作其他项目的消费者
404	not_found	消费者不存在、调用方无权访问，或 Key 不属于该消费者
500	internal_error	更新 API Key 状态失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除 API Key

功能介绍

永久删除指定 API Key。删除后，该 Key 不能再用于调用模型网关，也不能重新启用；需要恢复访问时只能重新签发 Key。

访问要求：有效 Token 和当前项目的消费者写权限。普通调用方只能管理自己创建的消费者下的 Key；具有消费者所有者管理权限的调用方可管理项目内其他用户的消费者；不能操作其他项目的消费者或不属于该消费者的 Key。

URI

DELETE /api/v1/consumers/{id}/apikeys/{keyId}

参数	类型	必选	描述
id	string	是	消费者 ID
keyId	string	是	API Key 资源 ID，对应消费者详情中 keys[].id，而不是 keys[].keyId

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/consumers/con-a1b2c3d4e5f6/apikeys/ak-a1b2c3d4e5f6
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	authentication required
403	forbidden	缺少消费者写权限或尝试操作其他项目的消费者
404	not_found	消费者不存在、调用方无权访问，或 Key 不属于该消费者
500	internal_error	删除 API Key 失败

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。