AI Model Management

version tip

Added since v5.2.0. Accessed via app.aiModel, this module provides configuration, query, update and deletion capabilities for AI model groups in a CloudBase environment, and supports OpenAI-compatible gateways (e.g. DeepSeek, Hunyuan, Moonshot).

AiModelService is organized around the AI Model Group (AIModelGroup). Each group contains:

• GroupName: group name. Custom group names MUST NOT start with cloudbase (reserved prefix).
• BaseUrl: model service URL (must be an OpenAI-compatible gateway).
• Models: list of models under this group. Replaced as a whole on update.
• Secret: credentials used to access the model service. Either SecretId / SecretKey or ApiKey.
• Status: group status. 1 = enabled, 2 = disabled.
• Type: group type. builtin (provided by CloudBase) / custom (user-defined).

---

Initialization

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const aiModel = app.aiModel

---

createAIModel

1. API Description

API feature: Creates a custom AI model configuration group.

API declaration: app.aiModel.createAIModel(options): Promise<CreateAIModelResp>

Note

groupName MUST NOT start with cloudbase, which is a reserved prefix. The server validates baseUrl + secret connectivity, so make sure the model service is reachable and the credentials are valid.

2. Input Parameters

Field	Required	Type	Description
groupName	Required	String	Group name. Must not start with cloudbase.
baseUrl	No	String	Model service URL (OpenAI-compatible gateway), e.g. https://api.deepseek.com/v1.
models	No	AIModel[]	Model list. See AIModel below.
remark	No	String	Group remark.
status	No	1 | 2	Model status. 1 = enabled, 2 = disabled.
secret	No	AIModelSecret	Model credentials. See AIModelSecret below.
envId	No	String	Environment ID. Falls back to the current environment if omitted.

AIModel

Field	Required	Type	Description
Model	No	String	Model name, e.g. deepseek-chat.
EnableMCP	No	Boolean	Whether MCP is enabled. Default false.
Tags	No	String[]	Tags.

AIModelSecret

Field	Required	Type	Description
SecretSource	No	String	Source of the credential. Fixed value: custom.
SecretId	No	String	Secret ID, paired with SecretKey.
SecretKey	No	String	Secret Key, paired with SecretId.
ApiKey	No	String	API Key. Mutually exclusive with SecretId/SecretKey.

3. Return Value

Field	Type	Description
Count	Number	Number of groups created.
RequestId	String	Request identifier.

4. Example

const res = await app.aiModel.createAIModel({
  groupName: 'custom-deepseek',
  baseUrl: 'https://api.deepseek.com/v1',
  models: [
    { Model: 'deepseek-chat', EnableMCP: false }
  ],
  remark: 'DeepSeek custom group',
  status: 1,
  secret: {
    SecretSource: 'custom',
    ApiKey: 'sk-xxxxxxxxxxxxxxxx'
  }
})

console.log(res.Count, res.RequestId)

---

updateAIModel

1. API Description

API feature: Updates an existing AI model configuration group.

API declaration: app.aiModel.updateAIModel(options): Promise<UpdateAIModelResp>

Note

The models field uses full-replacement semantics. Pass in all the models you want to keep, including the unchanged ones.

2. Input Parameters

Field	Required	Type	Description
groupName	Required	String	Name of the group to update.
baseUrl	No	String	Model service URL.
models	No	AIModel[]	Model list, fully replaced.
remark	No	String	Remark.
status	No	1 | 2	Model status. 1 = enabled, 2 = disabled.
secret	No	AIModelSecret	Model credentials.
envId	No	String	Environment ID. Falls back to the current environment if omitted.

AIModel / AIModelSecret are the same as in createAIModel.

3. Return Value

Field	Type	Description
Count	Number	Number of groups updated.
RequestId	String	Request identifier.

4. Example

const res = await app.aiModel.updateAIModel({
  groupName: 'custom-deepseek',
  models: [
    { Model: 'deepseek-chat', EnableMCP: true },
    { Model: 'deepseek-reasoner', EnableMCP: true }
  ],
  status: 1
})

