创建消费者
更新时间：2026-04-24
接口描述
本接口用于在指定 AI 网关实例下创建消费者。消费者用于管理凭证、配额和授权路由；同一实例下消费者名称不可重复。
注意事项
useV2必须传true，当前仅支持 2.0 凭证管理体系。authType目前仅支持KeyAuth。- 当
unlimitedQuota=false时totalQuota必填且须 ≥ 0；当unlimitedRequestQuota=false时totalRequestQuota必填且须 > 0。 credential可以不传，表示先创建"空凭证占位"，后续通过编辑消费者接口新增；若传入时inHeader与inQuery不能同时为true。- 当
srcProduct=agentos时，tags中必须包含非空的userName标签。
请求结构
Plain Text
1POST /v1/aigw/{instanceId}/consumer HTTP/1.1
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: authorization string
5Content-Type: application/json
6
7{
8 "consumerName": "test-consumer",
9 "authType": "KeyAuth",
10 "useV2": true,
11 "credential": {
12 "name": "my-key",
13 "generateMode": "auto",
14 "inHeader": true,
15 "inQuery": false,
16 "keyNames": ["Authorization"]
17 },
18 "unlimitedQuota": false,
19 "totalQuota": 5000,
20 "quotaResetType": "daily",
21 "unlimitedRequestQuota": false,
22 "totalRequestQuota": 100,
23 "requestQuotaResetType": "daily",
24 "tags": [{"tagKey": "env", "tagValue": "prod"}]
25}请求头域
除公共头域外，还需传入以下头域：
| 参数名称 | 类型 | 是否必选 | 描述 |
|---|---|---|---|
| X-Region | String | 是 | 地域代码，如 bj、gz、su 等 |
请求参数
| 参数名称 | 类型 | 是否必选 | 参数位置 | 描述 |
|---|---|---|---|---|
| instanceId | String | 是 | URL参数 | AI 网关实例 ID |
| consumerName | String | 是 | RequestBody参数 | 消费者名称，长度 2-64 个字符，同一实例下不可重复 |
| description | String | 否 | RequestBody参数 | 消费者描述，最多 255 个字符 |
| authType | String | 是 | RequestBody参数 | 认证方式，当前仅支持 KeyAuth |
| routeNames | List<String> | 否 | RequestBody参数 | 授权路由名称列表；为空时表示授权所有路由 |
| useV2 | Boolean | 是 | RequestBody参数 | 是否启用 2.0 凭证管理，必须为 true |
| credential | Credential | 否 | RequestBody参数 | 凭证配置；不传则创建空凭证占位，后续可通过编辑接口添加 |
| unlimitedQuota | Boolean | 是 | RequestBody参数 | 是否不限 Token 配额；为 false 时 totalQuota 必填 |
| totalQuota | Integer | 条件必选 | RequestBody参数 | Token 配额总量，unlimitedQuota=false 时必填且须 ≥ 0 |
| quotaResetType | String | 否 | RequestBody参数 | Token 配额重置周期，可选值：none/daily/weekly/monthly，默认 none |
| quotaResetDay | Integer | 条件必选 | RequestBody参数 | 每月重置日（1-31），quotaResetType=monthly 时必填 |
| quotaResetWeekday | Integer | 条件必选 | RequestBody参数 | 每周重置星期（0=周日，…，6=周六），quotaResetType=weekly 时必填 |
| quotaResetHour | Integer | 否 | RequestBody参数 | 重置时刻小时（0-23，CST），默认 0 |
| quotaResetMinute | Integer | 否 | RequestBody参数 | 重置时刻分钟（0-59），默认 0 |
| unlimitedRequestQuota | Boolean | 是 | RequestBody参数 | 是否不限请求次数配额；为 false 时 totalRequestQuota 必填 |
| totalRequestQuota | Integer | 条件必选 | RequestBody参数 | 请求次数配额总量，unlimitedRequestQuota=false 时必填且须 > 0 |
| requestQuotaResetType | String | 否 | RequestBody参数 | 请求次数配额重置周期，取值同 quotaResetType，默认 none |
| requestQuotaResetDay | Integer | 条件必选 | RequestBody参数 | 每月重置日（1-31），requestQuotaResetType=monthly 时必填 |
| requestQuotaResetWeekday | Integer | 条件必选 | RequestBody参数 | 每周重置星期（0=周日，…，6=周六），requestQuotaResetType=weekly 时必填 |
| requestQuotaResetHour | Integer | 否 | RequestBody参数 | 重置时刻小时（0-23，CST），默认 0 |
| requestQuotaResetMinute | Integer | 否 | RequestBody参数 | 重置时刻分钟（0-59），默认 0 |
| tags | List<Tag> | 条件必选 | RequestBody参数 | 标签列表；srcProduct=agentos 时必须包含 userName 标签 |
Credential 字段说明
| 参数名称 | 类型 | 是否必选 | 描述 |
|---|---|---|---|
| name | String | 否 | 凭证名称，用于前端展示；不传时系统自动生成形如 {consumerName}-{consumerId}-{timestamp} 的唯一名称 |
| description | String | 否 | 凭证描述 |
| generateMode | String | 否 | 生成方式，可选值：auto（自动生成）、custom（自定义），默认 auto |
| value | String | 条件必选 | 自定义凭证明文值，generateMode=custom 时必填 |
| inHeader | Boolean | 二选一 | 是否通过 HTTP Header 传递，与 inQuery 不能同时为 true |
| inQuery | Boolean | 二选一 | 是否通过 HTTP Query 传递，与 inHeader 不能同时为 true |
| keyNames | List<String> | 是 | Header/Query 的 key 名列表，如 ["Authorization"] |
Tag 字段说明
| 参数名称 | 类型 | 是否必选 | 描述 |
|---|---|---|---|
| tagKey | String | 是 | 标签键 |
| tagValue | String | 是 | 标签值 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| consumerId | String | 新创建消费者的 ID |
| credential | String | 若创建时生成凭证则返回凭证明文；无凭证创建时为空字符串 |
| authVersion | Integer | 认证版本号，固定为 2 |
请求示例
Plain Text
1POST http://aigw.bj.baidubce.com/v1/aigw/i-a1b2c3d4/consumer
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2026-04-23T04:17:29Z/3600/host;x-bce-date/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
5Content-Type: application/json
6
7{
8 "consumerName": "test-consumer",
9 "description": "测试用消费者",
10 "authType": "KeyAuth",
11 "routeNames": ["route-001", "route-002"],
12 "useV2": true,
13 "credential": {
14 "name": "my-key",
15 "generateMode": "auto",
16 "inHeader": true,
17 "inQuery": false,
18 "keyNames": ["Authorization"]
19 },
20 "unlimitedQuota": false,
21 "totalQuota": 5000,
22 "quotaResetType": "daily",
23 "quotaResetHour": 0,
24 "quotaResetMinute": 0,
25 "unlimitedRequestQuota": false,
26 "totalRequestQuota": 100,
27 "requestQuotaResetType": "daily",
28 "requestQuotaResetHour": 0,
29 "requestQuotaResetMinute": 0,
30 "tags": [{"tagKey": "env", "tagValue": "prod"}]
31}响应示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3x-bce-request-id: d8752367-38e8-45e4-b4c7-e53be3137ce5
4
5{
6 "consumerId": "cs-9d9b2f86ec8bde77",
7 "credential": "Bearer 9d9b2f86-ec8bde77-444b-57ce9ce6e6b6",
8 "authVersion": 2
9}评价此篇文章