Node SDK 调用

通过 @cloudbase/node-sdk 在 Node.js 服务端（如云函数、云托管）调用 CloudBase AI 大模型，支持文本生成、流式输出、图片生成等能力。

在线示例

准备工作

已创建云开发环境（旧套餐可升级），并已启用模型开关（见接入大模型）

安装

npm install @cloudbase/node-sdk

版本要求

Node SDK 调用混元生图模型需要 @cloudbase/node-sdk >= 3.18.3；其依赖的 @cloudbase/ai >= 2.30.0（该版本已内置 HY-Image-3.0-Plus-4090-Tob-v1.0 模型配置）。请检查版本：npm list @cloudbase/ai

初始化

云函数中使用

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "您的环境ID",
  timeout: 60000 // AI 生成可能耗时较长，建议设置较长超时时间
});

exports.main = async (event, context) => {
  const ai = app.ai();
  // 使用 AI 功能
};

独立 Node.js 服务中使用

const tcb = require("@cloudbase/node-sdk");

const app = tcb.init({
  env: "您的环境ID",
  secretId: "<YOUR_SECRET_ID>",
  secretKey: "<YOUR_SECRET_KEY>",
  timeout: 60000 // 设置超时时间为 60 秒，AI 生成可能耗时较长
});

const ai = app.ai();

密钥获取地址：腾讯云 API 密钥管理

超时配置

AI 模型生成文本可能需要较长时间，建议将 timeout 设置为 60000（60 秒）或更高，避免请求超时。

文本生成

generateText() - 非流式

一次性返回完整结果。

const model = ai.createModel("cloudbase");

const result = await model.generateText({
  model: "hy3",
  messages: [{ role: "user", content: "介绍一下李白" }],
});

console.log(result.text);     // 生成的文本
console.log(result.usage);    // Token 使用量
console.log(result.messages); // 完整消息历史

返回值

属性	类型	说明
text	string	生成的文本
messages	ChatModelMessage[]	完整消息历史
usage	Usage	Token 使用量
rawResponses	unknown[]	原始模型响应
error	unknown	错误信息（如有）

streamText() - 流式

流式返回文本，适用于实时对话场景。

const model = ai.createModel("cloudbase");

const res = await model.streamText({
  model: "hy3",
  messages: [{ role: "user", content: "介绍一下李白" }],
});

// 方式一：迭代文本流（推荐）
for await (const text of res.textStream) {
  console.log(text);  // 增量文本
}

// 方式二：迭代数据流，获取完整响应数据
for await (const data of res.dataStream) {
  console.log(data);  // 包含 choices、usage 等完整信息
}

// 获取最终结果
const messages = await res.messages;
const usage = await res.usage;

返回值

属性	类型	说明
textStream	AsyncIterable<string>	增量文本流
dataStream	AsyncIterable<DataChunk>	完整数据流
messages	Promise<ChatModelMessage[]>	最终消息历史
usage	Promise<Usage>	最终 Token 使用量

图片生成

仅 Node SDK 支持

图片生成功能仅在 Node SDK 中可用，Web SDK 和小程序均不支持。

const imageModel = ai.createImageModel("hunyuan-image");

const res = await imageModel.generateImage({
  model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
  prompt: "一只可爱的猫咪在草地上玩耍",
  size: "1280x720",
  revise: { value: true },
  enable_thinking: { value: false }
});

console.log(res.data[0].url);           // 图片 URL（24 小时有效）
console.log(res.data[0].revised_prompt); // 改写后的 prompt

图片生成参数

参数	类型	必填	说明
model	string	是	模型名称，`HY-Image-3.0-Plus-4090-Tob-v1.0`（推荐）或 `hunyuan-image-v3.0-v1.0.1`
prompt	string	是	图片描述，不超过 8192 字符
size	string	否	图片尺寸，格式 `"宽x高"`，默认 `1024x1024`，宽高范围 [512, 2048]，面积不超过 1024x1024
seed	number	否	生成种子，仅当生成 1 张图片时生效，范围 [1, 4294967295]
footnote	string	否	自定义水印内容，限制 16 字符，显示在图片右下角
revise	`{ value: boolean }`	否	是否改写 prompt，默认开启，改写会增加约 30s 耗时
enable_thinking	`{ value: boolean }`	否	改写时是否开启 thinking 模式，默认开启，效果更好但耗时增加（最大 60s）

返回值

属性	类型	说明
id	string	请求 ID
created	number	时间戳
data[].url	string	图片 URL（24 小时有效）
data[].revised_prompt	string	改写后的 prompt

图生文（视觉理解）

使用支持视觉的模型（如 hunyuan-vision）理解图片内容。

提示

需要先配置自定义模型 hunyuan-custom，填写混元大模型的 BaseURL 和 API Key。

const model = ai.createModel("hunyuan-custom");

const res = await model.streamText({
  model: "hunyuan-vision",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "这张图片的内容是什么？" },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/image.png"
          }
        }
      ]
    }
  ]
});

for await (const text of res.textStream) {
  console.log(text);
}

完整示例

云函数：AI 聊天接口

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "您的环境ID",
  timeout: 60000 // AI 生成可能耗时较长
});

exports.main = async (event, context) => {
  const { messages } = event;
  
  const ai = app.ai();
  const model = ai.createModel("cloudbase");

  try {
    const result = await model.generateText({
      model: "hy3",
      messages
    });

    return {
      success: true,
      text: result.text,
      usage: result.usage
    };
  } catch (error) {
    return {
      success: false,
      error: error.message
    };
  }
};

云函数：流式响应（SSE）

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "您的环境ID",
  timeout: 60000 // AI 生成可能耗时较长
});

exports.main = async (event, context) => {
  const { messages } = event;
  
  const ai = app.ai();
  const model = ai.createModel("cloudbase");

  const res = await model.streamText({
    model: "hy3",
    messages
  });

  // 收集完整文本
  let fullText = "";
  for await (const text of res.textStream) {
    fullText += text;
  }

  const usage = await res.usage;

  return {
    text: fullText,
    usage
  };
};

云函数：图片生成

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({
  env: "您的环境ID",
  timeout: 60000 // 图片生成可能耗时较长
});

exports.main = async (event, context) => {
  const { prompt } = event;

  const ai = app.ai();
  const imageModel = ai.createImageModel("hunyuan-image");

  const res = await imageModel.generateImage({
    model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
    prompt,
    size: "1280x720",
    enable_thinking: { value: false }
  });

  return {
    url: res.data[0].url,
    revisedPrompt: res.data[0].revised_prompt
  };
};

与 Web SDK 的差异

特性	Node SDK	Web SDK
初始化	`tcb.init()`	`cloudbase.init()`
认证方式	密钥或云函数环境	Publishable Key + 登录
图片生成	支持	不支持
运行环境	服务端	浏览器

准备工作​

安装​

初始化​

云函数中使用​

独立 Node.js 服务中使用​

文本生成​

generateText() - 非流式​

返回值​

streamText() - 流式​

返回值​

图片生成​

图片生成参数​

返回值​

图生文（视觉理解）​

完整示例​

云函数：AI 聊天接口​

云函数：流式响应（SSE）​

云函数：图片生成​

与 Web SDK 的差异​

准备工作

安装

初始化

云函数中使用

独立 Node.js 服务中使用

文本生成

generateText() - 非流式

返回值

streamText() - 流式

返回值

图片生成

图片生成参数

返回值

图生文（视觉理解）

完整示例

云函数：AI 聊天接口

云函数：流式响应（SSE）

云函数：图片生成

与 Web SDK 的差异