Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From cloudbase
Calls AI models (DeepSeek, Hunyuan, GLM, Kimi, MiniMax) from browser/Web apps via @cloudbase/js-sdk with generateText and streamText. Default for frontend AI. Do NOT propose Node.js proxy.
npx claudepluginhub tencentcloudbase/cloudbase-mcp --plugin cloudbaseHow this skill is triggered — by the user, by Claude, or both
Slash command
/cloudbase:ai-model-webThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
If this environment only installed the current skill, start from the CloudBase main entry and use the published `cloudbase/references/...` paths for sibling skills.
Node.js backend AI via @cloudbase/node-sdk — cloud functions, CloudRun, Express, Koa, NestJS, serverless APIs, scheduled jobs, LLM proxies. Supports image generation (Hunyuan Image) and text models (DeepSeek, GLM, Hunyuan, Kimi).
Provides Next.js integration patterns with Modal.com for AI inference, GPU workloads, video/audio processing, background jobs, webhooks, file uploads, and heavy compute offloading from Vercel.
Builds focused AI wrapper products around OpenAI and Anthropic APIs into paid tools solving specific problems. Covers architecture, prompt engineering, cost optimization, model selection, and UX patterns.
Share bugs, ideas, or general feedback.
If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.
https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.mdhttps://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ai-model-web/SKILL.mdKeep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.
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-sdkcan call the model from the browser directly. Only switch toai-model-nodejsif 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 themodelfield, not the routing plane.
Use it when you need to:
Do NOT use for:
ai-model-nodejs skillai-model-wechat skillai-model-nodejs skill (Node SDK only)http-api skill (it now includes the ai_model OpenAPI spec for direct HTTP calls; do NOT build a custom HTTP proxy)ai.createModel(...) argument is not a vendor / model nameRead 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 three 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-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-exp" | Only if DescribeAIModels explicitly returns this legacy builtin group for the current env (mainly the Mini Program Growth Plan — see ai-model-wechat). |
"custom-<your-name>" | A user-defined GroupName you onboarded via CreateAIModel. Must start with custom- (e.g. custom-kimi, custom-openai-compat). |
ai.createModel("deepseek") // wrong — that's a vendor, not a GroupName
ai.createModel("deepseek-v4-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
const model = ai.createModel("cloudbase"); // ← GroupName
await model.generateText({
model: "deepseek-v4-flash", // ← concrete model id
messages: [...]
});
createModel("cloudbase") stays the same.model field: { model: "deepseek-v3.2" }, { model: "hunyuan-2.0-instruct-20251111" }, { model: "kimi-k2.6" }, { model: "glm-5" }, …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 three legal values above.
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.
Call the MCP tool envQuery with action=info and read EnvId from the response. Every subsequent check and purchase link uses this EnvId.
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 (replacing {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/lowcode?buyType=resPack&envId={envId}&resourceType=token
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 theai-model-wechatskill.
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-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-v3.2, hunyuan-2.0-instruct-20251111, glm-5, 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-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 returnsInvalidParameter.
ai.createModel(<GroupName>) accepts exactly three kinds of legal values:
"cloudbase" — the main managed group (recommended)GroupName: "cloudbase", Type: "builtin", Remark: "腾讯云开发" (Tencent CloudBase)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.DescribeManagedAIModelListDescribeAIModels"hunyuan-exp" — legacy builtin group (kept for compatibility)ai-model-wechat skill for that flow)hunyuan-2.0-instruct-20251111; additional hunyuan SKUs must be discovered at runtime via DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] — do not hard-code other IDsCreateAIModel (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 timecreateModel("custom-kimi"), createModel("custom-openai-compat")Never write guesses like
createModel("deepseek")orcreateModel("custom")unlessDescribeAIModelsexplicitly returned that exactGroupName(old envs may still carry historicaldeepseek/hunyuan-expbuiltin groups — that stays legal for compatibility, but new projects should always go throughcloudbase).
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:
https://tcb.cloud.tencent.com/dev?envId={envId}#/ai
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.
npm install @cloudbase/js-sdk
⚠️ 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-toolskill (backend config viacallCloudApi).- Building the actual sign-in flow in the browser (login form, callbacks, session guarding) → follow the
auth-webskill (@cloudbase/js-sdkauth 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: "<YOUR_PUBLISHABLE_KEY>" // Get it from the CloudBase console
});
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:
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.auth-web skill.accessKey from the CloudBase consolePrerequisite: 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 viaUpdateAIModel. The example below usesdeepseek-v4-flashonly for illustration; substitute the actual model the user asked for.
const model = ai.createModel("cloudbase");
const result = await model.generateText({
model: "deepseek-v4-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
Prerequisite: the two-step preflight has passed.
const model = ai.createModel("cloudbase");
const res = await model.streamText({
model: "deepseek-v4-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
const model = ai.createModel("cloudbase");
try {
const result = await model.generateText({
model: "deepseek-v4-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);
}
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;
}
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.deepseek-v4-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 three kinds of values — "cloudbase" (the main managed group), "hunyuan-exp" (legacy builtin, Growth Plan scenarios), 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").@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.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.accessKey safe — use a publishable key, never a secret key.auth-tool skill and the browser sign-in flow to the auth-web skill; the AI-model skill checks auth.getSession() and verifies loginType before gating the call.UpdateAIModel; the latter is a prompt / parameter / network issue. Give the user different guidance for each.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.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.