AI SDK

初始化 SDK

初始化方法请参考初始化 SDK。

app.ai

初始化后，可以使用挂载至 cloudbase 实例上的 ai 方法创建 AI 实例，用于后续模型创建。

使用示例

app = cloudbase.init({ env: "your-env" });
const ai = app.ai();

类型声明

function ai(): AI;

返回值

AI

返回新创建的 AI 实例。

AI

用于创建 AI 模型的类。

createModel()

创建指定的 AI 模型。

使用示例

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

类型声明

function createModel(model: string): ChatModel;

返回一个实现了 ChatModel 抽象类的模型实例，该实例提供 AI 生成文本相关能力。

createImageModel()

创建指定的图片生成模型。

使用示例

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

类型声明

function createImageModel(provider: string): ImageModel;

参数

参数名	必填	类型	说明
provider	是	string	模型提供方名称，如 `"hunyuan-image"`

返回值

返回一个 ImageModel 实例，该实例提供 AI 图片生成相关能力。

bot

挂载了 Bot 类的实例，上面集合了一系列与 Agent 交互的方法。具体可参考 Bot 类的详细文档。

使用示例

const agentList = await ai.bot.list({ pageNumber: 1, pageSize: 10 });

registerFunctionTool()

注册函数工具。在进行大模型调用时，可以告知大模型可用的函数工具，当大模型的响应被解析为工具调用时，会自动调用对应的函数工具。

使用示例

// 省略初始化 AI sdk 的操作...

// 1. 定义获取天气的工具，详见 FunctionTool 类型
const getWeatherTool = {
  name: "get_weather",
  description: "返回某个城市的天气信息。调用示例：get_weather({city: '北京'})",
  fn: ({ city }) => `${city}的天气是：秋高气爽！！！`, // 在这定义工具执行的内容
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "要查询的城市",
      },
    },
    required: ["city"],
  },
};

// 2. 注册我们刚定义好的工具
ai.registerFunctionTool(getWeatherTool);

// 3. 在给大模型发送消息的同时，告知大模型可用一个获取天气的工具
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool], // 这里我们传入了获取天气工具
  messages: [
    {
      role: "user",
      content: "请告诉我北京的天气状况",
    },
  ],
});

console.log(result.text);

类型声明

function registerFunctionTool(functionTool: FunctionTool);

参数

参数名	必填	类型	说明
functionTool	是	FunctionTool	详见 FunctionTool

返回值

undefined

ChatModel

这个抽象类描述了 AI 生文模型类提供的接口。

generateText()

调用大模型生成文本。

使用示例

const hy = ai.createModel("hunyuan-exp"); // 创建模型
const res = await hy.generateText({
  model: "hunyuan-turbos-latest",
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});
console.log(res.text); // 打印生成的文本

类型声明

function generateText(data: BaseChatModelInput): Promise<{
  rawResponses: Array<unknown>;
  text: string;
  messages: Array<ChatModelMessage>;
  usage: Usage;
  error?: unknown;
}>;

参数

参数名	必填	类型	示例	说明
data	是	BaseChatModelInput	`{model: "hunyuan-turbos-latest", messages: [{ role: "user", content: "你好，请你介绍一下李白" }]}`	参数类型定义为 BaseChatModelInput ，作为基础的入参定义。实际上各家大模型还会有各自独特的输入参数，开发者可按需根据实际使用的大模型官方文档传入其他不在此类型中被定义的参数，充分利用大模型提供的能力。其他参数会被透传至大模型接口， SDK 侧不对它们不做额外处理。

返回值

属性名	类型	示例	说明
text	string	`"李白是一位唐朝诗人。"`	大模型生成的文本。
rawResponses	unknown[]	`[{"choices": [{"finish_reason": "stop","message": {"role": "assistant", "content": "你好呀，有什么我可以帮忙的吗？"}}], "usage": {"prompt_tokens": 14, "completion_tokens": 9, "total_tokens": 23}}]`	大模型的完整返回值，包含更多详细数据，如消息创建时间等等。由于各家大模型返回值互有出入，请根据实际情况使用。
res.messages	ChatModelMessage[]	`[{role: 'user', content: '你好'},{role: 'assistant', content: '你好！很高兴与你交流。请问有什么我可以帮助你的吗？无论是关于生活、工作、学习还是其他方面的问题，我都会尽力为你提供帮助。'}]`	本次调用的完整消息列表。
usage	Usage	`{"completion_tokens":33,"prompt_tokens":3,"total_tokens":36}`	本次调用消耗的 token。
error	unknown		调用过程中产生的错误。

