跳到主要内容

Node SDK 调用

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

在线示例
在 CodeSandbox 中打开完整示例代码 →

准备工作​

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

安装​

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); // 完整消息历史

返回值​

属性类型说明
textstring生成的文本
messagesChatModelMessage[]完整消息历史
usageUsageToken 使用量
rawResponsesunknown[]原始模型响应
errorunknown错误信息（如有）

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;

返回值​

属性类型说明
textStreamAsyncIterable<string>增量文本流
dataStreamAsyncIterable<DataChunk>完整数据流
messagesPromise<ChatModelMessage[]>最终消息历史
usagePromise<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 }
});

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

图片生成参数​

参数类型必填说明
modelstring是模型名称，HY-Image-3.0-Plus-4090-Tob-v1.0（文生图）或 HY-Image-v3.0-I2I-ToB-v1.0.1（图生图）
promptstring是图片描述，不超过 8192 字符
sizestring否图片尺寸，格式 "宽x高"，默认 1024x1024，宽高范围 [512, 2048]，面积不超过 1024x1024
seednumber否生成种子，仅当生成 1 张图片时生效，范围 [1, 4294967295]
footnotestring否自定义水印内容，限制 16 字符，显示在图片右下角
revise{ value: boolean }否是否改写 prompt，默认开启，改写会增加约 30s 耗时

返回值​

属性类型说明
idstring请求 ID
creatednumber时间戳
data[].urlstring图片 URL（24 小时有效）
data[].revised_promptstring改写后的 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"
  });

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

与 Web SDK 的差异​

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