wx.cloud.extend.AI

支持端：小程序、云函数

微信小程序基础库版本 3.15.1 及以上，支持通过微信云开发的 wx.cloud.extend.AI 扩展接口调用 cloudbase 提供的 DeepSeek、混元、Kimi、GLM、Minimax 等最新模型。

初始化

在使用 AI 相关能力前，需要传入云开发环境进行初始化。

wx.cloud.init({
  env: "<你的环境ID>",
});

初始化完毕后，即可通过 wx.cloud.extend.AI 使用扩展接口来调用 AI 相关能力。

大模型

AI.createModel()

创建指定的 AI 模型。

使用示例

传入模型提供商字符串：

const model = wx.cloud.extend.AI.createModel("cloudbase");

传入 ModelDefinition 对象（基础库 3.15.1 及以上支持）：

const model = wx.cloud.extend.AI.createModel({
  modelName: "custom-model",
  modelPath: "/v1/chat/completions",
  extractPath: "choices[0].delta.content",
  reasoningPath: "choices[0].delta.reasoning_content",
});

类型声明

function createModel(model: string | ModelDefinition): ChatModel;

interface ModelDefinition {
  modelName: string;
  modelPath: string;
  extractPath: string;
  reasoningPath?: string;
}

参数

返回一个提供 AI 生成文本能力的对象。

ChatModel.streamText()

以流式调用大模型生成文本。流式调用时，生成的文本及其他响应数据会通过 SSE 返回，该接口的返回值对 SSE 做了不同程度的封装，开发者能根据实际需求获取到文本流和完整数据流。

streamText 使用示例

// 连接模型提供商
const provider = wx.cloud.extend.AI.createModel("cloudbase"); 
const res = await provider.streamText({
  data: {
    model: "hy3-preview",
    messages: [
      {
        role: "user",
        content: "hi"
      }
    ]
  }
});

for await (let str of res.textStream) {
  // 打印生成的文本
  console.log(str); 
}
for await (let event of res.eventStream) {
  // 打印每次返回的完整数据
  console.log(event); 

  // 当大模型结束传输时，通常会发一条 [DONE] 数据，在此之后即可停止循环
  if (event.data === "[DONE]") {
    break;
  }
}

streamText 类型声明

function streamText(props: StreamTextInput): Promise<StreamTextResult>;

interface StreamTextResult {
  eventStream: EventStream;
  textStream: TextStream;
}

interface StreamTextInput {
  data: unknown;
  onEvent?: OnEvent;
  onText?: OnText;
  onFinish?: OnFinish;
}

interface OnEvent {
  (prop: { data: string }): unknown;
}

interface OnText {
  (text: string): unknown;
}

interface OnFinish {
  (text: string): unknown;
}

interface EventStream {
  [Symbol.asyncIterator](): AsyncIterator<{
    event?: unknown;
    id?: unknown;
    data: string;
  }>;
}

interface TextStream {
  [Symbol.asyncIterator](): AsyncIterator<string>;
}

参数

返回值

ChatModel.generateText()

调用大模型生成文本。

使用示例

// 连接模型提供商
const provider = wx.cloud.extend.AI.createModel("cloudbase"); 
const res = await provider.generateText({
  model: "hy3-preview",
  messages: [{ role: "user", content: "你好" }],
});
console.log(res);
// {
//   "id": "27dae91f4e9a4777782c61f89acf8ea4",
//   "object": "chat.completion",
//   "created": 1737602298,
//   "model": "hy3-preview",
//   "system_fingerprint": "",
//   "choices": [
//     {
//       "index": 0,
//       "message": {
//         "role": "assistant",
//         "content": "你好！很高兴与你交流。请问有什么我可以帮助你的吗？无论是关于生活、工作、学习还是其他方面的问题，我都会尽力为你提供帮助。"
//       },
//       "finish_reason": "stop"
//     }
//   ],
//   "usage": {
//     "prompt_tokens": 3,
//     "completion_tokens": 33,
//     "total_tokens": 36
//   },
//   "note": "以上内容为AI生成，不代表开发者立场，请勿删除或修改本标记"
// }
console.log(res.choices[0].message.content);
// 你好！很高兴与你交流。请问有什么我可以帮助你的吗？无论是关于生活、工作、学习还是其他方面的问题，我都会尽力为你提供帮助。

