ai-model-web

---

name: ai-model-web description: "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, 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)." version: 2.34.8 alwaysApply: false

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 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). |

❌ 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-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-flash",                       // ← concrete model id
  messages: [...]
});

Decision procedure (when the user names a specific model)

1. The user says "use DeepSeek v3.2" / "use hunyuan instruct" / "use Kimi k2.6" / "use GLM-5" / …
2. createModel("cloudbase") stays the same.
3. Put the model id into the model field: { model: "deepseek-v3.2" }, { model: "hunyuan-2.0-instruct-20251111" }, { model: "kimi-k2.6" }, { model: "glm-5" }, …
4. 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 three 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 (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 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[].

1. 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.

2. 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.

3. 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).

4. 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
   })
   

5. 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 three 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-exp" — legacy builtin group (kept for compatibility)

• Primarily relevant to the Mini Program Growth Plan scenario; do not use from Web unless the env explicitly still has it (switch to the `ai-m