ai-model-nodejs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用该技能

Use this skill for calling AI models in Node.js backend or CloudBase cloud functions using

@cloudbase/node-sdk

Use it when you need to:

Integrate AI text generation in backend services
Generate images with Hunyuan Image model
Call AI models from CloudBase cloud functions
Server-side AI processing

Do NOT use for:

Browser/Web apps → use
```
ai-model-web
```
skill
WeChat Mini Program → use
```
ai-model-wechat
```
skill
HTTP API integration → use
```
http-api
```
skill

当您需要在Node.js后端或CloudBase云函数中通过

@cloudbase/node-sdk

调用AI模型时，可使用该技能。

适用场景：

在后端服务中集成AI文本生成功能
使用Hunyuan Image模型生成图像
从CloudBase云函数中调用AI模型
服务端AI处理

不适用场景：

浏览器/网页应用 → 使用
```
ai-model-web
```
技能
微信小程序 → 使用
```
ai-model-wechat
```
技能
HTTP API集成 → 使用
```
http-api
```
技能

Available Providers and Models

可用的服务商与模型

CloudBase provides these built-in providers and models:

Provider Models Recommended

Provider	Models	Recommended
`hunyuan-exp`	`hunyuan-turbos-latest` , `hunyuan-t1-latest` , `hunyuan-2.0-thinking-20251109` , `hunyuan-2.0-instruct-20251111`	✅ `hunyuan-2.0-instruct-20251111`
`deepseek`	`deepseek-r1-0528` , `deepseek-v3-0324` , `deepseek-v3.2`	✅ `deepseek-v3.2`

hunyuan-exp

hunyuan-turbos-latest

hunyuan-t1-latest

hunyuan-2.0-thinking-20251109

hunyuan-2.0-instruct-20251111

✅

hunyuan-2.0-instruct-20251111

deepseek

deepseek-r1-0528

deepseek-v3-0324

deepseek-v3.2

✅

deepseek-v3.2

CloudBase提供以下内置服务商与模型：

服务商模型推荐使用

服务商	模型	推荐使用
`hunyuan-exp`	`hunyuan-turbos-latest` , `hunyuan-t1-latest` , `hunyuan-2.0-thinking-20251109` , `hunyuan-2.0-instruct-20251111`	✅ `hunyuan-2.0-instruct-20251111`
`deepseek`	`deepseek-r1-0528` , `deepseek-v3-0324` , `deepseek-v3.2`	✅ `deepseek-v3.2`

hunyuan-exp

hunyuan-turbos-latest

hunyuan-t1-latest

hunyuan-2.0-thinking-20251109

hunyuan-2.0-instruct-20251111

✅

hunyuan-2.0-instruct-20251111

deepseek

deepseek-r1-0528

deepseek-v3-0324

deepseek-v3.2

✅

deepseek-v3.2

Installation

安装

bash

npm install @cloudbase/node-sdk

⚠️ AI feature requires version 3.16.0 or above. Check with

npm list @cloudbase/node-sdk

bash

npm install @cloudbase/node-sdk

⚠️ AI功能需要3.16.0及以上版本，可通过

npm list @cloudbase/node-sdk

查看当前版本。

Initialization

初始化

In Cloud Functions

在云函数中

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });

exports.main = async (event, context) => {
  const ai = app.ai();
  // Use AI features
};

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });

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

Cloud Function Configuration for AI Models

AI模型的云函数配置

⚠️ Important: When creating cloud functions that use AI models (especially

generateImage()

and large language model generation), set a longer timeout as these operations can be slow.

Using MCP Tool
createFunction
:

Set the

timeout

parameter in the

func

object:

Parameter:
```
func.timeout
```
(number)
Unit: seconds
Range: 1 - 900
Default: 20 seconds (usually too short for AI operations)

Recommended timeout values:

Text generation (
generateText
): 60-120 seconds
Streaming (
streamText
): 60-120 seconds
Image generation (
generateImage
): 300-900 seconds (recommended: 900s)
Combined operations: 900 seconds (maximum allowed)

⚠️ 重要提示：创建使用AI模型的云函数时（尤其是调用

generateImage()

和大语言模型生成功能），需设置更长的超时时间，因为这些操作耗时可能较长。

使用MCP工具
createFunction
：

在

func

对象中设置

timeout

参数：

参数：
```
func.timeout
```
（数字类型）
单位：秒
范围：1 - 900
默认值：20秒（通常对于AI操作来说过短）

推荐超时时间：

文本生成（
generateText
）：60-120秒
流式输出（
streamText
）：60-120秒
图像生成（
generateImage
）：300-900秒（推荐设置为900秒）
组合操作：900秒（允许的最大值）

In Regular Node.js Server

在常规Node.js服务器中

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
  env: '<YOUR_ENV_ID>',
  secretId: '<YOUR_SECRET_ID>',
  secretKey: '<YOUR_SECRET_KEY>'
});

const ai = app.ai();

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
  env: '<YOUR_ENV_ID>',
  secretId: '<YOUR_SECRET_ID>',
  secretKey: '<YOUR_SECRET_KEY>'
});

const ai = app.ai();

generateText() - Non-streaming

generateText() - 非流式文本生成

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

