创建API
更新时间：2026-09-20
该接口用于创建 API 路由，并配置请求匹配、后端策略、路径重写、重试、超时和消费者认证等能力。
注意事项：
- API 创建后默认为已发布状态，创建成功后路由即生效。
- Model 路由使用
MODEL_NAME策略时，每个 PRIMARY 后端生成一条模型匹配规则，接口返回逻辑路由的入口apiId。 - Model 路由不能使用
x-gateway-api-scope和x-gateway-llm-model两个系统保留 Header。
请求结构
Plain Text
1POST /?action=CreateApi HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: authorization string
4
5{
6 "instanceId": instanceId,
7 "serviceId": serviceId,
8 "apiType": apiType,
9 "routeType": routeType,
10 "modelBackendStrategy": modelBackendStrategy,
11 "name": name,
12 "description": description,
13 "methods" : [method],
14 "path": path,
15 "matchType": matchType,
16 "headerList" : [headerList],
17 "queryList" : [queryList],
18 "backendList" : [backendList],
19 "urlRewrite": urlRewrite,
20 "urlRewritePath": urlRewritePath,
21 "urlRewriteHost": urlRewriteHost,
22 "urlRewriteType": urlRewriteType,
23 "urlRewriteRegexMatch": urlRewriteRegexMatch,
24 "urlRewriteRegexRewrite": urlRewriteRegexRewrite,
25 "retries": retries,
26 "attempts": attempts,
27 "perTryTimeout": perTryTimeout,
28 "retryOn" : [retryOn],
29 "httpCodes" : [httpCode],
30 "timeout": timeout,
31 "timeoutTime": timeoutTime,
32 "priorityNumber": priorityNumber,
33 "fallbackEnabled": fallbackEnabled,
34 "fallbackFirstTokenTimeoutMs": fallbackFirstTokenTimeoutMs,
35 "fallbackTriggerScope": fallbackTriggerScope,
36 "consumerAuthEnabled": consumerAuthEnabled,
37 "authorizationType": authorizationType,
38 "consumerIds" : [consumerId],
39 "consumerAuthorizations" : [consumerAuthorization]
40}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| instanceId | String | 是 | RequestBody参数 | 网关实例 ID |
| serviceId | String | 是 | RequestBody参数 | 服务 ID |
| apiType | String | 是 | RequestBody参数 | API 类型：基础 API 传 HTTP_ROUTE / WEB_SOCKET，Agent 路由传 http / websocket，Model 路由传 MODEL_ROUTE |
| routeType | String | 否 | RequestBody参数 | 路由类型：HTTP_ROUTE / MODEL_ROUTE / AGENT_ROUTE，不传时默认为 HTTP_ROUTE |
| modelBackendStrategy | String | 否 | RequestBody参数 | 后端策略：基础 API 支持 SINGLE / WEIGHT，Model 路由支持 SINGLE / MODEL_NAME / WEIGHT，Agent 路由不传 |
| name | String | 是 | RequestBody参数 | API 名称 |
| description | String | 否 | RequestBody参数 | 路由描述 |
| methods | List<String> | 是 | RequestBody参数 | 请求方法 |
| path | String | 是 | RequestBody参数 | 路径 |
| matchType | String | 是 | RequestBody参数 | 匹配类型 |
| headerList | List<AiGwApiHeader> | 否 | RequestBody参数 | 请求头 |
| queryList | List<AiGwApiQuery> | 否 | RequestBody参数 | 请求参数 |
| backendList | List<AiGwApiBackendBind> | 是 | RequestBody参数 | 后端配置 |
| urlRewrite | Boolean | 否 | RequestBody参数 | 路径重写 |
| urlRewritePath | String | 否 | RequestBody参数 | 路径重写：重写后的路径 |
| urlRewriteHost | String | 否 | RequestBody参数 | 路径重写：重写后的 Host |
| urlRewriteType | String | 否 | RequestBody参数 | 路径重写匹配类型：Exact / Prefix / Regex；开启路径重写时必填 |
| urlRewriteRegexMatch | String | 否 | RequestBody参数 | 正则重写模式，如 ^/user/(/+)(/.*)$；重写类型为 Regex 时必填 |
| urlRewriteRegexRewrite | String | 否 | RequestBody参数 | 正则重写替换表达式，如 /instance/\1；重写类型为 Regex 时必填 |
| retries | Boolean | 否 | RequestBody参数 | 重试 |
| attempts | int | 否 | RequestBody参数 | 重试次数 |
| perTryTimeout | int | 否 | RequestBody参数 | 单次重试超时时间（毫秒） |
| retryOn | List<String> | 否 | RequestBody参数 | 重试条件 |
| httpCodes | List<int> | 否 | RequestBody参数 | 触发重试的响应状态码 |
| timeout | Boolean | 否 | RequestBody参数 | 超时时间 |
| timeoutTime | int | 否 | RequestBody参数 | 超时时间（毫秒） |
| priorityNumber | long | 是 | RequestBody参数 | 优先级（0-9999），0 为最高优先级，默认 9999 |
| fallbackEnabled | Boolean | 否 | RequestBody参数 | Model 路由 Fallback 开关 |
| fallbackFirstTokenTimeoutMs | int | 否 | RequestBody参数 | Model 路由 Fallback 首次响应超时时间（毫秒），0 表示不启用 |
| fallbackTriggerScope | String | 否 | RequestBody参数 | Model 路由 Fallback 触发范围，仅支持 BACKEND_ERROR_ONLY |
| consumerAuthEnabled | Boolean | 否 | RequestBody参数 | 是否开启消费者认证 |
| authorizationType | String | 否 | RequestBody参数 | 消费者认证方式：API_KEY / AK_SK；开启认证时必填 |
| consumerIds | List<String> | 否 | RequestBody参数 | 绑定消费者 ID 列表，可为空（开启但空 = 全部拒绝） |
| consumerAuthorizations | List<ConsumerAuthorization> | 否 | RequestBody参数 | 消费者认证项列表；同一消费者可同时以 API_KEY 和 AK_SK 授权 |
返回头域
除公共头域，无其它特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| apiId | String | API ID |
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| MethodArgumentNotValidException | MethodArgumentNotValidException: name must not be blank | 400 | 必填参数缺失或格式不合法，name 不能为空 |
| HttpMessageNotReadable | Http Message Not Readable: JSON parse error | 400 | 请求体不是合法 JSON，无法解析，请检查 JSON 语法和字段类型 |
| ResourcePermissionDeny | Resource permission deny. | 401 | 无权限访问指定资源，请确认实例属于当前账号并使用有权限的账号凭证 |
| ServiceNotExist | Service not exist. | 404 | serviceId 对应的服务不存在、不属于当前账号或已删除 |
| HttpMediaTypeException | HttpMediaTypeException: Content-Type 'text/plain' is not supported | 415 | 请求的 Content-Type 不受支持，请使用 application/json |
| DataPlaneSyncFailed | 配置已保存成功，但网关操作失败，请稍后重试或联系技术支持。 | 500 | 配置已写入控制面，但下发数据面失败，请稍后重试或联系技术支持 |
请求示例
Plain Text
1POST /?action=CreateApi HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
4
5{
6 "instanceId": "gw-a1b2c3d4",
7 "serviceId": "sg-a1b2c3d4",
8 "apiType": "HTTP_ROUTE",
9 "routeType": "HTTP_ROUTE",
10 "name": "对话API",
11 "description": "对外提供对话能力",
12 "methods": [
13 "POST"
14 ],
15 "path": "/v1/chat",
16 "matchType": "Prefix",
17 "backendList": [
18 {
19 "backendId": "bd-a1b2c3d4",
20 "backendRole": "PRIMARY"
21 }
22 ],
23 "urlRewrite": false,
24 "retries": true,
25 "attempts": 1,
26 "perTryTimeout": 60000,
27 "timeout": true,
28 "timeoutTime": 60000,
29 "priorityNumber": 0,
30 "consumerAuthEnabled": false
31}返回示例
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
3Date: Wed, 03 Dec 2014 06:42:19 GMT
4Content-Type: application/json;charset=UTF-8
5Server: BWS
6
7{
8 "apiId": "api-a1b2c3d4"
9}评价此篇文章