# 创建API Key #### 功能介绍 创建接口是API Key全生命周期管理的起点，旨在为开发者或业务系统生成专属的身份访问凭证。在MaaS平台中，模型推理与数据请求均依赖有效的密钥进行鉴权。通过该接口，用户可以根据不同的业务场景生成独立的API Key，并为其分配最小必要权限。这不仅实现了业务间的隔离，还大幅降低了因单一密钥泄露而导致全局服务受损的风险，从源头上保障了模型调用的安全性与稳定性。 约束: - 鉴权：调用本接口需在请求头携带有效IAM token（X-Auth-Token），并具备对应细粒度权限：创建需modelarts:apiKey:create - 租户隔离：接口操作范围由当前token所属的Project / Domain 决定，project_id由鉴权上下文自动带入，不支持跨租户操作。 - 密钥安全：API Key明文仅在创建API Key的响应中返回，其余接口仅返回脱敏mask。请于创建后立即妥善保存，丢失后需重新创建。 - 请保证账号余额充足，否则会创建失败。 #### URI POST /v2/{project_id}/maas/api-auth/api-keys 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释** ：项目ID，是华为云中用于标识租户资源的唯一编号，与具体的区域（Region）相关联。在调用华为云API时用于定位资源所属的项目空间。通过[获取项目ID和名称](https://support.huaweicloud.com/api-maas/api-maas-0028.html)接口获取。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | label | 否 | String | **参数解释**：API Key的名称。标签长度范围为 0 到 100 个字符，支持大小写英文字母、数字、下划线、中划线。 **约束限制**：租户下全局唯一。 **取值范围**：不涉及。 **默认取值**：未填写时，系统生成一个默认值，ak-{6位随机数}。 | | description | 否 | String | **参数解释**：API Key的描述信息。最多 100 字符。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | allow_all | 是 | Boolean | **参数解释**：是否允许所有IP访问。 **约束限制**：不涉及。 **取值范围**： - true：表示不限制IP。 - false：限制IP。 **默认取值**：不涉及。 | | ip_whitelist | 否 | Array of strings | **参数解释**：API Key的IP白名单是华为云MaaS（模型即服务）中API Key的一项安全功能，用于限制只有指定IP地址才能使用该API Key调用模型服务，防止API Key泄露后被非法利用。示例如下： - 单个IP地址(如：192.168.1.1)； - IP地址段范围(如：192.168.1.10-192.168.1.100)； - CIDR网段(如：192.168.10.0/24)。 **约束限制**： - 数量 ≤ 100； - 每个IP须为合法IPv4，支持CIDR格式（如 192.168.0.0/24）； - 不可有重复IP； - CIDR掩码须连续合法； - 当allow_all=true时此项必须为空。 **IP校验规则**： 1. IP单段数值校验：IPv4的每一个段（Octet）必须是0到255之间的有效十进制整数。 2. IP 格式与子网掩码校验： - 整体格式必须符合x.x.x.x或x.x.x.x/y的正则规范。 - 若包含子网掩码，其数值必须在0到32之间。 - **特殊业务规则**：子网掩码的位数必须大于或等于该IP地址转换为32位二进制后最后一个1所在的位置（即掩码不能截断IP的有效标识位）。 3.**IP大小比较规则**：比较两个IP时，按从左到右（高位到低位）逐段进行数值比对，以此确定大小关系。 4.**IP 范围校验**：一个合法的IP范围必须严格包含2个IP，且这两个IP均需通过上述的格式与掩码校验，同时起始IP必须小于或等于结束IP。 | | resident_model_version_whitelist | 否 | [ResidentModelVersionWhitelist] object | **参数解释**：常驻模型版本白名单，限制可访问的常驻模型版本。 **约束限制**：不涉及。 | | endpoint_whitelist | 否 | [EndpointWhitelist] object | **参数解释**：自定义接入点白名单，限制可访问的自定义接入点。 **约束限制**：不涉及。 | 表3ResidentModelVersionWhitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | overall | 否 | String | **参数解释**：API Key生效的模型服务范围（包括模型服务以及对应的版本）。 **约束限制**：不涉及。 **取值范围**： 1. all: 表示全部生效。 2. 空字符串：表示非全部生效。 **默认取值**：空字符串。 | | whitelist | 否 | Array of [Whitelist] objects | **参数解释**：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。 **取值范围**：Whitelist对象数组，见下方拆解字段。 | 表4Whitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | resident_model_id | 否 | String | **参数解释**：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | version_whitelist | 否 | String | **参数解释**：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | 表5EndpointWhitelist | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | overall | 否 | String | **参数解释**：整体放行策略。 **约束限制**：不涉及。 **取值范围**："all" 表示放行全部，空字符串表示不启用整体放行。 **默认取值**：空字符串。 | | whitelist | 否 | Array of strings | **参数解释** ：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过[查询自定义接入点](https://support.huaweicloud.com/api-maas/api-maas-0015.html)接口获取ID。 **约束限制**：不涉及。 | #### 响应参数 **状态码：201** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**：API Key的唯一标识ID，系统自动生成。 **取值范围**：不涉及。 | | api_key | String | **参数解释**：推理服务生成的原始API Key明文（仅在创建时返回一次）。长度 ≤ 255 的字符串。 **取值范围**：不涉及。 | | label | String | **参数解释**：API Key的显示名称，回显请求中的label。 **取值范围**：不涉及。 | | description | String | **参数解释**：API Key的描述信息，回显请求中的description。最大长度100字符。 **取值范围**：不涉及。 | | allow_all | Boolean | **参数解释**：是否允许所有IP访问。 **取值范围**： - true：表示不限制IP。 - false ：限制IP。 | | ip_whitelist | Array of strings | **参数解释**：IP白名单列表，回显实际生效值。 **取值范围**：不涉及。 | | resident_model_version_whitelist | [ResidentModelVersionWhitelist] object | **参数解释**：常驻模型版本白名单信息，回显请求中的值。 **取值范围**：不涉及。 | | endpoint_whitelist | [EndpointWhitelist] object | **参数解释**：自定义接入点白名单信息，回显请求中的值。 **取值范围**：不涉及 。 | 表7ResidentModelVersionWhitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | overall | String | **参数解释**：API Key生效的模型服务范围（包括模型服务以及对应的版本）。 **取值范围**： 1. all: 表示全部生效。 2. 空字符串：表示非全部生效。 | | whitelist | Array of [Whitelist] objects | **参数解释**：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。 **取值范围**：Whitelist对象数组，见下方拆解字段。 | 表8Whitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | resident_model_id | String | **参数解释**：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。 **取值范围**：不涉及。 | | version_whitelist | String | **参数解释**：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下： 在MaaS控制台的"在线推理-预置服务"页面，使用快捷键F12打开开发者工具，选择"Network"页签，搜索"query"，单击以"query?business_type=payment"开头的名称，在"Response"页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。 **取值范围**：不涉及。 | 表9EndpointWhitelist | 参数 | 参数类型 | 描述 | |:---|:---|:---| | overall | String | **参数解释**：整体放行策略。 **取值范围**："all" 表示放行全部，空字符串表示不启用整体放行。 | | whitelist | Array of strings | **参数解释** ：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过[查询自定义接入点](https://support.huaweicloud.com/api-maas/api-maas-0015.html)接口获取ID。 | **状态码：403** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_msg | String | **参数解释**：错误信息描述。 **取值范围**：不涉及。 | | error_code | String | **参数解释**：错误码。 **取值范围**：不涉及。 | #### 请求示例 ``` POST https://{endpoint}/v2/{project_id}/services/api-auth/api-keys/ { "description" : "用于生产环境调用的密钥", "label" : "my-api-key", "allow_all" : false, "ip_whitelist" : [ "192.168.0.0/24", "10.0.0.1" ], "resident_model_version_whitelist" : { "overall" : "", "whitelist" : [ { "resident_model_id" : "ce15e584-bb43-46ff-a215-febb27501353", "version_whitelist" : "all" }, { "resident_model_id" : "1a848aa4-6493-4da0-bd5a-e1e918fad55f", "version_whitelist" : "all" } ] }, "endpoint_whitelist" : { "overall" : "", "whitelist" : [ "d8d76767-637a-4040-8835-39bdc39b79b6", "6a9cba80-3594-4611-a8c0-a5a1fd34985d" ] } } ``` #### 响应示例 **状态码：201** ``` { "id" : "1ccb3e8f-ece2-4f9c-97cc-18143dff685c", "api_key" : "返回的明文api_key", "label" : "my-api-key", "description" : "用于生产环境调用的密钥", "allow_all" : false, "ip_whitelist" : [ "192.168.0.0/24", "10.0.0.1" ], "resident_model_version_whitelist" : { "overall" : "", "whitelist" : [ { "resident_model_id" : "ce15e584-bb43-46ff-a215-febb27501353", "version_whitelist" : "all" }, { "resident_model_id" : "1a848aa4-6493-4da0-bd5a-e1e918fad55f", "version_whitelist" : "all" } ] }, "endpoint_whitelist" : { "overall" : "", "whitelist" : [ "d8d76767-637a-4040-8835-39bdc39b79b6", "6a9cba80-3594-4611-a8c0-a5a1fd34985d" ] } } ``` **状态码：403** ``` { "error_msg" : "Invalid token.", "error_code" : "ModelArts.0104" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 创建API Key成功。 | | 403 | 用户鉴权token异常。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-maas/ErrorCode.html)。