负载均衡创建用户组

1. 接口描述

接口请求域名： clb.tencentcloudapi.com 。

在指定模型路由实例下创建一个用户组。用户组是介于模型路由实例与 Key 之间的一层可选分组，可为组内 Key 统一配置模型白名单，并通过关联 Budget 统一管理额度。创建为异步操作，接口会同步返回用户组ID，可凭返回的 RequestId 调用 DescribeAsyncJobs 查询创建进度。支持建组时绑定 Prompt：传入 PromptId 与 PromptVersion 后，组内 Key 的请求将按该版本 Prompt 的 Content 与 RewriteStrategy 注入或改写 system 内容，并受该版本 MaxTokens 约束；不传则默认不绑定 Prompt，建组后可通过 ModifyUserGroupPrompt 绑定、更换版本或解绑。仅传入 PromptId 或 PromptVersion 其一时返回 InvalidParameter；PromptId 不存在时返回 ResourceNotFound.Prompt；PromptVersion 不存在于该 Prompt 的历史版本中时返回 ResourceNotFound.PromptVersion。

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer

点击调试

API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateUserGroup。
Version	是	String	公共参数，本接口取值：2018-03-17。
Region	是	String	公共参数，详见产品支持的地域列表，本接口仅支持其中的: ap-beijing, ap-guangzhou, ap-shanghai, ap-singapore, na-siliconvalley 。
ModelRouterId	是	String	模型路由实例ID。用户组将创建在该实例下。示例值：cmr-pm53f9c3
UserGroupName	是	String	用户组名称。必填。同一模型路由实例下名称唯一，长度不超过255个字符。示例值：核心业务组
BudgetId	否	String	建组时直接关联的预算 ID（须为已存在的 Budget）。关联后由该 Budget 统一管理本组的消费上限与限速。不传表示不关联预算，可建组后再用 AssociateBudget 关联。示例值：budget-1a2b3c4d
PromptId	否	String	建组时绑定的 Prompt 资源 ID（pmt-xxx，须为该实例下已存在的 Prompt）。与 PromptVersion 必须成对传入，仅传其一将返回错误。不传表示默认不绑定 Prompt，可建组后再调用 ModifyUserGroupPrompt 绑定或更换版本。绑定后，组内 Key 的请求将按该版本 Prompt 的 Content 与 RewriteStrategy 注入或改写 system 内容。示例值：pmt-a1b2c3d4
PromptVersion	否	String	绑定的 Prompt 版本号（如 v1、v2，由 CreatePrompt / CreatePromptVersion 生成，长度不超过16个字符），与 PromptId 必须成对传入，须为该 Prompt 下已存在的版本。版本为不可变快照，Prompt 后续新增版本不会自动生效于已绑定的用户组，需显式重新绑定新版本。一个用户组同时只关联一份 Prompt 的一个版本，重复绑定即为替换。示例值：v2
IntentRouters.N	否	Array of String	用户组意图路由白名单（ir-xxx）。每一项须为该实例已创建的意图路由名。命中意图路由名时其内部真实模型自动豁免白名单。为空表示不授权任何意图路由。示例值：["ir-chat"]
KeyIds.N	否	Array of String	建组时同时绑定的已有 Key ID 列表，最多100个。每个 Key 须属于同一模型路由实例。建组与绑定为一个原子异步任务，任一 Key 失败则整组创建回滚。不传表示建空组。示例值：["mkey-aaa111","mkey-bbb222"]
Models.N	否	Array of String	用户组真实模型白名单。每一项须为该实例已关联的模型名。为空表示不在用户组层限制真实模型（按实例层白名单生效）。示例值：["deepseek-v3"]
Tags.N	否	Array of TagInfo	标签列表，最多50个。

3. 输出参数

参数名称	类型	描述
UserGroupId	String	新建用户组的ID。示例值：ugrp-9f8e7d6c
RequestId	String	唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 创建用户组

输入示例

POST / HTTP/1.1
Host: clb.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateUserGroup
<公共请求参数>

{
    "ModelRouterId": "cmr-pm53f9c3",
    "UserGroupName": "核心业务组",
    "Models": [
        "deepseek-v3"
    ],
    "IntentRouters": [
        "ir-chat"
    ]
}

输出示例

{
    "Response": {
        "UserGroupId": "ugrp-9f8e7d6c",
        "RequestId": "d81e7b1f-3587-491b-8556-9e47222fecfd"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

Tencent Cloud SDK 3.0 for Python: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for Java: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for PHP: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for Go: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for Node.js: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for .NET: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for C++: CNB, GitHub, Gitee
Tencent Cloud SDK 3.0 for Ruby: CNB, GitHub, Gitee

命令行工具

Tencent Cloud CLI 3.0

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见公共错误码。

错误码	描述
InvalidParameter	参数错误。
ResourceNotFound.Prompt	提示词未找到
ResourceNotFound.PromptVersion	ResourceNotFound.PromptVersion

创建用户组

本页目录：