FastGPTFastGPT

初始化应用或 Skill 调试会话

初始化指定会话并获取应用基础信息、欢迎语、全局变量、预设问题及历史上下文状态,支持应用会话与 Skill 调试会话。

端点概览

  • HTTP 方法:GET
  • 请求路径:/api/core/chat/init
  • 所属模块:对话 / 会话管理
  • 鉴权方式:Authorization: Bearer <apiKey>—支持 应用 API Key(无需 appId)与 个人密钥(需传 appId);另支持 authProxy 团队成员代理(详见 API 入门:完成首次请求)
  • 在线调试:在云服务 Scalar 调试台打开(自部署实例请将域名替换为 <instance>/apidoc/systemopenapi#tag/%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86/GET/core/chat/init)

接口说明与注意事项

初始化应用会话或 Skill 编辑调试会话,返回会话配置、变量和已有会话状态。

Query 身份二选一:应用会话传 appId;Skill 调试会话传 skillId,两种模式均需传 chatId。使用登录态或接口允许的 API Key 鉴权;同时传入 appId 和 skillId 时优先使用 skillId。

应用辅助生成会话通过 appId 与 sourceType 指定,sourceType 支持 chatAgentHelper、workflowBuilder;普通应用会话省略 sourceType。

外链分享会话使用 GET /api/core/chat/outLink/init,传入 JSON 序列化的 outLinkAuthData。

Skill 编辑沙盒的启动、恢复或复用使用 POST /api/core/ai/skill/runtime/init,与本接口的会话初始化用途不同。

请求参数

Query 查询参数

各分支公共字段

字段类型必填默认值约束与说明
chatIdstring是-会话 ID。最小长度:1;最大长度:1024
loadCustomFeedbacksboolean否-是否加载自定义反馈

互斥参数分支(anyOf 选填其一)

  • 应用会话

通过 appId 定位会话。接口同时支持 API Key 和登录态时,Authorization 优先于 token/Cookie。

字段类型必填默认值约束与说明
appIdstring是-应用 ID,使用接口允许的请求头凭证鉴权。正则:^[0-9a-fA-F]{24}$
sourceTypestring (enum)否-appId 对应的会话资源类型。缺省为 App 会话;辅助生成会话传对应 sourceType。可选值:app , chatAgentHelper , workflowBuilder

默认身份: 不传 customUid 和 authProxy,沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。

自定义使用者: 通过 customUid 对接自己平台的使用者,不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId;管理对话时按该值限制使用者范围。

字段类型必填默认值约束与说明
customUidstring是-仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID(outLinkUid),不匹配 tmbId;省略时保留原访问范围,传入时限制读取、修改及删除。最长 1024 字符,不接受空字符串或 null,不改变鉴权成员。最小长度:1;最大长度:1024

代理团队成员: 通过 authProxy 代表同团队成员执行,解析出有效 tmbId 后按该成员权限校验。仅开启代理权限的个人密钥可用,与 customUid 互斥。

字段类型必填默认值约束与说明
authProxystring是-代理身份的 JSON 字符串,例如 {"tmbId":"团队成员 ID"} 或 {"username":"用户名"}
  • Skill 调试会话

通过 skillId 定位调试会话,优先于 appId 并忽略其 sourceType,使用接口允许的请求头凭证鉴权。

字段类型必填默认值约束与说明
skillIdstring是-Skill Edit 调试 ID,使用接口允许的请求头凭证鉴权。正则:^[0-9a-fA-F]{24}$
  • 应用 API Key(无需 appId)

Authorization 使用绑定应用的 APP API Key 时无需传 appId 或 sourceType,服务端从 Key 绑定取得应用,sourceType 固定为 app。个人密钥和登录态不能使用此省略方式;显式传入 appId 时仍以 Key 绑定为准。

默认身份: 不传 customUid 和 authProxy,沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。

自定义使用者: 通过 customUid 对接自己平台的使用者,不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId;管理对话时按该值限制使用者范围。

字段类型必填默认值约束与说明
customUidstring是-仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID(outLinkUid),不匹配 tmbId;省略时保留原访问范围,传入时限制读取、修改及删除。最长 1024 字符,不接受空字符串或 null,不改变鉴权成员。最小长度:1;最大长度:1024

请求示例

调用前请将 YOUR_API_KEY 与示例 ID 替换为真实值;私有化部署实例请将基础域名替换为 <instance>/api。

cURL 请求示例

curl --fail-with-body -X GET "https://cloud.fastgpt.cn/api/core/chat/init?appId=68ad85a7463006c963799a05&chatId=1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应结构与示例

除兼容 OpenAI 协议的对话补全或二进制下载接口外,成功响应统一包裹在 { "code": 200, "statusText": "", "message": "", "data": ... } 标准结构中;下方 200 字段表对应 data 载荷结构(若契约未声明具体载荷结构,请以上方状态描述及实际响应为准)。

HTTP 200

成功返回聊天初始化信息

Content-Type : application/json

字段类型必填默认值约束与说明
chatIdstring否-会话 ID。最大长度:1024
userAvatarstring否-用户头像
titlestring是-对话标题
variablesobject否-全局变量值
chatGenerateStatusnumber (enum)否-由 Redis 生成租约计算的运行状态:0=generating(生成中),1=done(空闲)。可选值:0 , 1
hasBeenReadboolean否-是否已读
appobject是-应用配置
app.chatConfigobject否-聊天配置
app.chatConfig.welcomeTextstring否-新会话开始时展示给用户的欢迎语
app.chatConfig.welcomeConfigobject否-开场白配置
app.chatConfig.welcomeConfig.welcomeTextstring否-新会话开始时展示给用户的欢迎语
app.chatConfig.welcomeConfig.welcomeQuestionsstring[]否-开场白下方展示的预设问题列表
app.chatConfig.variablesobject[]否-应用启动对话前需要用户填写的变量列表
app.chatConfig.variables[].maxFilesinteger否-该变量允许选择的最大文件数量。最小值:0;最大值:9007199254740991
app.chatConfig.variables[].canSelectFileboolean否-该变量是否允许选择普通文件
app.chatConfig.variables[].customPdfParseboolean否-是否使用自定义 PDF 解析配置
app.chatConfig.variables[].canSelectImgboolean否-该变量是否允许选择图片
app.chatConfig.variables[].canSelectVideoboolean否-该变量是否允许选择视频
app.chatConfig.variables[].canSelectAudioboolean否-该变量是否允许选择音频
app.chatConfig.variables[].canSelectCustomFileExtensionboolean否-该变量是否允许选择自定义扩展名文件
app.chatConfig.variables[].customFileExtensionListstring[]否-该变量允许选择的自定义文件扩展名列表
app.chatConfig.variables[].keystring是-变量键名,用于在提示词或工作流中引用该输入
app.chatConfig.variables[].labelstring是-变量展示名称
app.chatConfig.variables[].valueTypestring (enum)否-变量值的数据类型。可选值:string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp
app.chatConfig.variables[].requiredboolean否-该变量是否必填
app.chatConfig.variables[].defaultValueobject | array | string | number | boolean | null否-变量默认值
app.chatConfig.variables[].referencePlaceholderstring否-引用变量时展示的占位提示
app.chatConfig.variables[].isRichTextboolean否-是否使用富文本编辑器输入
app.chatConfig.variables[].placeholderstring否-变量输入框占位提示
app.chatConfig.variables[].maxLengthinteger否-文本变量最大输入长度。最小值:0;最大值:9007199254740991
app.chatConfig.variables[].minLengthinteger否-文本变量最小输入长度。最小值:0;最大值:9007199254740991
app.chatConfig.variables[].markListobject[]否-数值滑块变量的刻度配置
app.chatConfig.variables[].stepnumber否-数值变量步进值
app.chatConfig.variables[].maxnumber否-数值变量最大值
app.chatConfig.variables[].minnumber否-数值变量最小值
app.chatConfig.variables[].precisionnumber否-数值变量小数精度
app.chatConfig.variables[].canLocalUploadboolean否-该变量是否允许从本地上传文件
app.chatConfig.variables[].canUrlUploadboolean否-该变量是否允许通过 URL 引入文件
app.chatConfig.variables[].timeGranularitystring (enum)否-时间变量的选择粒度。可选值:day , hour , minute , second
app.chatConfig.variables[].timeRangeStartstring否-时间范围变量的起始时间
app.chatConfig.variables[].timeRangeEndstring否-时间范围变量的结束时间
app.chatConfig.variables[].datasetOptionsobject[]否-知识库选择变量的可选知识库列表
app.chatConfig.variables[].customInputConfigobject否-变量在编辑器中的自定义输入配置
app.chatConfig.variables[].typestring (enum)是-变量输入组件类型。可选值:input , textarea , numberInput , select , multipleSelect , timePointSelect , timeRangeSelect , switch , password , file , llmSelect , datasetSelect , custom , internal
app.chatConfig.variables[].descriptionstring是-变量用途说明
app.chatConfig.variables[].listobject[]否-选择类变量的可选项
app.chatConfig.variables[].enumsobject[]否-已弃用。已废弃:旧版枚举变量选项
app.chatConfig.autoExecuteobject否-自动执行配置
app.chatConfig.autoExecute.openboolean是-是否在进入会话后自动触发应用执行
app.chatConfig.autoExecute.defaultPromptstring是""自动执行时注入的默认用户问题
app.chatConfig.questionGuideobject否-问题引导配置
app.chatConfig.questionGuide.openboolean是-是否开启问题引导
app.chatConfig.questionGuide.modelIdstring否-生成问题引导时使用的模型 ID
app.chatConfig.questionGuide.modelstring否-已弃用。生成问题引导时使用的旧模型标识
app.chatConfig.questionGuide.customPromptstring否-生成问题引导时追加的自定义提示词
app.chatConfig.ttsConfigobject否-语音播报配置
app.chatConfig.ttsConfig.typestring (enum)是-语音播报方式:关闭、浏览器播报或模型播报。可选值:none , web , model
app.chatConfig.ttsConfig.modelIdstring否-模型播报时使用的语音模型 ID
app.chatConfig.ttsConfig.modelstring否-已弃用。模型播报时使用的语音模型
app.chatConfig.ttsConfig.voicestring否-模型播报时使用的音色
app.chatConfig.ttsConfig.speednumber否-语音播报速度
app.chatConfig.whisperConfigobject否-语音输入配置
app.chatConfig.whisperConfig.openboolean是-是否开启语音输入识别
app.chatConfig.whisperConfig.autoSendboolean是false语音识别完成后是否自动发送问题
app.chatConfig.whisperConfig.autoTTSResponseboolean是false语音输入后是否自动播报应用回复
app.chatConfig.scheduledTriggerConfigobject否-定时触发配置
app.chatConfig.scheduledTriggerConfig.cronStringstring是-定时触发表达式
app.chatConfig.scheduledTriggerConfig.timezonestring是-定时触发使用的时区
app.chatConfig.scheduledTriggerConfig.defaultPromptstring是""定时触发时注入的默认用户问题
app.chatConfig.chatInputGuideobject否-对话输入引导配置
app.chatConfig.chatInputGuide.openboolean是-是否开启对话输入引导
app.chatConfig.chatInputGuide.customUrlstring是-自定义输入引导页面地址
app.chatConfig.fileSelectConfigobject否-对话文件选择配置
app.chatConfig.fileSelectConfig.maxFilesinteger否-单次对话允许选择的最大文件数量。最小值:0;最大值:9007199254740991
app.chatConfig.fileSelectConfig.canSelectFileboolean否-是否允许在对话中选择普通文件
app.chatConfig.fileSelectConfig.customPdfParseboolean否-是否使用自定义 PDF 解析配置
app.chatConfig.fileSelectConfig.canSelectImgboolean否-是否允许在对话中选择图片
app.chatConfig.fileSelectConfig.canSelectVideoboolean否-是否允许在对话中选择视频
app.chatConfig.fileSelectConfig.canSelectAudioboolean否-是否允许在对话中选择音频
app.chatConfig.fileSelectConfig.canSelectCustomFileExtensionboolean否-是否允许选择自定义扩展名的文件
app.chatConfig.fileSelectConfig.customFileExtensionListstring[]否-允许选择的自定义文件扩展名列表
app.chatConfig.entryPointsobject[]否-应用对话页的功能入口列表
app.chatConfig.entryPoints[].idstring是--
app.chatConfig.entryPoints[].namestring是--
app.chatConfig.entryPoints[].iconstring否--
app.chatConfig.instructionstring否-应用对话页展示给用户的使用说明
app.chatModelsstring[]否-聊天模型
app.namestring是-应用名称。最小长度:1
app.avatarstring是-应用头像
app.introstring是-应用简介
app.canUseboolean否-是否可用
app.typestring (enum)是-应用类型。可选值:folder , toolFolder , simple , chatAgent , advanced , plugin , toolSet , httpToolSet , hidden , tool , httpPlugin
app.pluginInputsobject[]是-插件输入
app.pluginInputs[].keystring是-变量键名,用于在提示词或工作流中引用该输入
app.pluginInputs[].labelstring是-变量展示名称
app.pluginInputs[].valueTypestring (enum)否-变量值的数据类型。可选值:string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp
app.pluginInputs[].requiredboolean否-该变量是否必填
app.pluginInputs[].defaultValueobject | array | string | number | boolean | null否-变量默认值
app.pluginInputs[].referencePlaceholderstring否-引用变量时展示的占位提示
app.pluginInputs[].isRichTextboolean否-是否使用富文本编辑器输入
app.pluginInputs[].placeholderstring否-变量输入框占位提示
app.pluginInputs[].maxLengthinteger否-文本变量最大输入长度。最小值:0;最大值:9007199254740991
app.pluginInputs[].minLengthinteger否-文本变量最小输入长度。最小值:0;最大值:9007199254740991
app.pluginInputs[].markListobject[]否-数值滑块变量的刻度配置
app.pluginInputs[].markList[].labelstring是-刻度展示名称
app.pluginInputs[].markList[].valuenumber是-刻度值
app.pluginInputs[].stepnumber否-数值变量步进值
app.pluginInputs[].maxnumber否-数值变量最大值
app.pluginInputs[].minnumber否-数值变量最小值
app.pluginInputs[].precisionnumber否-数值变量小数精度
app.pluginInputs[].canSelectFileboolean否-该变量是否允许选择普通文件
app.pluginInputs[].canSelectImgboolean否-该变量是否允许选择图片
app.pluginInputs[].canSelectVideoboolean否-该变量是否允许选择视频
app.pluginInputs[].canSelectAudioboolean否-该变量是否允许选择音频
app.pluginInputs[].canSelectCustomFileExtensionboolean否-该变量是否允许选择自定义扩展名文件
app.pluginInputs[].customFileExtensionListstring[]否-该变量允许选择的自定义文件扩展名列表
app.pluginInputs[].canLocalUploadboolean否-该变量是否允许从本地上传文件
app.pluginInputs[].canUrlUploadboolean否-该变量是否允许通过 URL 引入文件
app.pluginInputs[].maxFilesinteger否-该变量允许选择的最大文件数量。最小值:0;最大值:9007199254740991
app.pluginInputs[].timeGranularitystring (enum)否-时间变量的选择粒度。可选值:day , hour , minute , second
app.pluginInputs[].timeRangeStartstring否-时间范围变量的起始时间
app.pluginInputs[].timeRangeEndstring否-时间范围变量的结束时间
app.pluginInputs[].datasetOptionsobject[]否-知识库选择变量的可选知识库列表
app.pluginInputs[].datasetOptions[].datasetIdstring是-可选知识库 ID
app.pluginInputs[].datasetOptions[].avatarstring是-可选知识库头像
app.pluginInputs[].datasetOptions[].namestring是-可选知识库名称
app.pluginInputs[].datasetOptions[].vectorModelobject是--
app.pluginInputs[].datasetOptions[].errorstring否--
app.pluginInputs[].customInputConfigobject否-变量在编辑器中的自定义输入配置
app.pluginInputs[].customInputConfig.selectValueTypeListstring (enum)[]`否-自定义输入允许选择的数据类型列表
app.pluginInputs[].customInputConfig.showDefaultValueboolean否-是否在编辑器中展示默认值配置
app.pluginInputs[].customInputConfig.showDescriptionboolean否-是否在编辑器中展示字段说明配置
app.pluginInputs[].customInputConfig.hideBottomDividerboolean否-是否隐藏变量编辑区域底部分割线
app.pluginInputs[].selectedTypestring (enum)否-多类型输入当前选中的渲染组件类型。可选值:reference , input , textarea , numberInput , switch , select , multipleSelect , JSONEditor , addInputParam , customVariable , selectApp , selectLLMModel , settingLLMModel , selectDataset , selectDatasetParamsModal , settingDatasetQuotePrompt , hidden , custom , selectSkill , selectTool 等
app.pluginInputs[].renderTypeListstring (enum)[]`是-该输入在编辑器中允许使用的渲染组件类型
app.pluginInputs[].valueDescstring否-输入值说明,通常用于展示引用值含义
app.pluginInputs[].valueobject | array | string | number | boolean | null否-节点输入当前值
app.pluginInputs[].debugLabelstring否-调试模式下展示的输入名称
app.pluginInputs[].descriptionstring否-节点输入说明
app.pluginInputs[].toolDescriptionstring否-作为工具调用参数时的语义说明
app.pluginInputs[].defaultToAgentGeneratedboolean否-工具输入缺少保存选择时,是否默认由 Agent 生成
app.pluginInputs[].canAgentGeneratedboolean否-该输入是否允许由 Agent 生成;未设置时按输入组件类型判断
app.pluginInputs[].customJsonSchemaobject否-工具参数自定义 JSON Schema 的 property 定义
app.pluginInputs[].enumstring否-已废弃:旧版枚举配置
app.pluginInputs[].inputListobject[]否-系统输入配置项列表
app.pluginInputs[].inputList[].keystring是-输入配置键名
app.pluginInputs[].inputList[].labelstring是-输入配置展示名称
app.pluginInputs[].inputList[].descriptionstring否-输入配置说明
app.pluginInputs[].inputList[].placeholderstring否-输入配置占位提示
app.pluginInputs[].inputList[].requiredboolean否-该输入配置是否必填
app.pluginInputs[].inputList[].inputTypestring (enum)是-输入配置渲染组件类型。可选值:input , numberInput , secret , switch , select
app.pluginInputs[].inputList[].valueobject否-输入配置默认值或密钥值
app.pluginInputs[].inputList[].listobject[]否-选择类输入配置的可选项
app.pluginInputs[].canEditboolean否-该输入是否允许在编辑器中修改
app.pluginInputs[].isProboolean否-该输入是否为商业版能力
app.pluginInputs[].isToolOutputboolean否-该输入是否来自工具输出
app.pluginInputs[].deprecatedboolean否-该输入是否已废弃
app.pluginInputs[].listobject[]否-选择类变量的可选项
app.pluginInputs[].list[].labelstring是-变量选项展示名称
app.pluginInputs[].list[].valuestring是-变量选项实际值
app.pluginInputs[].list[].iconstring否-变量选项图标
app.pluginInputs[].list[].descriptionstring否-变量选项说明
app.pluginInputs[].enumsobject[]否-已弃用。已废弃:旧版枚举变量选项
app.pluginInputs[].enums[].valuestring是-枚举项实际值
app.pluginInputs[].enums[].labelstring是-枚举项展示名称
app.useAgentSandboxboolean否-是否使用虚拟机

互斥参数分支(anyOf 选填其一)

  • 分支 1
字段类型必填默认值约束与说明
appIdstring是-应用 ID,仅工作流辅助生成会话返回。正则:^[0-9a-fA-F]{24}$
skillIdany否--
sourceType"workflowBuilder"是-工作流辅助生成会话资源类型。固定值:"workflowBuilder"
  • 分支 2
字段类型必填默认值约束与说明
appIdstring是-应用 ID,仅 ChatAgentHelper 会话返回。正则:^[0-9a-fA-F]{24}$
skillIdany否--
sourceType"chatAgentHelper"是-ChatAgentHelper 会话资源类型。固定值:"chatAgentHelper"
  • 分支 3
字段类型必填默认值约束与说明
appIdstring是-应用 ID,仅 App 会话返回。正则:^[0-9a-fA-F]{24}$
skillIdany否--
  • 分支 4
字段类型必填默认值约束与说明
appIdany否--
skillIdstring是-Skill Edit 调试 ID,仅 Skill Edit 会话返回。正则:^[0-9a-fA-F]{24}$
在 GitHub 上编辑

文件更新时间

本页导航

准备好开始了吗?

让你的企业知识真正被 AI 用起来