Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
When to use this skill
Use this skill for calling AI models in browser/Web applications via @cloudbase/js-sdk.
🧭 Runtime-plane default for Web. Any time the user's request is framed around a page, a Web app, the frontend, React/Vue/Next/Nuxt, a dashboard UI, or "add AI to my H5", this skill is the default routing target. Do NOT first propose a Node.js / cloud-function / CloudRun proxy; @cloudbase/js-sdk can call the model from the browser directly. Only switch to ai-model-nodejs if the user explicitly asks for a backend/server call, image generation, or a scenario that truly needs server-side keys or long-running work. This decision is independent of which concrete model the user picks — model names (deepseek-*, glm-*, hunyuan-*, kimi-*, …) only affect the model field, not the routing plane.
Use it when you need to:
- Integrate AI text generation into a frontend Web app
- Stream AI responses for a better UX
- Call Hunyuan / DeepSeek / GLM / Kimi / MiniMax models from the browser
Do NOT use for:
- Node.js backend or cloud functions → use the
ai-model-nodejs skill
- WeChat Mini Program → use the
ai-model-wechat skill
- Image generation → use the
ai-model-nodejs skill (Node SDK only)
- Runtimes without a CloudBase SDK (native apps, Python, Go, etc.) → use the
http-api-cloudbase skill (it now includes the ai_model OpenAPI spec for direct HTTP calls; do NOT build a custom HTTP proxy)
⛔ STOP — ai.createModel(...) argument is not a vendor / model name
Read this before writing any createModel(...) line. The single most common mistake when agents generate code for this SDK is hallucinating the argument. There are exactly four legal shapes. Anything else is a bug.
✅ Legal ai.createModel(...) argument |
When to use it |
"cloudbase" |
The main managed group for new projects (TokenHub-backed, multi-vendor pool). Vendor + concrete model go into the model field of generateText / streamText, e.g. { model: "deepseek-v4.1-flash" }. No model is enabled by default — always check DescribeAIModels first and, if the target model is missing, enable it with UpdateAIModel before calling the SDK. |
"hunyuan-v3" |
Legacy plan group, being retired. Only hy3 is available and the platform adds no new models to it. Existing code keeps working — new code should use cloudbase + { model: "hy3" }. |
"hunyuan-exp" |
Only if DescribeAIModels explicitly returns this older legacy builtin group for the current env. Its original default model hunyuan-2.0-instruct-20251111 is offline (2026-05-31) — never target that id. |
"custom-<your-name>" |
A user-defined GroupName you onboarded via CreateAIModel. Must start with custom- (e.g. custom-kimi, custom-openai-compat). |
❌ Do NOT write any of these — they are all wrong
ai.createModel("deepseek") // wrong — that's a vendor, not a GroupName
ai.createModel("deepseek-v4.1-flash") // wrong — that's a model name, goes in the `model` field
ai.createModel("hunyuan") // wrong — vendor family, not a GroupName
ai.createModel("hunyuan-2.0-instruct-20251111") // wrong — model name
ai.createModel("glm") / ai.createModel("kimi") / ai.createModel("minimax") // wrong — vendor names
ai.createModel("openai") / ai.createModel("moonshot") // wrong — vendor names
ai.createModel("custom") // wrong — placeholder; use your real custom-<name>
ai.createModel(modelName) // wrong — do not reuse the variable that holds the model id
✅ Correct pattern — GroupName vs Model are two different fields
const model = ai.createModel("cloudbase"); // ← GroupName
await model.generateText({
model: "deepseek-v4.1-flash", // ← concrete model id
messages: [...]
});
Decision procedure (when the user names a specific model)
- The user says "use DeepSeek v3.2" / "use hunyuan instruct" / "use Kimi k2.6" / "use GLM-5" / …
createModel("cloudbase") stays the same.
- Put the model id into the
model field: { model: "deepseek-v4.1-flash" }, { model: "hy3" }, { model: "kimi-k2.6" }, { model: "glm-5.3" }, …
- Never assume the model is already enabled. Before writing the SDK call, verify it is present in
DescribeAIModels({ GroupName: "cloudbase" }).Models[]. If missing, call DescribeManagedAIModelList to confirm the exact Model name the platform supports (case-sensitive — do not guess the spelling), then enable it via UpdateAIModel with Status: 1 (remember Models is a full replacement, so resend everything already enabled + the new one).
If you are about to type ai.createModel( and the thing inside the parentheses is a vendor name, a model name, or a guess — stop. It is almost certainly one of the four legal values above.
Mandatory Two-Step Preflight (before any SDK code)
Before generating any AI-related SDK code, run the two-step preflight: ① eligibility, ② group readiness. Emitting createModel(...) straight away and letting the user debug runtime errors is significantly more costly.
Step 0: obtain the environment ID
Call the MCP tool queryEnv with action=info and read EnvId from the response. Every subsequent check and purchase link uses this EnvId.
Preflight ① — Eligibility (Token Credits resource pack)
Call the MCP tool:
callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId })
Pass conditions (all required):
envPostpayPackageInfoList contains at least one entry
That entry's postpayPackageId starts with pkg_tcb_tokencredits_
That entry's status is NOT in [3, 4] (3 / 4 typically mean expired / disabled; trust the live response)
❌ Not satisfied → stop writing code and surface this to the user (replace {region} with the environment's Region from queryEnv, e.g. ap-shanghai, and {envId} with the real id):
The current environment has no active Token Credits resource pack. Please purchase one before calling any AI API:
https://buy.cloud.tencent.com/CloudBase?buyType=resPack®ion={region}&envId={envId}
Let me know once it's done and I'll re-check the resource pack status.
✅ Satisfied → proceed to preflight ②.
Parameter casing is PascalCase by contract. If the call returns InvalidParameter, fall back to camelCase (envId / envPostpayPackageInfoList) and trust the live response. For the Mini Program scenario there is an additional growth-plan branch — switch to the ai-model-wechat skill.
Preflight ② — Group readiness (DescribeAIModels → UpdateAIModel if needed)
Eligibility alone is not enough. Do not write createModel("cloudbase") yet. First confirm that the target GroupName exists in the env with Status=1, and that the target Model is present in its Models[].
List groups configured in the current env:
callCloudApi(service="tcb", action="DescribeAIModels", params={ EnvId })
Returns AIModelGroups: AIModelGroup[], where each AIModelGroup includes GroupName, Type (builtin / custom), Models: [{ Model, EnableMCP, Tags }], Status (1 = on / 2 = off), BaseUrl, Secret, Remark. The main managed GroupName is cloudbase.
Never assume a model is already enabled. Inspect AIModelGroups[?].Models[].Model for the cloudbase group. If the target model (or, when the user did not specify one, the model you intend to default to such as deepseek-v4.1-flash) is missing, jump to step 4 and enable it — do not call createModel("cloudbase") yet. If the cloudbase group itself is missing or has Status=2, also jump to step 4.
User asked for a model that belongs to the managed catalog (e.g. deepseek-v4.1-flash, hy3, glm-5.3, kimi-k2.6, …): check whether that Model is already in the cloudbase group's Models[]. If not, jump to step 4. Do not guess the exact model id — verify the canonical spelling in DescribeManagedAIModelList first (step 4 covers this).
Enable / add a managed model (always inspect the authoritative catalog + pricing first):
callCloudApi(service="tcb", action="DescribeManagedAIModelList", params={ EnvId })
Returns ManagedAIModelGroup[], where each group lists GroupName (e.g. cloudbase), Remark, and Models: [{ Model, EnableMCP, ModelSpec{ContextLength, MaxInputToken, MaxOutputToken}, ModelChargingInfo[{Type, InputPrice, OutputPrice, InputOutputUnit, CachePrice}] }]. This is the single source of truth for supported model names and pricing — do not infer them from memory. Use the exact Model string returned here when calling UpdateAIModel. Also surface the prices to the user before enabling.
Then enable (note: Models is a full replacement — always resend the already-enabled models together with the new one):
callCloudApi(service="tcb", action="UpdateAIModel", params={
EnvId,
GroupName: "cloudbase",
Models: [
// resend every model that DescribeAIModels already showed as enabled
{ Model: "<already-enabled model, e.g. deepseek-v4.1-flash>" },
// append the newly-requested one, using the exact spelling from DescribeManagedAIModelList
{ Model: "<target model>" }
],
Status: 1
})
The requested model is not in the managed catalog (not found by DescribeManagedAIModelList) → jump to the next section, Custom onboarding (models outside the managed catalog).
All Actions use service=tcb, Version=2018-06-08. Parameters are PascalCase (EnvId / GroupName / Models / Status). Fall back to camelCase only if the call returns InvalidParameter.
Available Providers and Models
ai.createModel(<GroupName>) accepts exactly four kinds of legal values:
1. "cloudbase" — the main managed group (recommended)
GroupName: "cloudbase", Type: "builtin", Remark: "腾讯云开发" (Tencent CloudBase)
- Backed by Tencent Cloud TokenHub, a unified managed pool covering multiple vendors — Hunyuan (HY 2.0 Instruct, HY 2.0 Think, Hunyuan-role, Hy3 preview, …), DeepSeek (DeepSeek-V4-Pro, DeepSeek-V4-Flash, Deepseek-v3.2, Deepseek-v3.1, Deepseek-r1-0528, Deepseek-v3-0324, …), Zhipu GLM (GLM-5, GLM-5-Turbo, GLM-5.1, GLM-5V-Turbo), Kimi (K2.5, K2.6), MiniMax (M2.5, M2.7), and more. The roster evolves — do not hard-code specific SKUs in application code; discover at runtime.
- No model is enabled by default. Always call
DescribeAIModels first to see what the env has actually enabled; if your target model is missing, call DescribeManagedAIModelList for the authoritative catalog + pricing and then UpdateAIModel (Status: 1, Models full-replacement) to enable it before making the SDK call.
- Authoritative catalog + pricing:
DescribeManagedAIModelList
- Env-enabled set:
DescribeAIModels
2. "hunyuan-v3" — legacy plan group (being retired)
- Only
hy3; the group gets no new models and is on its way out. Migration target is cloudbase + { model: "hy3" }
- Still legal for existing code — do not "fix"
createModel("hunyuan-v3") into createModel("hy3"); hy3 is a model id, not a GroupName
- Mainly matters for Mini Program Growth Plan environments (see
ai-model-wechat)
3. "hunyuan-exp" — older legacy builtin group (kept for compatibility)
- Do not use it from Web unless the env explicitly still returns it (switch to the
ai-model-wechat skill for that flow)
- Its original default
hunyuan-2.0-instruct-20251111 went offline on 2026-05-31 — never target that model id. Whatever models the group still exposes must be read from DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]
4. User-defined GroupName
- Onboarded via
CreateAIModel (see the next section). The custom GroupName MUST start with custom- (e.g. custom-kimi, custom-moonshot, custom-openai-compat). This naming convention prevents future collisions with built-in / vendor GroupNames (cloudbase, hunyuan-exp, deepseek, glm, kimi, minimax, …) that the platform may introduce over time
- Examples:
createModel("custom-kimi"), createModel("custom-openai-compat")
Never write guesses like createModel("deepseek") or createModel("custom") unless DescribeAIModels explicitly returned that exact GroupName (old envs may still carry historical deepseek / hunyuan-exp builtin groups — that stays legal for compatibility, but new projects should always go through cloudbase).
Custom onboarding (models outside the managed catalog)
When the user wants to call a non-managed model (self-hosted, enterprise-internal, third-party OpenAI-compatible endpoint, …), do not block. Guide them through onboarding:
Option 1: console flow (recommended, user handles it)
https://tcb.cloud.tencent.com/dev?envId={envId}#/ai
Option 2: programmatic onboarding (CreateAIModel)
callCloudApi(service="tcb", action="CreateAIModel", params={
EnvId: "<envId>",
GroupName: "custom-<your-name>", // MUST start with "custom-" (e.g. custom-kimi, custom-openai-compat); never start with "cloudbase"
BaseUrl: "<OpenAI-compatible endpoint, e.g. https://api.moonshot.cn/v1>",
Models: [
{ Model: "<model name, e.g. kimi-k2.5>", EnableMCP: true }
],
Remark: "<optional remark>",
Status: 1,
Secret: { ApiKey: "<vendor api key supplied by the user>" }
})
Once onboarded, confirm with DescribeAIModels that the group is ready, then call ai.createModel("<the GroupName you just registered>") from your code. Use UpdateAIModel to add/remove models, rotate keys, or change BaseUrl (remember Models is a full replacement). Use DeleteAIModel to remove a custom group (builtin groups cannot be deleted).
Custom-model billing is covered by the third-party provider and does not draw from the Token Credits resource pack. Field casing follows the live contract — fall back to camelCase on InvalidParameter.
Installation
npm install @cloudbase/js-sdk
Initialization
⚠️ Do not use anonymous sign-in as the default. Anonymous login is disabled by default for new environments, and inactive existing environments have also been automatically disabled. Even when anonymous login is manually enabled, anonymous users are denied AI model invocation permissions by default. The AI-model skill does not prescribe a specific login UI — delegate that concern:
- Enabling / configuring login providers (phone SMS, email, WeChat Open Platform, username+password, OAuth, …) → follow the
auth-tool-cloudbase skill (backend config via callCloudApi).
- Building the actual sign-in flow in the browser (login form, callbacks, session guarding) → follow the
auth-web-cloudbase skill (@cloudbase/js-sdk auth API, e.g. signInWithPassword, signInWithPhone, getSession).
Do not fall back to signInAnonymously() for AI features — anonymous users cannot call AI models. Only use anonymous login for non-AI read-only demos where the user explicitly requests it and accepts the trade-off.
import cloudbase from "@cloudbase/js-sdk";
const app = cloudbase.init({
env: "<YOUR_ENV_ID>",
accessKey: import.meta.env.VITE_PUBLISHABLE_KEY // auto-provision via queryAppAuth / manageAppAuth, write to .env.local (see auth-web-cloudbase prerequisites)
});
const auth = app.auth;
// CRITICAL: Use auth.getSession() to check login — NOT the deprecated getLoginState().
// getLoginState() returns uid even without real login (just accessKey), causing false positives.
// getSession() returns data.session === undefined when no real login exists.
// Anonymous users are DENIED AI model permissions — calling AI without real login will fail.
const { data: sessionData } = await auth.getSession();
if (!sessionData?.session || sessionData.session.user?.is_anonymous) {
// No real login or anonymous session — route to sign-in page
window.location.href = "/login";
return;
}
const ai = app.ai();
Important notes:
- Use synchronous initialization with a top-level import
accessKey causes getLoginState() to return misleading auth data — the deprecated getLoginState() returns an object with uid even without real login, which breaks naive !!loginState checks. Use auth.getSession() instead: it returns data.session === undefined when no real login exists, so !!data.session is a reliable auth gate.
- The user MUST be authenticated with a verified login (phone, email, WeChat, username+password, custom) before using AI features. Anonymous users are denied AI model permissions. The exact flow is the responsibility of the
auth-web-cloudbase skill.
- Get
accessKey from the CloudBase console
generateText() — non-streaming
Prerequisite: the two-step preflight (eligibility + group readiness) has passed, and the target model has been confirmed present in DescribeAIModels({ GroupName: "cloudbase" }).Models[] — if it was not, it should already have been enabled via UpdateAIModel. The example below uses deepseek-v4.1-flash only for illustration; substitute the actual model the user asked for.
const model = ai.createModel("cloudbase");
const result = await model.generateText({
model: "deepseek-v4.1-flash", // must already be enabled in this env (DescribeAIModels → UpdateAIModel)
messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],
});
console.log(result.text); // generated text string
console.log(result.usage); // { prompt_tokens, completion_tokens, total_tokens }
console.log(result.messages); // full message history
console.log(result.rawResponses); // raw model responses
streamText() — streaming
Prerequisite: the two-step preflight has passed.
const model = ai.createModel("cloudbase");
const res = await model.streamText({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],
});
// Option 1: iterate the text stream (recommended)
for await (let text of res.textStream) {
console.log(text); // incremental text chunks
}
// Option 2: iterate the data stream for full response chunks
for await (let data of res.dataStream) {
console.log(data); // full response chunk with metadata
}
// Option 3: access final results
const messages = await res.messages; // full message history
const usage = await res.usage; // token usage
Error Handling Pattern
const model = ai.createModel("cloudbase");
try {
const result = await model.generateText({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "Generate a concise onboarding checklist." }],
});
console.log(result.text);
} catch (error) {
console.error("Failed to call CloudBase AI from Web", error);
}
Type Definitions
interface BaseChatModelInput {
model: string; // required: model name
messages: Array<ChatModelMessage>; // required: message array
temperature?: number; // optional: sampling temperature
topP?: number; // optional: nucleus sampling
}
type ChatModelMessage =
| { role: "user"; content: string }
| { role: "system"; content: string }
| { role: "assistant"; content: string };
interface GenerateTextResult {
text: string; // generated text
messages: Array<ChatModelMessage>; // full message history
usage: Usage; // token usage
rawResponses: Array<unknown>; // raw model responses
error?: unknown; // error if any
}
interface StreamTextResult {
textStream: AsyncIterable<string>; // incremental text stream
dataStream: AsyncIterable<DataChunk>; // full data stream
messages: Promise<ChatModelMessage[]>;// final message history
usage: Promise<Usage>; // final token usage
error?: unknown; // error if any
}
interface Usage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
}
Best Practices
- Run the two-step preflight first — ① eligibility (Token Credits resource pack via
DescribeEnvPostpayPackage) + ② group readiness (DescribeAIModels to inspect what is enabled, DescribeManagedAIModelList for the authoritative supported-model catalog, UpdateAIModel with a full-replacement Models[] and Status: 1 when the target model is missing). Skipping preflight leads straight to "model not found" / "model not enabled" errors at runtime.
- Never assume any model is already enabled — not
deepseek-v4.1-flash, not hunyuan-*, not anything. Always verify with DescribeAIModels first; if the target is missing, look up the exact Model string in DescribeManagedAIModelList (do not guess the spelling or invent vendor prefixes) and then UpdateAIModel to enable it.
createModel accepts exactly four kinds of values — "cloudbase" (the main managed group), "hunyuan-v3" (legacy plan group, only hy3, being retired), "hunyuan-exp" (older legacy builtin), or a user-defined GroupName registered via CreateAIModel (MUST start with custom-, e.g. custom-kimi, custom-openai-compat). Never guess with createModel("deepseek") / createModel("kimi") / createModel("custom").
- Do not invent SDK method names or parameters. This SKILL.md is the authoritative reference for
@cloudbase/js-sdk's AI surface — look up the method signature here (or in the Type Definitions section below) before writing code. If a method or field is not documented here, stop and ask, or check the live contract via the MCP tools. No guessing.
- Show pricing before enabling a new managed model —
DescribeManagedAIModelList returns ModelSpec (context length, max input/output tokens) + ModelChargingInfo (input / output / cache prices, billing unit). Surface the prices to the user before calling UpdateAIModel.
- Use streaming for long responses — better perceived latency and interactivity.
- Handle errors gracefully — wrap AI calls in try/catch.
- Keep
accessKey safe — use a publishable key, never a secret key.
- Initialize early — set up the SDK at app entry so auth and AI are both ready before routing.
- Do NOT use anonymous auth for AI features — anonymous login is disabled by default for new environments, and anonymous users are denied AI model permissions. Require a verified sign-in (phone, email, username+password, WeChat, custom) before calling any AI API. Delegate provider configuration to the
auth-tool-cloudbase skill and the browser sign-in flow to the auth-web-cloudbase skill; the AI-model skill checks auth.getSession() and verifies loginType before gating the call.
- Distinguish "preflight failure" from "model call failure" — the former means the user needs to buy a resource pack or call
UpdateAIModel; the latter is a prompt / parameter / network issue. Give the user different guidance for each.
- TypeScript: do NOT use
any to silence type errors from the SDK. The SDK ships its own types; if an error shows up, narrow with unknown + a type guard, write a precise interface for the shape you actually consume, or augment types in a local .d.ts. Never : any, as any, @ts-ignore, or @ts-nocheck. See the Engineering constitution in the web-development skill.
- Self-verify before claiming done. Run
tsc --noEmit + the project build + open the page with agent-browser and actually trigger the AI call. Confirm: (a) the text stream reaches the UI, (b) no new console errors, (c) result.usage is non-zero. Saying "it should work" without evidence is not acceptable — follow web-development/browser-testing.md.
1---2name: ai-model-web-43description: "Use this skill when a browser/Web app (React, Vue, Next, Nuxt, static sites, SPAs, dashboards, AI chat UI, 页面, 前端, 网页) needs AI models via @cloudbase/js-sdk. Default routing for Web/frontend AI — call directly from the browser, do NOT propose a Node.js proxy. Covers generateText and streamText; models via ai.createModel with groups cloudbase, the legacy hunyuan-v3 / hunyuan-exp, or custom-*, model id in the `model` field. MUST run two-step preflight before code — see body. NOT for Node.js backend (use ai-model-nodejs), Mini Program (use ai-model-wechat), or image generation (Node SDK only)."4version: 2.37.65license: MIT6alwaysApply: false7metadata:8 source: https://skillmd.com/skills/tencentcloudbase/ai-model-web-49---1011## Sibling skills (local only)1213Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.1415If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context.1617## When to use this skill1819Use this skill for **calling AI models in browser/Web applications** via `@cloudbase/js-sdk`.2021> 🧭 **Runtime-plane default for Web.** Any time the user's request is framed around a page, a Web app, the frontend, React/Vue/Next/Nuxt, a dashboard UI, or "add AI to my H5", this skill is the default routing target. **Do NOT first propose a Node.js / cloud-function / CloudRun proxy**; `@cloudbase/js-sdk` can call the model from the browser directly. Only switch to `ai-model-nodejs` if the user explicitly asks for a backend/server call, image generation, or a scenario that truly needs server-side keys or long-running work. This decision is independent of which concrete model the user picks — model names (`deepseek-*`, `glm-*`, `hunyuan-*`, `kimi-*`, …) only affect the `model` field, not the routing plane.2223**Use it when you need to:**2425- Integrate AI text generation into a frontend Web app26- Stream AI responses for a better UX27- Call Hunyuan / DeepSeek / GLM / Kimi / MiniMax models from the browser2829**Do NOT use for:**3031- Node.js backend or cloud functions → use the `ai-model-nodejs` skill32- WeChat Mini Program → use the `ai-model-wechat` skill33- Image generation → use the `ai-model-nodejs` skill (Node SDK only)34- Runtimes without a CloudBase SDK (native apps, Python, Go, etc.) → use the `http-api-cloudbase` skill (it now includes the `ai_model` OpenAPI spec for direct HTTP calls; do NOT build a custom HTTP proxy)3536---3738## ⛔ STOP — `ai.createModel(...)` argument is **not** a vendor / model name3940Read this before writing any `createModel(...)` line. The single most common mistake when agents generate code for this SDK is hallucinating the argument. There are **exactly four** legal shapes. Anything else is a bug.4142| ✅ Legal `ai.createModel(...)` argument | When to use it |43|----------------------------------------|----------------|44| `"cloudbase"` | **The main managed group for new projects** (TokenHub-backed, multi-vendor pool). Vendor + concrete model go into the **`model` field** of `generateText` / `streamText`, e.g. `{ model: "deepseek-v4.1-flash" }`. **No model is enabled by default — always check `DescribeAIModels` first and, if the target model is missing, enable it with `UpdateAIModel` before calling the SDK.** |45| `"hunyuan-v3"` | **Legacy plan group, being retired.** Only `hy3` is available and the platform adds no new models to it. Existing code keeps working — new code should use `cloudbase` + `{ model: "hy3" }`. |46| `"hunyuan-exp"` | Only if `DescribeAIModels` explicitly returns this older legacy builtin group for the current env. Its original default model `hunyuan-2.0-instruct-20251111` is **offline** (2026-05-31) — never target that id. |47| `"custom-<your-name>"` | A user-defined GroupName you onboarded via `CreateAIModel`. **Must** start with `custom-` (e.g. `custom-kimi`, `custom-openai-compat`). |4849### ❌ Do NOT write any of these — they are all wrong5051```js52ai.createModel("deepseek") // wrong — that's a vendor, not a GroupName53ai.createModel("deepseek-v4.1-flash") // wrong — that's a model name, goes in the `model` field54ai.createModel("hunyuan") // wrong — vendor family, not a GroupName55ai.createModel("hunyuan-2.0-instruct-20251111") // wrong — model name56ai.createModel("glm") / ai.createModel("kimi") / ai.createModel("minimax") // wrong — vendor names57ai.createModel("openai") / ai.createModel("moonshot") // wrong — vendor names58ai.createModel("custom") // wrong — placeholder; use your real custom-<name>59ai.createModel(modelName) // wrong — do not reuse the variable that holds the model id60```6162### ✅ Correct pattern — GroupName vs Model are two different fields6364```js65const model = ai.createModel("cloudbase"); // ← GroupName66await model.generateText({67 model: "deepseek-v4.1-flash", // ← concrete model id68 messages: [...]69});70```7172### Decision procedure (when the user names a specific model)73741. The user says "use DeepSeek v3.2" / "use hunyuan instruct" / "use Kimi k2.6" / "use GLM-5" / …752. `createModel("cloudbase")` stays the same.763. Put the model id into the **`model` field**: `{ model: "deepseek-v4.1-flash" }`, `{ model: "hy3" }`, `{ model: "kimi-k2.6" }`, `{ model: "glm-5.3" }`, …774. **Never assume the model is already enabled.** Before writing the SDK call, verify it is present in `DescribeAIModels({ GroupName: "cloudbase" }).Models[]`. If missing, call `DescribeManagedAIModelList` to confirm the exact `Model` name the platform supports (case-sensitive — do **not** guess the spelling), then enable it via `UpdateAIModel` with `Status: 1` (remember `Models` is a full replacement, so resend everything already enabled + the new one).7879> If you are about to type `ai.createModel(` and the thing inside the parentheses is a vendor name, a model name, or a guess — **stop**. It is almost certainly one of the four legal values above.8081---8283## Mandatory Two-Step Preflight (before any SDK code)8485Before generating any AI-related SDK code, **run the two-step preflight**: ① eligibility, ② group readiness. Emitting `createModel(...)` straight away and letting the user debug runtime errors is significantly more costly.8687### Step 0: obtain the environment ID8889Call the MCP tool `queryEnv` with `action=info` and read `EnvId` from the response. Every subsequent check and purchase link uses this `EnvId`.9091---9293### Preflight ① — Eligibility (Token Credits resource pack)9495Call the MCP tool:9697```98callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId })99```100101**Pass conditions (all required):**102- `envPostpayPackageInfoList` contains at least one entry103- That entry's `postpayPackageId` starts with `pkg_tcb_tokencredits_`104- That entry's `status` is NOT in `[3, 4]` (3 / 4 typically mean expired / disabled; trust the live response)105106- ❌ **Not satisfied** → **stop writing code** and surface this to the user (replace `{region}` with the environment's `Region` from `queryEnv`, e.g. `ap-shanghai`, and `{envId}` with the real id):107 > The current environment has no active Token Credits resource pack. Please purchase one before calling any AI API:108 > https://buy.cloud.tencent.com/CloudBase?buyType=resPack®ion={region}&envId={envId}109 >110 > Let me know once it's done and I'll re-check the resource pack status.111112- ✅ **Satisfied** → proceed to preflight ②.113114> Parameter casing is PascalCase by contract. If the call returns `InvalidParameter`, fall back to camelCase (`envId` / `envPostpayPackageInfoList`) and trust the live response. For the Mini Program scenario there is an additional growth-plan branch — switch to the `ai-model-wechat` skill.115116---117118### Preflight ② — Group readiness (`DescribeAIModels` → `UpdateAIModel` if needed)119120Eligibility alone is not enough. **Do not write `createModel("cloudbase")` yet.** First confirm that the target `GroupName` exists in the env with `Status=1`, and that the target `Model` is present in its `Models[]`.1211221. **List groups configured in the current env:**123124 ```125 callCloudApi(service="tcb", action="DescribeAIModels", params={ EnvId })126 ```127128 Returns `AIModelGroups: AIModelGroup[]`, where each `AIModelGroup` includes `GroupName`, `Type` (`builtin` / `custom`), `Models: [{ Model, EnableMCP, Tags }]`, `Status` (1 = on / 2 = off), `BaseUrl`, `Secret`, `Remark`. The main managed `GroupName` is `cloudbase`.1291302. **Never assume a model is already enabled.** Inspect `AIModelGroups[?].Models[].Model` for the `cloudbase` group. If the target model (or, when the user did not specify one, the model you intend to default to such as `deepseek-v4.1-flash`) is missing, jump to step 4 and enable it — do not call `createModel("cloudbase")` yet. If the `cloudbase` group itself is missing or has `Status=2`, also jump to step 4.1311323. **User asked for a model that belongs to the managed catalog** (e.g. `deepseek-v4.1-flash`, `hy3`, `glm-5.3`, `kimi-k2.6`, …): check whether that `Model` is already in the `cloudbase` group's `Models[]`. If not, jump to step 4. **Do not guess the exact model id** — verify the canonical spelling in `DescribeManagedAIModelList` first (step 4 covers this).1331344. **Enable / add a managed model** (always inspect the authoritative catalog + pricing first):135136 ```137 callCloudApi(service="tcb", action="DescribeManagedAIModelList", params={ EnvId })138 ```139140 Returns `ManagedAIModelGroup[]`, where each group lists `GroupName` (e.g. `cloudbase`), `Remark`, and `Models: [{ Model, EnableMCP, ModelSpec{ContextLength, MaxInputToken, MaxOutputToken}, ModelChargingInfo[{Type, InputPrice, OutputPrice, InputOutputUnit, CachePrice}] }]`. **This is the single source of truth for supported model names and pricing — do not infer them from memory. Use the exact `Model` string returned here when calling `UpdateAIModel`.** Also surface the prices to the user before enabling.141142 Then enable (note: `Models` is a **full replacement** — always resend the already-enabled models together with the new one):143144 ```145 callCloudApi(service="tcb", action="UpdateAIModel", params={146 EnvId,147 GroupName: "cloudbase",148 Models: [149 // resend every model that DescribeAIModels already showed as enabled150 { Model: "<already-enabled model, e.g. deepseek-v4.1-flash>" },151 // append the newly-requested one, using the exact spelling from DescribeManagedAIModelList152 { Model: "<target model>" }153 ],154 Status: 1155 })156 ```1571585. **The requested model is not in the managed catalog** (not found by `DescribeManagedAIModelList`) → jump to the next section, **Custom onboarding (models outside the managed catalog)**.159160> All Actions use `service=tcb`, `Version=2018-06-08`. Parameters are PascalCase (`EnvId` / `GroupName` / `Models` / `Status`). Fall back to camelCase only if the call returns `InvalidParameter`.161162---163164## Available Providers and Models165166`ai.createModel(<GroupName>)` accepts exactly four kinds of legal values:167168### 1. `"cloudbase"` — the main managed group (recommended)169170- `GroupName: "cloudbase"`, `Type: "builtin"`, `Remark: "腾讯云开发"` (Tencent CloudBase)171- Backed by **Tencent Cloud TokenHub**, a unified managed pool covering multiple vendors — **Hunyuan** (HY 2.0 Instruct, HY 2.0 Think, Hunyuan-role, Hy3 preview, …), **DeepSeek** (DeepSeek-V4-Pro, DeepSeek-V4-Flash, Deepseek-v3.2, Deepseek-v3.1, Deepseek-r1-0528, Deepseek-v3-0324, …), **Zhipu GLM** (GLM-5, GLM-5-Turbo, GLM-5.1, GLM-5V-Turbo), **Kimi** (K2.5, K2.6), **MiniMax** (M2.5, M2.7), and more. The roster evolves — **do not hard-code specific SKUs** in application code; discover at runtime.172- **No model is enabled by default.** Always call `DescribeAIModels` first to see what the env has actually enabled; if your target model is missing, call `DescribeManagedAIModelList` for the authoritative catalog + pricing and then `UpdateAIModel` (`Status: 1`, `Models` full-replacement) to enable it before making the SDK call.173- Authoritative catalog + pricing: `DescribeManagedAIModelList`174- Env-enabled set: `DescribeAIModels`175176### 2. `"hunyuan-v3"` — legacy plan group (being retired)177178- Only `hy3`; the group gets no new models and is on its way out. Migration target is `cloudbase` + `{ model: "hy3" }`179- Still legal for existing code — do **not** "fix" `createModel("hunyuan-v3")` into `createModel("hy3")`; `hy3` is a model id, not a GroupName180- Mainly matters for Mini Program Growth Plan environments (see `ai-model-wechat`)181182### 3. `"hunyuan-exp"` — older legacy builtin group (kept for compatibility)183184- Do not use it from Web unless the env explicitly still returns it (switch to the `ai-model-wechat` skill for that flow)185- Its original default `hunyuan-2.0-instruct-20251111` went **offline on 2026-05-31** — never target that model id. Whatever models the group still exposes must be read from `DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]`186187### 4. User-defined GroupName188189- Onboarded via `CreateAIModel` (see the next section). The custom `GroupName` **MUST start with `custom-`** (e.g. `custom-kimi`, `custom-moonshot`, `custom-openai-compat`). This naming convention prevents future collisions with built-in / vendor GroupNames (`cloudbase`, `hunyuan-exp`, `deepseek`, `glm`, `kimi`, `minimax`, …) that the platform may introduce over time190- Examples: `createModel("custom-kimi")`, `createModel("custom-openai-compat")`191192> **Never** write guesses like `createModel("deepseek")` or `createModel("custom")` unless `DescribeAIModels` explicitly returned that exact `GroupName` (old envs may still carry historical `deepseek` / `hunyuan-exp` builtin groups — that stays legal for compatibility, but new projects should always go through `cloudbase`).193194---195196## Custom onboarding (models outside the managed catalog)197198When the user wants to call a **non-managed** model (self-hosted, enterprise-internal, third-party OpenAI-compatible endpoint, …), **do not block**. Guide them through onboarding:199200### Option 1: console flow (recommended, user handles it)201202`https://tcb.cloud.tencent.com/dev?envId={envId}#/ai`203204### Option 2: programmatic onboarding (`CreateAIModel`)205206```207callCloudApi(service="tcb", action="CreateAIModel", params={208 EnvId: "<envId>",209 GroupName: "custom-<your-name>", // MUST start with "custom-" (e.g. custom-kimi, custom-openai-compat); never start with "cloudbase"210 BaseUrl: "<OpenAI-compatible endpoint, e.g. https://api.moonshot.cn/v1>",211 Models: [212 { Model: "<model name, e.g. kimi-k2.5>", EnableMCP: true }213 ],214 Remark: "<optional remark>",215 Status: 1,216 Secret: { ApiKey: "<vendor api key supplied by the user>" }217})218```219220Once onboarded, confirm with `DescribeAIModels` that the group is ready, then call `ai.createModel("<the GroupName you just registered>")` from your code. Use `UpdateAIModel` to add/remove models, rotate keys, or change `BaseUrl` (remember `Models` is a **full replacement**). Use `DeleteAIModel` to remove a custom group (builtin groups cannot be deleted).221222> Custom-model billing is covered by the third-party provider and does not draw from the Token Credits resource pack. Field casing follows the live contract — fall back to camelCase on `InvalidParameter`.223224---225226## Installation227228```bash229npm install @cloudbase/js-sdk230```231232## Initialization233234> ⚠️ **Do not use anonymous sign-in as the default.** Anonymous login is **disabled by default** for new environments, and inactive existing environments have also been automatically disabled. Even when anonymous login is manually enabled, **anonymous users are denied AI model invocation permissions by default**. The AI-model skill does **not** prescribe a specific login UI — delegate that concern:235>236> - **Enabling / configuring login providers** (phone SMS, email, WeChat Open Platform, username+password, OAuth, …) → follow the **`auth-tool-cloudbase`** skill (backend config via `callCloudApi`).237> - **Building the actual sign-in flow in the browser** (login form, callbacks, session guarding) → follow the **`auth-web-cloudbase`** skill (`@cloudbase/js-sdk` auth API, e.g. `signInWithPassword`, `signInWithPhone`, `getSession`).238>239> Do **not** fall back to `signInAnonymously()` for AI features — anonymous users cannot call AI models. Only use anonymous login for non-AI read-only demos where the user explicitly requests it and accepts the trade-off.240241```js242import cloudbase from "@cloudbase/js-sdk";243244const app = cloudbase.init({245 env: "<YOUR_ENV_ID>",246 accessKey: import.meta.env.VITE_PUBLISHABLE_KEY // auto-provision via queryAppAuth / manageAppAuth, write to .env.local (see auth-web-cloudbase prerequisites)247});248249const auth = app.auth;250251// CRITICAL: Use auth.getSession() to check login — NOT the deprecated getLoginState().252// getLoginState() returns uid even without real login (just accessKey), causing false positives.253// getSession() returns data.session === undefined when no real login exists.254// Anonymous users are DENIED AI model permissions — calling AI without real login will fail.255const { data: sessionData } = await auth.getSession();256if (!sessionData?.session || sessionData.session.user?.is_anonymous) {257 // No real login or anonymous session — route to sign-in page258 window.location.href = "/login";259 return;260}261262const ai = app.ai();263```264265**Important notes:**266267- Use synchronous initialization with a top-level import268- **`accessKey` causes `getLoginState()` to return misleading auth data** — the deprecated `getLoginState()` returns an object with `uid` even without real login, which breaks naive `!!loginState` checks. Use `auth.getSession()` instead: it returns `data.session === undefined` when no real login exists, so `!!data.session` is a reliable auth gate.269- The user MUST be authenticated with a verified login (phone, email, WeChat, username+password, custom) before using AI features. Anonymous users are denied AI model permissions. The exact flow is the responsibility of the `auth-web-cloudbase` skill.270- Get `accessKey` from the CloudBase console271272---273274## generateText() — non-streaming275276> **Prerequisite:** the two-step preflight (eligibility + group readiness) has passed, and the target model has been confirmed present in `DescribeAIModels({ GroupName: "cloudbase" }).Models[]` — if it was not, it should already have been enabled via `UpdateAIModel`. The example below uses `deepseek-v4.1-flash` only for illustration; substitute the actual model the user asked for.277278```js279const model = ai.createModel("cloudbase");280281const result = await model.generateText({282 model: "deepseek-v4.1-flash", // must already be enabled in this env (DescribeAIModels → UpdateAIModel)283 messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],284});285286console.log(result.text); // generated text string287console.log(result.usage); // { prompt_tokens, completion_tokens, total_tokens }288console.log(result.messages); // full message history289console.log(result.rawResponses); // raw model responses290```291292---293294## streamText() — streaming295296> **Prerequisite:** the two-step preflight has passed.297298```js299const model = ai.createModel("cloudbase");300301const res = await model.streamText({302 model: "deepseek-v4.1-flash",303 messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],304});305306// Option 1: iterate the text stream (recommended)307for await (let text of res.textStream) {308 console.log(text); // incremental text chunks309}310311// Option 2: iterate the data stream for full response chunks312for await (let data of res.dataStream) {313 console.log(data); // full response chunk with metadata314}315316// Option 3: access final results317const messages = await res.messages; // full message history318const usage = await res.usage; // token usage319```320321---322323## Error Handling Pattern324325```js326const model = ai.createModel("cloudbase");327328try {329 const result = await model.generateText({330 model: "deepseek-v4.1-flash",331 messages: [{ role: "user", content: "Generate a concise onboarding checklist." }],332 });333334 console.log(result.text);335} catch (error) {336 console.error("Failed to call CloudBase AI from Web", error);337}338```339340---341342## Type Definitions343344```ts345interface BaseChatModelInput {346 model: string; // required: model name347 messages: Array<ChatModelMessage>; // required: message array348 temperature?: number; // optional: sampling temperature349 topP?: number; // optional: nucleus sampling350}351352type ChatModelMessage =353 | { role: "user"; content: string }354 | { role: "system"; content: string }355 | { role: "assistant"; content: string };356357interface GenerateTextResult {358 text: string; // generated text359 messages: Array<ChatModelMessage>; // full message history360 usage: Usage; // token usage361 rawResponses: Array<unknown>; // raw model responses362 error?: unknown; // error if any363}364365interface StreamTextResult {366 textStream: AsyncIterable<string>; // incremental text stream367 dataStream: AsyncIterable<DataChunk>; // full data stream368 messages: Promise<ChatModelMessage[]>;// final message history369 usage: Promise<Usage>; // final token usage370 error?: unknown; // error if any371}372373interface Usage {374 prompt_tokens: number;375 completion_tokens: number;376 total_tokens: number;377}378```379380---381382## Best Practices3833841. **Run the two-step preflight first** — ① eligibility (Token Credits resource pack via `DescribeEnvPostpayPackage`) + ② group readiness (`DescribeAIModels` to inspect what is enabled, `DescribeManagedAIModelList` for the authoritative supported-model catalog, `UpdateAIModel` with a full-replacement `Models[]` and `Status: 1` when the target model is missing). Skipping preflight leads straight to "model not found" / "model not enabled" errors at runtime.3852. **Never assume any model is already enabled** — not `deepseek-v4.1-flash`, not `hunyuan-*`, not anything. Always verify with `DescribeAIModels` first; if the target is missing, look up the exact `Model` string in `DescribeManagedAIModelList` (do **not** guess the spelling or invent vendor prefixes) and then `UpdateAIModel` to enable it.3863. **`createModel` accepts exactly four kinds of values** — `"cloudbase"` (the main managed group), `"hunyuan-v3"` (legacy plan group, only `hy3`, being retired), `"hunyuan-exp"` (older legacy builtin), or a user-defined GroupName registered via `CreateAIModel` (**MUST start with `custom-`**, e.g. `custom-kimi`, `custom-openai-compat`). **Never** guess with `createModel("deepseek")` / `createModel("kimi")` / `createModel("custom")`.3874. **Do not invent SDK method names or parameters.** This SKILL.md is the authoritative reference for `@cloudbase/js-sdk`'s AI surface — look up the method signature here (or in the Type Definitions section below) before writing code. If a method or field is not documented here, stop and ask, or check the live contract via the MCP tools. No guessing.3885. **Show pricing before enabling a new managed model** — `DescribeManagedAIModelList` returns `ModelSpec` (context length, max input/output tokens) + `ModelChargingInfo` (input / output / cache prices, billing unit). Surface the prices to the user before calling `UpdateAIModel`.3896. **Use streaming for long responses** — better perceived latency and interactivity.3907. **Handle errors gracefully** — wrap AI calls in try/catch.3918. **Keep `accessKey` safe** — use a publishable key, never a secret key.3929. **Initialize early** — set up the SDK at app entry so auth and AI are both ready before routing.39310. **Do NOT use anonymous auth for AI features** — anonymous login is disabled by default for new environments, and anonymous users are denied AI model permissions. Require a verified sign-in (phone, email, username+password, WeChat, custom) before calling any AI API. Delegate provider configuration to the `auth-tool-cloudbase` skill and the browser sign-in flow to the `auth-web-cloudbase` skill; the AI-model skill checks `auth.getSession()` and verifies `loginType` before gating the call.39411. **Distinguish "preflight failure" from "model call failure"** — the former means the user needs to buy a resource pack or call `UpdateAIModel`; the latter is a prompt / parameter / network issue. Give the user different guidance for each.39512. **TypeScript: do NOT use `any` to silence type errors from the SDK.** The SDK ships its own types; if an error shows up, narrow with `unknown` + a type guard, write a precise `interface` for the shape you actually consume, or augment types in a local `.d.ts`. Never `: any`, `as any`, `@ts-ignore`, or `@ts-nocheck`. See the Engineering constitution in the `web-development` skill.39613. **Self-verify before claiming done.** Run `tsc --noEmit` + the project build + open the page with `agent-browser` and actually trigger the AI call. Confirm: (a) the text stream reaches the UI, (b) no new console errors, (c) `result.usage` is non-zero. Saying "it should work" without evidence is not acceptable — follow `web-development/browser-testing.md`.