类型声明

function generateText(data: unknown): Promise<unknown>;

参数

返回值

该接口直接返回实际调用大模型的响应值，需要根据实际响应内容解析出需要的数据。参见上文使用示例。

图片生成

基础库 3.17.4 及以上支持

通过 AI.createImageModel() 创建图片模型实例，可调用 generateImage() 进行文生图或图生图。

模型下线预告： HY-Image-3.0-Plus-4090-Tob-v1.0（文生图）与 HY-Image-v3.0-I2I-ToB-v1.0.1（图生图）将于 2026 年 12 月 1 日 0 点下线，下线后调用会报错。接替模型 hy-image-v3.5-preview 预计 2026 年 11 月中旬提供，调用方式与当前模型不同，具体改造点另行通知。请评估工作量并预留适配时间。详见《关于混元生图 3.0 模型下线的通知》。

AI.createImageModel()

创建指定的图片模型实例。

使用示例

const imageModel = wx.cloud.extend.AI.createImageModel("hunyuan-image");

类型声明

function createImageModel(provider: string): ImageModel;

参数

返回一个提供图片生成能力的对象。

ImageModel.generateImage()

调用图片模型生成图片（支持文生图与图生图）。

使用示例

文生图：

const imageModel = wx.cloud.extend.AI.createImageModel("hunyuan-image");
const res = await imageModel.generateImage({
  model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
  prompt: "一只胖胖的橘猫坐在窗台上打盹，水彩风格，温暖色调",
  size: "1024x1024",
  revise: { value: true },
  timeout: 120000,
});

console.log(res.data[0].url);
console.log(res.data[0].revised_prompt);

图生图：

const imageModel = wx.cloud.extend.AI.createImageModel("hunyuan-image");
const res = await imageModel.generateImage({
  model: "HY-Image-v3.0-I2I-ToB-v1.0.1",
  prompt: "将这张照片转换为油画风格",
  size: "1024x1024",
  revise: { value: true },
  image_urls: ["https://example.com/reference.jpg"], // 或传入 images: ["<base64>"]
  timeout: 120000,
});

console.log(res.data[0].url);

类型声明

function generateImage(data: GenerateImageInput): Promise<GenerateImageOutput>;

interface GenerateImageInput {
  model: string;
  prompt: string;
  size?: string;
  revise?: { value: boolean };
  footnote?: string;
  image_urls?: string[];
  images?: string[];
  timeout?: number;
}

interface GenerateImageOutput {
  id: string;
  created: number;
  data: Array<{
    url: string;
    revised_prompt?: string;
  }>;
}

参数

返回值

关于 revised_prompt

revised_prompt 中包含模型输出的内联标记，<think> 内为推理过程，<recaption> 内为画面描述，末尾还会携带 <boi>、<img_size_*>、<img_ratio_*> 等尺寸标记。直接展示前需提取 <recaption> 的内容：

function cleanRevisedPrompt(text) {
  if (!text) return "";

  let out = text.replace(/<think>[\s\S]*?<\/think>/gi, "");

  const recaption = out.match(/<recaption>([\s\S]*?)<\/recaption>/i);
  const answer = out.match(/<answer>([\s\S]*?)<\/answer>/i);
  if (recaption && recaption[1].trim()) out = recaption[1];
  else if (answer && answer[1].trim()) out = answer[1];

  return out
    .replace(/<\/?boi>/gi, "")
    .replace(/<img_size_\d+>/gi, "")
    .replace(/<img_ratio_\d+>/gi, "")
    .replace(/<\/?recaption>/gi, "")
    .replace(/<\/?answer>/gi, "")
    .trim();
}

Agent

AI.bot.sendMessage()

与 Agent 进行对话。

请求参数说明

消息格式

interface Message {
  id: string;           // 消息 ID
  role: "user" | "assistant" | "system" | "tool";
  content: string;      // 消息内容
  name?: string;        // 工具名称（role 为 tool 时）
  toolCallId?: string;  // 工具调用 ID（role 为 tool 时）
}

响应格式

响应采用 SSE 格式，每个事件以 data: 开头：

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"你好"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED"}

事件类型

更多用法请参考 云开发 Agent 文档。