const result = await model.generateText({
  model: "hunyuan-2.0-instruct-20251111",  // Recommended model
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

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

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

const result = await model.generateText({
  model: "hunyuan-2.0-instruct-20251111",  // 推荐使用的模型
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

console.log(result.text);           // 生成的文本字符串
console.log(result.usage);          // { prompt_tokens, completion_tokens, total_tokens }
console.log(result.messages);       // 完整的消息历史
console.log(result.rawResponses);   // 模型原始响应

streamText() - Streaming

streamText() - 流式文本生成

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

const res = await model.streamText({
  model: "hunyuan-2.0-instruct-20251111",  // Recommended model
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

// Option 1: Iterate text stream (recommended)
for await (let text of res.textStream) {
  console.log(text);  // Incremental text chunks
}

// Option 2: Iterate data stream for full response data
for await (let data of res.dataStream) {
  console.log(data);  // Full response chunk with metadata
}

// Option 3: Get final results
const messages = await res.messages;  // Full message history
const usage = await res.usage;        // Token usage

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

const res = await model.streamText({
  model: "hunyuan-2.0-instruct-20251111",  // 推荐使用的模型
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

// 方式1：遍历文本流（推荐）
for await (let text of res.textStream) {
  console.log(text);  // 增量文本片段
}

// 方式2：遍历数据流获取完整响应数据
for await (let data of res.dataStream) {
  console.log(data);  // 包含元数据的完整响应片段
}

// 方式3：获取最终结果
const messages = await res.messages;  // 完整消息历史
const usage = await res.usage;        // Token使用情况

generateImage() - Image Generation

generateImage() - 图像生成

⚠️ Image generation is only available in Node SDK, not in JS SDK (Web) or WeChat Mini Program.

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

const res = await imageModel.generateImage({
  model: "hunyuan-image",
  prompt: "一只可爱的猫咪在草地上玩耍",
  size: "1024x1024",
  version: "v1.9",
});

console.log(res.data[0].url);           // Image URL (valid 24 hours)
console.log(res.data[0].revised_prompt);// Revised prompt if revise=true

⚠️ 图像生成仅在Node SDK中可用，JS SDK（网页端）或微信小程序不支持该功能。

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

const res = await imageModel.generateImage({
  model: "hunyuan-image",
  prompt: "一只可爱的猫咪在草地上玩耍",
  size: "1024x1024",
  version: "v1.9",
});

console.log(res.data[0].url);           // 图片URL（24小时内有效）
console.log(res.data[0].revised_prompt);// 若revise=true，返回修改后的prompt

Image Generation Parameters

图像生成参数

interface HunyuanGenerateImageInput {
  model: "hunyuan-image";      // Required
  prompt: string;                       // Required: image description
  version?: "v1.8.1" | "v1.9";         // Default: "v1.8.1"
  size?: string;                        // Default: "1024x1024"
  negative_prompt?: string;             // v1.9 only
  style?: string;                       // v1.9 only
  revise?: boolean;                     // Default: true
  n?: number;                           // Default: 1
  footnote?: string;                    // Watermark, max 16 chars
  seed?: number;                        // Range: [1, 4294967295]
}

interface HunyuanGenerateImageOutput {
  id: string;
  created: number;
  data: Array<{
    url: string;                        // Image URL (24h valid)
    revised_prompt?: string;
  }>;
}

interface HunyuanGenerateImageInput {
  model: "hunyuan-image";      // 必填
  prompt: string;                       // 必填：图像描述
  version?: "v1.8.1" | "v1.9";         // 默认值："v1.8.1"
  size?: string;                        // 默认值："1024x1024"
  negative_prompt?: string;             // 仅v1.9版本支持
  style?: string;                       // 仅v1.9版本支持
  revise?: boolean;                     // 默认值：true
  n?: number;                           // 默认值：1
  footnote?: string;                    // 水印，最多16个字符
  seed?: number;                        // 范围：[1, 4294967295]
}

interface HunyuanGenerateImageOutput {
  id: string;
  created: number;
  data: Array<{
    url: string;                        // 图片URL（24小时内有效）
    revised_prompt?: string;
  }>;
}

Type Definitions

类型定义

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;
}

interface BaseChatModelInput {
  model: string;                        // 必填：模型名称
  messages: Array<ChatModelMessage>;    // 必填：消息数组
  temperature?: number;                 // 可选：采样温度
  topP?: number;                        // 可选：核采样参数
}

type ChatModelMessage =
  | { role: "user"; content: string }
  | { role: "system"; content: string }
  | { role: "assistant"; content: string };

interface GenerateTextResult {
  text: string;                         // 生成的文本
  messages: Array<ChatModelMessage>;    // 完整消息历史
  usage: Usage;                         // Token使用情况
  rawResponses: Array<unknown>;         // 模型原始响应
  error?: unknown;                      // 错误信息（若有）
}

interface StreamTextResult {
  textStream: AsyncIterable<string>;    // 增量文本流
  dataStream: AsyncIterable<DataChunk>; // 完整数据流
  messages: Promise<ChatModelMessage[]>;// 最终消息历史
  usage: Promise<Usage>;                // 最终Token使用情况
  error?: unknown;                      // 错误信息（若有）
}

interface Usage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}