streamText()

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

使用示例

const hy = ai.createModel("hunyuan-exp"); // 创建模型
const res = await hy.streamText({
  model: "hunyuan-turbos-latest",
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

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

类型声明

function streamText(data: BaseChatModelInput): Promise<StreamTextResult>;

参数

参数名	必填	类型	示例	说明
data	是	BaseChatModelInput	`{model: "hunyuan-turbos-latest", messages: [{ role: "user", content: "你好，请你介绍一下李白" }]}`	参数类型定义为 BaseChatModelInput ，作为基础的入参定义。实际上各家大模型还会有各自独特的输入参数，开发者可按需根据实际使用的大模型官方文档传入其他不在此类型中被定义的参数，充分利用大模型提供的能力。其他参数会被透传至大模型接口， SDK 侧不对它们不做额外处理。

返回值

StreamTextResult 属性名	类型	说明
textStream	`ReadableStream<string>`	以流式返回的大模型生成文本，可参考使用示例获取到生成的增量文本。
dataStream	`ReadableStream<DataChunk>`	以流式返回的大模型响应数据，可参考使用示例获取到生成的增量数据。由于各家大模型响应值互有出入，请根据实际情况合理使用。
messages	`Promise<ChatModelMessage[]>`	本次调用的完整消息列表。
usage	`Promise<Usage>`	本次调用消耗的 token。
error	`unknown`	本次调用产生的错误。

DataChunk 属性名	类型	说明
choices	`Array<object>`
choices[n].finish_reason	`string`	模型终止推断的原因。
choices[n].delta	`ChatModelMessage`	本次请求的消息。
usage	`Usage`	本次请求消耗的 token。
rawResponse	`unknown`	大模型返回的原始回复。

示例

const hy = ai.createModel("hunyuan-exp");
const res = await hy.streamText({
  model: "hunyuan-turbos-latest",
  messages: [{ role: "user", content: "1+1结果是" }],
});

// 文本流
for await (let str of res.textStream) {
  console.log(str);
}
// 1
// 加
// 1
// 的结果
// 是
// 2
// 。

// 数据流
for await (let str of res.dataStream) {
  console.log(str);
}

// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-turbos-latest", version: "202404011000", choices: Array(1), …}

ImageModel

这个类描述了 AI 图片生成模型类提供的接口。

generateImageSubUrlConfig

用于配置不同 provider 和 model 组合对应的 API 子路径。调用 generateImage() 时，SDK 会根据 input.model 查找对应的子路径，若未找到则使用默认路径 images/generations。

类型声明

generateImageSubUrlConfig: Record<string, Record<string, string>>

默认值

{
  'hunyuan-image': {
    'hunyuan-image-v3.0-v1.0.4': 'images/ar/generations',
    'hunyuan-image-v3.0-v1.0.1': 'images/ar/generations',
  },
}

使用示例

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

// 自定义子路径配置
imageModel.generateImageSubUrlConfig['hunyuan-image']['custom-model'] = 'images/custom/generations';

generateImage()

调用大模型生成图片。

使用示例

const imageModel = ai.createImageModel("hunyuan-image");
const res = await imageModel.generateImage({
  model: "hunyuan-image-v3.0-v1.0.4",
  prompt: "一只可爱的猫咪在草地上玩耍",
});
console.log(res.data[0].url); // 打印生成的图片 URL

类型声明

function generateImage(input: HunyuanARGenerateImageInput): Promise<HunyuanARGenerateImageOutput>;
function generateImage(input: HunyuanGenerateImageInput): Promise<HunyuanGenerateImageOutput>;

参数

参数名	必填	类型	说明
input	是	HunyuanARGenerateImageInput \| HunyuanGenerateImageInput	图片生成参数，详见 HunyuanARGenerateImageInput 或 HunyuanGenerateImageInput

返回值

Promise<HunyuanARGenerateImageOutput> 或 Promise<HunyuanGenerateImageOutput>

属性名	类型	说明
id	string	此次请求的 id
created	number	unix 时间戳
data	Array<object>	返回的图片生成内容
data[n].url	string	生成的图片 url，有效期为 24 小时
data[n].revised_prompt	string	原 prompt 改写后的文本（若 revise 为 false，则为原 prompt）

Bot

用于与 Agent 交互的类。

get()

获取某个 Agent 的信息。

使用示例

const res = await ai.bot.get({ botId: "botId-xxx" });
console.log(res);

类型声明

function get(props: { botId: string });

参数

参数名	必填	类型	说明
props.botId	是	string	要获取信息的 Agent 的 id

返回值

属性名	类型	示例	说明
botId	string	`"bot-27973647"`	Agent ID
name	string	`"信达雅翻译"`	Agent 名称
introduction	string		Agent 简介
welcomeMessage	string		Agent 欢迎语
avatar	string		Agent 头像链接
background	string		Agent 聊天背景图链接
isNeedRecommend	boolean		Agent 回答后是否推荐问题
type	string		Agent 类型

list()

批量获取多个 Agent 的信息。

使用示例

await ai.bot.list({
  pageNumber: 1,
  pageSize: 10,
  name: "",
  enable: true,
  information: "",
  introduction: "",
});

类型声明

function list(props: {
  name: string;
  introduction: string;
  information: string;
  enable: boolean;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.pageNumber	是	number	分页下标
props.pageSize	是	number	分页大小
props.enable	是	boolean	Agent 是否启用
props.name	是	string	Agent 名字，用于模糊查询
props.information	是	string	Agent 信息，用于模糊查询
props.introduction	是	string	Agent 简介，用于模糊查询

返回值

属性名	类型	示例	说明
total	number	---	Agent 总数
botList	`Array<object>`		Agent 列表
`botList[n].botId`	string	`"bot-27973647"`	Agent ID
`botList[n].name`	string	`"信达雅翻译"`	Agent 名称
`botList[n].introduction`	string		Agent 简介
`botList[n].welcomeMessage`	string		Agent 欢迎语
`botList[n].avatar`	string		Agent 头像链接
`botList[n].background`	string		Agent 聊天背景图链接
`botList[n].isNeedRecommend`	boolean		Agent 回答后是否推荐问题
`botList[n].type`	string		Agent 类型

sendMessage()

与 Agent 进行对话。响应会通过 SSE 返回，该接口的返回值对 SSE 做了不同程度的封装，开发者能根据实际需求获取到文本流和完整数据流。

使用示例

const res = await ai.bot.sendMessage({
  botId: "botId-xxx",
  history: [{ content: "你是李白。", role: "user" }],
  msg: "你好",
});
for await (let str of res.textStream) {
  console.log(str);
}
for await (let data of res.dataStream) {
  console.log(data);
}

类型声明

function sendMessage(props: {
  botId: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.msg	是	string	此次对话要发送的消息
props.history	是	[]	在此次对话前发生的聊天记录
`props.history[n].role`	是	string	本聊天信息的发送角色
`props.history[n].content`	是	string	本聊天信息的内容

返回值

Promise<StreamResult>

StreamResult 属性名	类型	说明
textStream	`AsyncIterable<string>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。
dataStream	`AsyncIterable<AgentStreamChunk>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。

AgentStreamChunk 属性名	类型	说明
created	number	对话时间戳
record_id	string	对话记录ID
model	string	大模型类型
version	string	大模型版本
type	string	回复类型： text: 主要回答内容，thinking: 思考过程，search: 查询结果，knowledge: 知识库
role	string	对话角色，响应中固定为 assistant
content	string	对话内容
finish_reasion	string	对话结束标志，continue 表示对话未结束，stop 表示对话结束
reasoning_content	string	深度思考内容（仅deepseek-r1是不为空字符串）
usage	object	token使用量
usage.prompt_tokens	number	表示prompt的tokens数，多次返回中保持不变
usage.completion_tokens	number	回答的token总数，在流式返回中，表示到目前为止所有completion的tokens总数，多次返回中持续累加
usage.total_tokens	number	表示prompt_tokens和completion_tokens之和
knowledge_base	string[]	对话中使用到的知识库
search_info	object	搜索结果信息，需要开启联网查询
search_info.search_results	object[]	搜索引文信息
search_info.search_results[n].index	string	搜索引文序号
search_info.search_results[n].title	string	搜索引文标题
search_info.search_results[n].url	string	搜索引文链接

getChatRecords()

获取聊天记录。

使用示例

await ai.bot.getChatRecords({
  botId: "botId-xxx",
  pageNumber: 1,
  pageSize: 10,
  sort: "asc",
});

类型声明

function getChatRecords(props: {
  botId: string;
  sort: string;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.sort	是	string	排序方式
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

返回值

属性名	类型	说明
total	number	对话总数
recordList	`Array<object>`	对话总数
`recordList[n].botId`	string	Agent ID
`recordList[n].recordId`	string	对话 ID，由系统生成
`recordList[n].role`	string	对话中的角色
`recordList[n].content`	string	对话内容
`recordList[n].conversation`	string	用户标识
`recordList[n].type`	string	对话数据类型
`recordList[n].image`	string	对话生成的图片链接
`recordList[n].triggerSrc`	string	对话发起来源
`recordList[n].replyTo`	string	对话回复的记录 ID
`recordList[n].createTime`	string	对话时间

sendFeedback()

发送对某条聊天记录的反馈信息。

使用示例

const res = await ai.bot.sendFeedback({
  userFeedback: {
    botId: "botId-xxx",
    recordId: "recordId-xxx",
    comment: "非常棒",
    rating: 5,
    tags: ["优美"],
    aiAnswer: "落英缤纷",
    input: "来个成语",
    type: "upvote",
  },
  botId: "botId-xxx",
});

类型声明

function sendFeedback(props: { userFeedback: IUserFeedback; botId: string });

参数

参数名	必填	类型	说明
props.userFeedback	是	IUserFeedback	用户反馈，详见 IUserFeedback 类型定义
props.botId	是	string	将要反馈的 Agent id

getFeedback()

获取已存在的反馈信息。

使用示例

const res = await ai.bot.getFeedback({
  botId: "botId-xxx",
  from: 0,
  to: 0,
  maxRating: 4,
  minRating: 3,
  pageNumber: 1,
  pageSize: 10,
  sender: "user-a",
  senderFilter: "include",
  type: "upvote",
});

类型声明

function sendFeedback(props: {
  botId: string;
  type: string;
  sender: string;
  senderFilter: string;
  minRating: number;
  maxRating: number;
  from: number;
  to: number;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.type	是	string	用户反馈类型，点赞 upvote 点踩 downvote
props.sender	是	string	评论创建用户
props.senderFilter	是	string	评论创建用户过滤关系 include:包含 exclude:不包含 equal:等于 unequal:不等于 prefix:前缀
props.minRating	是	number	最低评分
props.maxRating	是	number	最高评分
props.from	是	number	开始时间戳
props.to	是	number	结束时间戳
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

返回值

属性名	类型	说明
feedbackList	object[]	反馈查询结果
feedbackList[n].recordId	string	对话记录 ID
feedbackList[n].type	string	用户反馈类型，点赞 upvote 点踩 downvote
feedbackList[n].botId	string	Agent ID
feedbackList[n].comment	string	用户评论
feedbackList[n].rating	number	用户评分
feedbackList[n].tags	string[]	用户反馈的标签数组
feedbackList[n].input	string	用户输入的问题
feedbackList[n].aiAnswer	string	Agent 的回答
total	number	反馈总数

uploadFiles()

将云存储中的文件上传至 Agent，用于进行文档聊天。

使用示例

// 上传文件
await ai.bot.uploadFiles({
  botId: "botId-xxx",
  fileList: [
    {
      fileId: "cloud://xxx.docx",
      fileName: "xxx.docx",
      type: "file",
    },
  ],
});

// 进行文档聊天
const res = await ai.bot.sendMessage({
  botId: "your-bot-id",
  msg: "这个文件的内容是什么",
  files: ["xxx.docx"], // 文件 fileId 数组
});

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

类型声明

function uploadFiles(props: {
  botId: string;
  fileList: Array<{
    fileId: "string";
    fileName: "string";
    type: "file";
  }>;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.fileList	是	string	文件列表
props.fileList[n].fileId	是	string	云存储文件 id
props.fileList[n].fileName	是	string	文件名
props.fileList[n].type	是	string	暂时只支持 `"file"`

getRecommendQuestions()

获取推荐的问题。

使用示例

const res = ai.bot.getRecommendQuestions({
  botId: "botId-xxx",
  history: [{ content: "你是谁啊", role: "user" }],
  msg: "你好",
  agentSetting: "",
  introduction: "",
  name: "",
});

for await (let str of res.textStream) {
  console.log(str);
}

类型声明

function getRecommendQuestions(props: {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.name	是	string	Agent 名称
props.introduction	是	string	Agent 简介
props.agentSetting	是	string	Agent 设定
props.msg	是	string	用户发送信息
props.history	是	Array	历史对话信息
`props.history[n].role`	是	string	历史信息角色
`props.history[n].content`	是	string	历史信息内容

返回值

Promise<StreamResult>

StreamResult 属性名	类型	说明
textStream	`AsyncIterable<string>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。
dataStream	`AsyncIterable<AgentStreamChunk>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。

AgentStreamChunk 属性名	类型	说明
created	number	对话时间戳
record_id	string	对话记录ID
model	string	大模型类型
version	string	大模型版本
type	string	回复类型： text: 主要回答内容，thinking: 思考过程，search: 查询结果，knowledge: 知识库
role	string	对话角色，响应中固定为 assistant
content	string	对话内容
finish_reasion	string	对话结束标志，continue 表示对话未结束，stop 表示对话结束
reasoning_content	string	深度思考内容（仅deepseek-r1是不为空字符串）
usage	object	token使用量
usage.prompt_tokens	number	表示prompt的tokens数，多次返回中保持不变
usage.completion_tokens	number	回答的token总数，在流式返回中，表示到目前为止所有completion的tokens总数，多次返回中持续累加
usage.total_tokens	number	表示prompt_tokens和completion_tokens之和
knowledge_base	string[]	对话中使用到的知识库
search_info	object	搜索结果信息，需要开启联网查询
search_info.search_results	object[]	搜索引文信息
search_info.search_results[n].index	string	搜索引文序号
search_info.search_results[n].title	string	搜索引文标题
search_info.search_results[n].url	string	搜索引文链接

createConversation()

创建与 Agent 的新对话。

使用示例

const res = await ai.bot.createConversation({
  botId: "botId-xxx",
  title: "我的对话",
});

类型声明

function createConversation(props: IBotCreateConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.title	否	string	对话标题

返回值

Promise<IConversation>

getConversation()

获取对话列表。

使用示例

const res = await ai.bot.getConversation({
  botId: "botId-xxx",
  pageSize: 10,
  pageNumber: 1,
  isDefault: false,
});

类型声明

function getConversation(props: IBotGetConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.pageSize	否	number	分页大小，默认 10
props.pageNumber	否	number	分页下标，默认 1
props.isDefault	否	boolean	是否只获取默认对话

deleteConversation()

删除指定对话。

使用示例

await ai.bot.deleteConversation({
  botId: "botId-xxx",
  conversationId: "conv-123",
});

类型声明

function deleteConversation(props: IBotDeleteConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.conversationId	是	string	要删除的对话 ID

speechToText()

语音转文字。

使用示例

const res = await ai.bot.speechToText({
  botId: "botId-xxx",
  engSerViceType: "16k_zh",
  voiceFormat: "mp3",
  url: "https://example.com/audio.mp3",
});

类型声明

function speechToText(props: IBotSpeechToText);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.engSerViceType	是	string	引擎类型，如"16k_zh"
props.voiceFormat	是	string	音频格式，如"mp3"
props.url	是	string	音频文件 URL
props.isPreview	否	boolean	是否为预览模式

textToSpeech()

文字转语音。

使用示例

const res = await ai.bot.textToSpeech({
  botId: "botId-xxx",
  voiceType: 1,
  text: "你好，我是AI助手",
});

类型声明

function textToSpeech(props: IBotTextToSpeech);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.voiceType	是	number	语音类型
props.text	是	string	要转换的文本
props.isPreview	否	boolean	是否为预览模式

getTextToSpeechResult()

获取文字转语音的结果。

使用示例

const res = await ai.bot.getTextToSpeechResult({
  botId: "botId-xxx",
  taskId: "task-123",
});

类型声明

function getTextToSpeechResult(props: IBotGetTextToSpeechResult);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.taskId	是	string	任务 ID
props.isPreview	否	boolean	是否为预览模式

IBotCreateConversation

interface IBotCreateConversation {
  botId: string;
  title?: string;
}

IBotGetConversation

interface IBotGetConversation {
  botId: string;
  pageSize?: number;
  pageNumber?: number;
  isDefault?: boolean;
}

IBotDeleteConversation

interface IBotDeleteConversation {
  botId: string;
  conversationId: string;
}

IBotSpeechToText

interface IBotSpeechToText {
  botId: string;
  engSerViceType: string;
  voiceFormat: string;
  url: string;
  isPreview?: boolean;
}

IBotTextToSpeech

interface IBotTextToSpeech {
  botId: string;
  voiceType: number;
  text: string;
  isPreview?: boolean;
}

IBotGetTextToSpeechResult

interface IBotGetTextToSpeechResult {
  botId: string;
  taskId: string;
  isPreview?: boolean;
}

BaseChatModelInput

interface BaseChatModelInput {
  model: string;
  messages: Array<ChatModelMessage>;
  temperature?: number;
  topP?: number;
  tools?: Array<FunctionTool>;
  toolChoice?: "none" | "auto" | "custom";
  maxSteps?: number;
  onStepFinish?: (prop: IOnStepFinish) => unknown;
}

BaseChatModelInput 属性名	类型	说明
model	`string`	模型名称。
messages	`Array<ChatModelMessage>`	消息列表。
temperature	`number`	采样温度，控制输出的随机性。
topP	`number`	温度采样，即模型考虑概率质量为 top_p 的标记的结果。
tools	`Array<FunctionTool>`	大模型可用的工具列表。
toolChoice	`string`	指定大模型选择工具的方式。
maxSteps	`number`	请求大模型的最大次数。
onStepFinish	`(prop: IOnStepFinish) => unknown`	当对大模型的一次请求完成时，出发的回调函数。

BotInfo

interface BotInfo {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  welcomeMessage: string;
  avatar: string;
  background: string;
  tags: Array<string>;
  isNeedRecommend: boolean;
  knowledgeBase: Array<string>;
  type: string;
  initQuestions: Array<string>;
  enable: true;
}

IUserFeedback

interface IUserFeedback {
  recordId: string;
  type: string;
  botId: string;
  comment: string;
  rating: number;
  tags: Array<string>;
  input: string;
  aiAnswer: string;
}

ChatModelMessage

type ChatModelMessage =
  | UserMessage
  | SystemMessage
  | AssistantMessage
  | ToolMessage;

UserMessage

type UserMessage = {
  role: "user";
  content: string;
};

SystemMessage

type SystemMessage = {
  role: "system";
  content: string;
};

AssistantMessage

type AssistantMessage = {
  role: "assistant";
  content?: string;
  tool_calls?: Array<ToolCall>;
};

ToolMessage

type ToolMessage = {
  role: "tool";
  tool_call_id: string;
  content: string;
};

ToolCall

export type ToolCall = {
  id: string;
  type: string;
  function: { name: string; arguments: string };
};

FunctionTool

工具定义类型。

type FunctionTool = {
  name: string;
  description: string;
  fn: CallableFunction;
  parameters: object;
};

FunctionTool 属性名	类型	说明
name	`string`	工具名称。
description	`string`	工具的描述。清楚的工具描述有助于大模型认识工具的用途。
fn	`CallableFunction`	工具的执行函数。当 AI SDK 解析出大模型的响应需要该工具调用时，会调用此函数，并将结果返回给大模型。
parameters	`object`	工具执行函数的入参。需要使用 JSON Schema 的格式定义入参。

IOnStepFinish

大模型响应后出发的回调函数的入参类型。

interface IOnStepFinish {
  messages: Array<ChatModelMessage>;
  text?: string;
  toolCall?: ToolCall;
  toolResult?: unknown;
  finishReason?: string;
  stepUsage?: Usage;
  totalUsage?: Usage;
}

IOnStepFinish 属性名	类型	说明
messages	`Array<ChatModelMessage>`	到当前步骤为止所有的消息列表。
text	`string`	当前响应的文本。
toolCall	`ToolCall`	当前响应调用的工具。
toolResult	`unknown`	对应的工具调用结果。
finishReason	`string`	大模型推理结束的原因。
stepUsage	`Usage`	当前步骤所花费的 token。
totalUsage	`Usage`	到当前步骤为止所花费的总 token。

Usage

type Usage = {
  completion_tokens: number;
  prompt_tokens: number;
  total_tokens: number;
};

IConversation

Agent 会话。

interface IConversation {
  id: string;
  envId: string;
  ownerUin: string;
  userId: string;
  conversationId: string;
  title: string;
  startTime: string; // date-time format
  createTime: string;
  updateTime: string;
}

HunyuanGenerateImageInput

混元图片生成输入参数。

interface HunyuanGenerateImageInput {
  model: 'hunyuan-image';
  /** 用来生成图像的文本描述 */
  prompt: string;
  /** 模型版本，支持 v1.8.1 和 v1.9，默认版本 v1.8.1 */
  version?: 'v1.8.1' | 'v1.9' | (string & {});
  /** 图片尺寸，默认 "1024x1024" */
  size?: string;
  /** 仅 v1.9 支持，负向词 */
  negative_prompt?: string;
  /** 仅 v1.9 支持，可指定风格 */
  style?: '古风二次元风格' | '都市二次元风格' | '悬疑风格' | '校园风格' | '都市异能风格' | (string & {});
  /** 为 true 时对 prompt 进行改写，默认为 true */
  revise?: boolean;
  /** 生成图片个数，默认为 1 */
  n?: number;
  /** 业务自定义水印内容，限制 16 个字符长度 */
  footnote?: string;
  /** 生成种子，范围 [1, 4294967295] */
  seed?: number;
}

HunyuanGenerateImageInput 属性名	类型	说明
model	`string`	模型名称，固定为 `hunyuan-image`
prompt	`string`	用来生成图像的文本描述
version	`string`	模型版本，支持 `v1.8.1` 和 `v1.9`，默认版本 `v1.8.1`
size	`string`	图片尺寸，默认 `"1024x1024"`
negative_prompt	`string`	仅 v1.9 支持，负向词
style	`string`	仅 v1.9 支持，可指定风格：古风二次元风格、都市二次元风格、悬疑风格、校园风格、都市异能风格
revise	`boolean`	为 true 时对 prompt 进行改写，默认为 true
n	`number`	生成图片个数，默认为 1
footnote	`string`	业务自定义水印内容，限制 16 个字符长度
seed	`number`	生成种子，范围 [1, 4294967295]

HunyuanGenerateImageOutput

混元图片生成输出。

interface HunyuanGenerateImageOutput {
  /** 此次请求的 id */
  id: string;
  /** unix 时间戳 */
  created: number;
  /** 返回的图片生成内容 */
  data: Array<{
    /** 生成的图片 url，有效期为 24 小时 */
    url: string;
    /** 原 prompt 改写后的文本。若 revise 为 false，则为原 prompt */
    revised_prompt?: string;
  }>;
}

HunyuanGenerateImageOutput 属性名	类型	说明
id	`string`	此次请求的 id
created	`number`	unix 时间戳
data	`Array<object>`	返回的图片生成内容
data[n].url	`string`	生成的图片 url，有效期为 24 小时
data[n].revised_prompt	`string`	原 prompt 改写后的文本。若 revise 为 false，则为原 prompt

HunyuanARGenerateImageInput

混元图片生成 v3.0 输入参数，支持自定义宽高比。

interface HunyuanARGenerateImageInput {
  /** 模型名称：hunyuan-image-v3.0-v1.0.4（推荐）或 hunyuan-image-v3.0-v1.0.1 */
  model: 'hunyuan-image-v3.0-v1.0.4' | 'hunyuan-image-v3.0-v1.0.1';
  /** 生成图片使用的文本，不超过 8192 字符 */
  prompt: string;
  /**
   * 图片尺寸，格式 "${宽}x${高}"，默认 "1024x1024"
   * hunyuan-image-v3.0-v1.0.4：宽高范围 [512, 2048]，面积不超过 1024x1024
   * hunyuan-image-v3.0-v1.0.1：支持固定尺寸列表
   */
  size?: string;
  /** 生成种子，仅当生成图片数为 1 时生效，范围 [1, 4294967295] */
  seed?: number;
  /** 业务自定义水印内容，限制 16 字符，生成在图片右下角 */
  footnote?: string;
  /** 是否对 prompt 改写，默认开启。改写会增加约 30s 耗时 */
  revise?: { value: boolean };
  /** 改写是否开启 thinking 模式，默认开启。开启后效果提升但耗时增加（最大 60s） */
  enable_thinking?: { value: boolean };
}

HunyuanARGenerateImageInput 属性名	类型	说明
model	`string`	模型名称，`hunyuan-image-v3.0-v1.0.4`（推荐）或 `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）

HunyuanARGenerateImageOutput

混元图片生成 v3.0 输出。

interface HunyuanARGenerateImageOutput {
  /** 此次请求的 id */
  id: string;
  /** unix 时间戳 */
  created: number;
  /** 返回的图片生成内容 */
  data: Array<{
    /** 生成的图片 url，有效期为 24 小时 */
    url: string;
    /** 改写后的 prompt */
    revised_prompt?: string;
  }>;
}

HunyuanARGenerateImageOutput 属性名	类型	说明
id	`string`	此次请求的 id
created	`number`	unix 时间戳
data	`Array<object>`	返回的图片生成内容
data[n].url	`string`	生成的图片 url，有效期为 24 小时
data[n].revised_prompt	`string`	改写后的 prompt

初始化 SDK​

app.ai​

使用示例​

类型声明​

返回值​

AI​

createModel()​

使用示例​

类型声明​

createImageModel()​

使用示例​

类型声明​

参数​

返回值​

bot​

使用示例​

registerFunctionTool()​

使用示例​

类型声明​

参数​

返回值​

ChatModel​

generateText()​

使用示例​

类型声明​

参数​

返回值​

streamText()​

使用示例​

类型声明​

参数​

返回值​

示例​

ImageModel​

generateImageSubUrlConfig​

类型声明​

默认值​

使用示例​

generateImage()​

使用示例​

类型声明​

参数​

返回值​

Bot​

get()​

使用示例​

类型声明​

参数​

返回值​

list()​

使用示例​

类型声明​

参数​

返回值​

sendMessage()​

使用示例​

类型声明​

参数​

返回值​

getChatRecords()​

使用示例​

类型声明​

参数​

返回值​

sendFeedback()​

使用示例​

类型声明​

参数​

getFeedback()​

使用示例​

类型声明​

参数​

返回值​

uploadFiles()​

使用示例​

类型声明​

参数​

getRecommendQuestions()​

使用示例​

类型声明​

初始化 SDK

app.ai

使用示例

类型声明

返回值

AI

createModel()

使用示例

类型声明

createImageModel()

使用示例

类型声明

参数

返回值

bot

使用示例

registerFunctionTool()

使用示例

类型声明

参数

返回值

ChatModel

generateText()

使用示例

类型声明

参数

返回值

streamText()

使用示例

类型声明

参数

返回值

示例

ImageModel

generateImageSubUrlConfig

类型声明

默认值

使用示例

generateImage()

使用示例

类型声明

参数

返回值

Bot

get()

使用示例

类型声明

参数

返回值

list()

使用示例

类型声明

参数

返回值

sendMessage()

使用示例

类型声明

参数

返回值

getChatRecords()

使用示例

类型声明

参数

返回值

sendFeedback()

使用示例

类型声明

参数

getFeedback()

使用示例

类型声明

参数

返回值

uploadFiles()

使用示例

类型声明

参数

getRecommendQuestions()

使用示例

类型声明