console.log(res.Count)

---

deleteAIModel

1. API Description

API feature: Deletes AI model configuration groups in batch.

API declaration: app.aiModel.deleteAIModel(options): Promise<DeleteAIModelResp>

2. Input Parameters

Field	Required	Type	Description
groupNames	Required	String[]	List of group names. At least one non-empty item.
envId	No	String	Environment ID. Falls back to the current environment if omitted.

3. Return Value

Field	Type	Description
Count	Number	Number of groups successfully deleted.
RequestId	String	Request identifier.

4. Example

const res = await app.aiModel.deleteAIModel({
  groupNames: ['custom-deepseek', 'custom-hunyuan']
})

console.log(res.Count)

---

describeAIModels

1. API Description

API feature: Lists AI model groups configured under the current environment, including both builtin and custom groups.

API declaration: app.aiModel.describeAIModels(options?): Promise<DescribeAIModelsResp>

2. Input Parameters

Field	Required	Type	Description
envId	No	String	Environment ID. Falls back to the current environment if omitted.

3. Return Value

Field	Type	Description
AIModels	AIModelGroup[] | null	Model group list. May be null.
RequestId	String	Request identifier.

AIModelGroup

Field	Type	Description
GroupName	String	Group name, e.g. hunyuan-exp / deepseek / cloudbase / custom-xxx.
Models	AIModel[] | null	Model list.
Type	'builtin' | 'custom'	Group type.
OriginType	'builtin' | 'custom'	Original group type.
Remark	String	Remark.
BaseUrl	String	Model service URL.
Status	1 | 2	Model status. 1 = enabled, 2 = disabled.
Secret	AIModelSecret | null	Model credentials (may be masked or null in response).
CreateTime	String	Creation time, ISO 8601.
UpdateTime	String	Last update time, ISO 8601.

4. Example

const res = await app.aiModel.describeAIModels()

for (const group of res.AIModels || []) {
  console.log(group.GroupName, group.Type, group.Status, group.Models?.length)
}

---

describeManagedAIModelList

1. API Description

API feature: Lists managed AI models supported by the CloudBase platform (billed by CloudBase, no user-provided credentials required).

API declaration: app.aiModel.describeManagedAIModelList(options?): Promise<DescribeManagedAIModelListResp>

2. Input Parameters

Field	Required	Type	Description
envId	No	String	Environment ID. Falls back to the current environment if omitted.

3. Return Value

Field	Type	Description
ManagedAIModelList	ManagedAIModelGroup[] | null	Managed model group list.
RequestId	String	Request identifier.

ManagedAIModelGroup

Field	Type	Description
GroupName	String	Group name, e.g. cloudbase.
Models	ManagedAIModel[] | null	Model list.
Remark	String	Remark.

ManagedAIModel

Field	Type	Description
Model	String	Model name, e.g. hy3-preview.
EnableMCP	Boolean	Whether MCP is enabled.
ModelSpec	ManagedAIModelSpec	Model specification (context window, token limits).
ModelChargingInfo	ManagedAIModelChargingInfo[]	Billing info (uniform / tiered).

ManagedAIModelSpec

Field	Type	Description
MaxInputToken	String	Max input tokens, e.g. 192k.
MaxOutputToken	String	Max output tokens, e.g. 32k.
ContextLength	String	Context window length, e.g. 128k.

ManagedAIModelChargingInfo

Field	Type	Description
Type	'Uniform' | 'Tiered'	Charging type: uniform / tiered.
Name	String	Tier name, e.g. 0-16k.
InputPrice	String	Input token price.
OutputPrice	String	Output token price.
CachePrice	String	Cache-hit price.
InputOutputUnit	String	Billing unit, e.g. 1k tokens.

4. Example

const res = await app.aiModel.describeManagedAIModelList()

for (const group of res.ManagedAIModelList || []) {
  console.log(group.GroupName, group.Remark)
  for (const model of group.Models || []) {
    console.log('  -', model.Model, model.ModelSpec?.ContextLength)
  }
}