创建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和名称接口获取。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

请求参数

表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校验规则： IP单段数值校验：IPv4的每一个段（Octet）必须是0到255之间的有效十进制整数。 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	参数解释：自定义接入点白名单，限制可访问的自定义接入点。约束限制：不涉及。

表3 ResidentModelVersionWhitelist
参数	是否必选	参数类型	描述
overall	否	String	参数解释：API Key生效的模型服务范围（包括模型服务以及对应的版本）。约束限制：不涉及。取值范围： all: 表示全部生效。空字符串：表示非全部生效。默认取值：空字符串。
whitelist	否	Array of Whitelist objects	参数解释：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。取值范围：Whitelist对象数组，见下方拆解字段。

表4 Whitelist
参数	是否必选	参数类型	描述
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即为常驻模型版本值。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表5 EndpointWhitelist
参数	是否必选	参数类型	描述
overall	否	String	参数解释：整体放行策略。约束限制：不涉及。取值范围：“all” 表示放行全部，空字符串表示不启用整体放行。默认取值：空字符串。
whitelist	否	Array of strings	参数解释：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过查询自定义接入点接口获取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	参数解释：自定义接入点白名单信息，回显请求中的值。取值范围：不涉及。

表7 ResidentModelVersionWhitelist
参数	参数类型	描述
overall	String	参数解释：API Key生效的模型服务范围（包括模型服务以及对应的版本）。取值范围： all: 表示全部生效。空字符串：表示非全部生效。
whitelist	Array of Whitelist objects	参数解释：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。取值范围：Whitelist对象数组，见下方拆解字段。

表8 Whitelist
参数	参数类型	描述
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即为常驻模型版本值。取值范围：不涉及。

表9 EndpointWhitelist
参数	参数类型	描述
overall	String	参数解释：整体放行策略。取值范围：“all” 表示放行全部，空字符串表示不启用整体放行。
whitelist	Array of strings	参数解释：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过查询自定义接入点接口获取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异常。

错误码

请参见错误码。

父主题： API Key鉴权管理

上一篇：API Key鉴权管理

下一篇：更新API Key