用途:在 Node.js 服务端调用 AI 模型,适用于云函数、CloudRun、Express/Koa/NestJS 服务、无服务器 API、定时任务、智能体编排与批量作业等必须把密钥留在服务端的场景。图像生成仅该 SDK 支持。若为网页/前端 AI 对话界面应改用 ai-model-web,微信小程序改用 ai-model-wechat,非 CloudBase SDK 运行时(Python、Go、PHP、curl 等)改用 http-api-cloudbase。
主要能力:文本生成 generateText、流式 streamText、图像生成 generateImage(createImageModel("hunyuan-image"))。createModel 只接受三种合法取值:"cloudbase"(主托管组,多厂商池)、"hunyuan-exp"(旧内置组,仅在 DescribeAIModels 返回时使用)、以 custom- 开头的自定义 GroupName。厂商名或具体模型 id 不能作为 createModel 参数,模型 id 应放入 generateText/streamText 的 model 字段。
使用方式:安装 npm install @cloudbase/node-sdk,需 3.16.0 及以上。云函数内用 tcb.init({ env }) 后取 app.ai();普通 Node 服务需传 secretId、secretKey。调用前须完成两步预检:① 用 queryEnv 取 EnvId,再 callCloudApi(service="tcb", action="DescribeEnvPostpayPackage") 确认存在 pkg_tcb_tokencredits_ 开头且状态非 3/4 的 Token Credits 资源包;② 用 DescribeAIModels 确认目标组与模型已启用,缺失时先用 DescribeManagedAIModelList 查权威模型名与价格,再用 UpdateAIModel(Models 为全量替换,Status: 1)启用。
限制:默认不启用任何模型;模型名区分大小写,不可猜测。云函数需设置较长超时,文本/流式建议 60–120 秒,图像生成建议 900 秒;HTTP 函数网关上限 60 秒,需异步任务加轮询。自定义模型由第三方计费,不消耗 Token Credits。方法签名以 api-reference.md 为准,未文档化则不应臆测。