FastGPT API接口调用教程｜2026最新版

本文面向希望将 FastGPT 接入到自有系统、网站、企业微信、飞书、钉钉、小程序、客服系统或内部业务平台的开发者，系统讲解 FastGPT API 的基本概念、接口调用方式、鉴权方法、常见参数、流式输出、知识库问答、应用对话以及实际开发中的最佳实践。

一、FastGPT 是什么？

FastGPT 是一个面向企业和开发者的 AI 应用平台，常用于搭建智能客服、知识库问答、企业内部助手、数据分析助手、业务流程自动化机器人等应用。

它的核心能力通常包括：

• AI 对话应用搭建
• 知识库问答
• 工作流编排
• 插件/工具调用
• 多轮上下文管理
• API 接口调用
• OpenAI 兼容接口调用
• 企业私有化部署

对于开发者来说，FastGPT 最大的价值之一就是：
你可以先在可视化界面中搭建好一个 AI 应用，然后通过 API 把这个应用能力接入到自己的系统里。

例如：

• 在官网中接入智能客服；
• 在 SaaS 系统中加入 AI 助手；
• 在企业微信中接入企业知识库机器人；
• 在后台管理系统中加入文档问答；
• 在内部工单系统中实现自动回复；
• 在小程序中提供智能咨询服务。

二、FastGPT API 的常见调用场景

在正式写代码之前，我们先了解一下 FastGPT API 常见的使用场景。

1. 调用应用进行对话

这是最常见的场景。
你在 FastGPT 中创建一个应用，比如“企业知识库助手”，然后通过 API 向它发送用户问题，FastGPT 返回回答。

适合场景：

• 智能客服；
• 网站在线问答；
• 企业知识库助手；
• 售前咨询机器人；
• 产品文档问答机器人。

2. 接入知识库问答

FastGPT 可以绑定知识库。
当用户提问时，系统会先从知识库中检索相关内容，再结合大模型生成答案。

适合场景：

• 公司制度查询；
• 产品手册问答；
• API 文档助手；
• 售后问题查询；
• 培训资料问答。

3. 工作流自动化

FastGPT 支持工作流编排，可以通过节点组合实现复杂业务逻辑。

例如：

1. 用户输入问题；
2. 判断问题类型；
3. 查询知识库；
4. 调用外部接口；
5. 整理结果；
6. 返回最终答案。

适合场景：

• 订单查询助手；
• 报表分析助手；
• 工单分流机器人；
• CRM 客户助手；
• 复杂业务问答系统。

4. 与第三方平台集成

FastGPT API 可以接入：

• 企业微信；
• 飞书；
• 钉钉；
• 微信公众号；
• 小程序；
• App；
• Web 网站；
• 客服系统；
• OA 系统；
• CRM 系统；
• ERP 系统。

只要你的系统可以发送 HTTP 请求，就可以调用 FastGPT API。

三、调用 FastGPT API 前的准备工作

在开始调用接口之前，一般需要准备以下内容。

1. 创建 FastGPT 应用

进入 FastGPT 控制台后，通常需要先创建一个应用。

常见应用类型包括：

• 简单对话应用；
• 知识库问答应用；
• 工作流应用；
• 插件增强应用。

创建应用后，需要完成模型配置、提示词设置、知识库绑定、工作流配置等操作。

2. 获取 API Key

API Key 是调用接口时的身份凭证。

一般可以在 FastGPT 的应用设置、API 访问配置或账号设置中生成。

调用接口时，通常需要在请求头中携带：

Authorization: Bearer YOUR_API_KEY

其中 YOUR_API_KEY 替换为你自己的密钥。

注意：API Key 具有调用权限，不要暴露在前端页面、GitHub 仓库、日志文件或公共文档中。

3. 获取接口地址

如果你使用的是官方云服务，接口地址通常是平台提供的 API 地址。

如果你是私有化部署，则接口地址可能类似：

https://your-domain.com/api

或者：

http://your-server-ip:3000/api

具体路径需要以你的 FastGPT 部署版本和接口文档为准。

4. 确认应用 ID

部分接口调用时需要传入应用 ID，例如：

{
  "appId": "your_app_id"
}

应用 ID 通常可以在应用详情页、应用设置或 API 调用说明中找到。

四、FastGPT API 的基本调用方式

FastGPT API 通常采用 HTTP 请求方式调用，常见格式为：

POST /api/xxx
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体一般是 JSON 格式，例如：

{
  "chatId": "user_001",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "请介绍一下你们公司的售后政策"
    }
  ]
}

其中：

五、使用 curl 调用 FastGPT API

curl 是最简单的测试方式，适合快速验证接口是否可用。

下面是一个示例：

curl --location --request POST 'https://your-fastgpt-domain.com/api/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "chatId": "demo-user-001",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下 FastGPT 的主要功能"
    }
  ]
}'

如果调用成功，通常会返回类似结果：

{
  "id": "chatcmpl_xxx",
  "model": "fastgpt-app",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "FastGPT 是一个用于构建 AI 应用和知识库问答系统的平台..."
      }
    }
  ]
}

不同版本、不同部署方式的返回字段可能略有差异，但核心内容通常都在回答字段中。

六、使用 JavaScript 调用 FastGPT API

如果你的后端是 Node.js，可以使用 fetch 或 axios 调用。

下面以 fetch 为例。

const API_URL = 'https://your-fastgpt-domain.com/api/v1/chat/completions';
const API_KEY = 'YOUR_API_KEY';

async function callFastGPT(question, chatId = 'user_001') {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatId,
      stream: false,
      detail: false,
      messages: [
        {
          role: 'user',
          content: question
        }
      ]
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`FastGPT API 调用失败：${errorText}`);
  }

  const data = await response.json();
  return data;
}

callFastGPT('请用一句话介绍 FastGPT')
  .then(result => {
    console.log('返回结果：', result);
  })
  .catch(error => {
    console.error(error);
  });

在真实项目中，建议把 API Key 放到服务端环境变量中：

FASTGPT_API_KEY=your_api_key
FASTGPT_API_URL=https://your-fastgpt-domain.com/api/v1/chat/completions

然后在代码中读取：

const API_KEY = process.env.FASTGPT_API_KEY;
const API_URL = process.env.FASTGPT_API_URL;

七、使用 Python 调用 FastGPT API

Python 后端也非常适合调用 FastGPT API。
下面使用 requests 库演示。

import requests

API_URL = "https://your-fastgpt-domain.com/api/v1/chat/completions"
API_KEY = "YOUR_API_KEY"

def call_fastgpt(question, chat_id="user_001"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "chatId": chat_id,
        "stream": False,
        "detail": False,
        "messages": [
            {
                "role": "user",
                "content": question
            }
        ]
    }

    response = requests.post(API_URL, headers=headers, json=payload, timeout=60)

    if response.status_code != 200:
        raise Exception(f"FastGPT API 调用失败：{response.status_code}, {response.text}")

    return response.json()

if __name__ == "__main__":
    result = call_fastgpt("请介绍一下 FastGPT 的知识库问答能力")
    print(result)

如果你希望只提取回答内容，可以根据实际返回结构处理：

answer = result["choices"][0]["message"]["content"]
print(answer)

八、流式输出调用方式

在聊天机器人场景中，如果模型生成的内容较长，用户等待完整结果返回会感觉比较慢。

这时可以使用流式输出。

流式输出的特点是：

• 模型边生成边返回；
• 前端可以逐字显示；
• 用户体验更接近 ChatGPT；
• 适合长文本生成、客服聊天、知识库问答等场景。

请求时通常将：

"stream": true

示例：

curl --location --request POST 'https://your-fastgpt-domain.com/api/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "chatId": "stream-user-001",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "请详细介绍 FastGPT API 的调用流程"
    }
  ]
}'

流式响应通常采用类似 SSE 的格式：

data: {"choices":[{"delta":{"content":"FastGPT"}}]}

data: {"choices":[{"delta":{"content":" API"}}]}

data: {"choices":[{"delta":{"content":" 的调用流程包括..."}}]}

data: [DONE]

前端可以监听响应流，并把每次返回的 content 拼接起来显示。

九、Node.js 处理流式响应示例

下面是一个简单示例，用于读取 FastGPT 的流式输出。

async function callFastGPTStream(question) {
  const response = await fetch('https://your-fastgpt-domain.com/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FASTGPT_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatId: 'stream-user-001',
      stream: true,
      messages: [
        {
          role: 'user',
          content: question
        }
      ]
    })
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder('utf-8');

  let fullText = '';

  while (true) {
    const { done, value } = await reader.read();

    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    const lines = chunk.split('\n').filter(line => line.trim());

    for (const line of lines) {
      if (!line.startsWith('data:')) continue;

      const data = line.replace('data:', '').trim();

      if (data === '[DONE]') {
        console.log('流式输出结束');
        return fullText;
      }

      try {
        const json = JSON.parse(data);
        const content = json.choices?.[0]?.delta?.content || '';

        if (content) {
          fullText += content;
          process.stdout.write(content);
        }
      } catch (err) {
        // 某些情况下 chunk 可能被截断，需要根据实际情况做更健壮的解析
      }
    }
  }

  return fullText;
}

十、多轮对话如何处理？

多轮对话是 AI 应用中非常重要的能力。

常见方式有两种：

方式一：使用固定 chatId

如果 FastGPT 服务端会根据 chatId 保存上下文，则你只需要为每个用户或会话生成唯一的 chatId。

例如：

{
  "chatId": "user_10086",
  "messages": [
    {
      "role": "user",
      "content": "我想了解你们的会员政策"
    }
  ]
}

下一次同一个用户继续提问：

{
  "chatId": "user_10086",
  "messages": [
    {
      "role": "user",
      "content": "那高级会员有什么权益？"
    }
  ]
}

系统就可以基于同一个会话上下文进行回答。

方式二：由业务系统维护 messages

如果你希望完全控制上下文，也可以在自己的业务系统中维护历史消息。

例如：

{
  "chatId": "custom-session-001",
  "messages": [
    {
      "role": "user",
      "content": "FastGPT 是什么？"
    },
    {
      "role": "assistant",
      "content": "FastGPT 是一个 AI 应用构建平台。"
    },
    {
      "role": "user",
      "content": "它适合做企业知识库吗？"
    }
  ]
}

这种方式更灵活，但需要注意上下文长度限制。
如果历史消息过多，建议进行摘要压缩，避免请求过大、成本过高或响应变慢。

十一、FastGPT API 参数详解

不同版本的 FastGPT API 参数可能略有差异，但常见参数包括以下几类。

1. chatId

会话唯一标识。

建议使用：

用户ID + 场景ID

例如：

user_9527_customer_service

这样可以避免不同业务场景之间上下文混淆。

2. stream

是否开启流式输出。

"stream": true

适合前端聊天页面。

"stream": false

适合后端一次性获取结果。

3. detail

是否返回详细信息。

如果设置为 true，可能会返回知识库检索结果、使用的模块信息、调试信息等。
开发调试阶段可以开启，生产环境建议根据需要决定。

4. messages

对话消息数组。

常见格式：

[
  {
    "role": "user",
    "content": "你好"
  }
]

role 常见取值：

5. variables

部分 FastGPT 应用或工作流支持变量传入。

例如，你的工作流中定义了用户姓名、订单号、城市等变量，则可以在 API 调用时传入：

{
  "variables": {
    "userName": "张三",
    "orderId": "NO202601010001",
    "city": "上海"
  }
}

这样 FastGPT 在执行工作流时就可以使用这些业务数据。

十二、在 Web 项目中接入 FastGPT 的推荐架构

很多新手会直接在前端调用 FastGPT API，这种做法并不推荐。

原因是：

• API Key 会暴露；
• 无法控制调用频率；
• 容易被恶意刷接口；
• 不方便记录日志；
• 不方便做用户权限校验；
• 无法统一处理敏感词、审计和限流。

更推荐的架构是：

浏览器 / 小程序 / App
        ↓
你的后端服务
        ↓
FastGPT API

也就是说：

1. 前端把用户问题发送给你的后端；
2. 后端校验用户身份；
3. 后端调用 FastGPT API；
4. 后端将结果返回给前端；
5. 后端记录日志、消耗额度、调用状态等信息。

这样更安全，也更适合生产环境。

十三、Express 后端代理示例

下面是一个简单的 Node.js Express 后端接口示例。

import express from 'express';

const app = express();
app.use(express.json());

app.post('/api/ai/chat', async (req, res) => {
  try {
    const { question, userId } = req.body;

    if (!question) {
      return res.status(400).json({
        message: 'question 不能为空'
      });
    }

    const response = await fetch(process.env.FASTGPT_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.FASTGPT_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        chatId: `user_${userId || 'anonymous'}`,
        stream: false,
        detail: false,
        messages: [
          {
            role: 'user',
            content: question
          }
        ]
      })
    });

    const data = await response.json();

    res.json({
      success: true,
      data
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      message: error.message
    });
  }
});

app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});

前端调用自己的后端接口即可：

const res = await fetch('/api/ai/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: '10001',
    question: '你们的退款政策是什么？'
  })
});

const data = await res.json();
console.log(data);

十四、知识库问答调用注意事项

如果你的 FastGPT 应用绑定了知识库，API 调用流程通常不需要额外改变。
你只需要调用应用接口，FastGPT 会自动完成：

1. 用户问题分析；
2. 向量检索；
3. 找到相关文档片段；
4. 组装上下文；
5. 调用大模型生成答案；
6. 返回最终结果。

但为了提升知识库问答效果，建议注意以下几点。

1. 文档切分要合理

如果文档切分太大，检索结果可能不够精准。
如果切分太小，回答可能缺少上下文。

建议按照：

• 标题；
• 段落；
• 问答对；
• 业务流程；
• 产品模块；

进行结构化整理。

2. 文档内容要干净

尽量减少无意义内容，例如：

• 页眉页脚；
• 重复导航；
• 乱码；
• 多余空格；
• 无关广告；
• 过期说明。

知识库质量直接影响最终回答质量。

3. 问答型内容效果更好

如果你的业务是客服问答，可以把知识库整理成 FAQ 格式：

问题：如何申请退款？
答案：用户可以在订单详情页点击“申请退款”，系统将在1-3个工作日内审核。

这种结构对检索和回答都非常友好。

4. 定期更新知识库

企业政策、产品功能、价格方案经常变化。
如果知识库不更新，AI 很可能根据旧内容回答，导致用户误解。

建议建立知识库更新机制，例如：

• 每周同步一次文档；
• 产品发布后立即更新；
• 客服高频问题定期整理；
• 过期内容定期清理。

十五、常见错误与解决方法

1. 401 Unauthorized

原因通常是 API Key 错误或请求头缺失。

检查：

Authorization: Bearer YOUR_API_KEY

注意 Bearer 后面有一个空格。

2. 404 Not Found

可能原因：

• API 地址写错；
• 部署路径不正确；
• 接口版本不一致；
• 网关转发配置错误。

建议先使用 curl 直接测试接口地址。

3. 500 Internal Server Error

可能原因：

• FastGPT 服务异常；
• 模型服务不可用；
• 知识库检索失败；
• 工作流节点配置错误；
• 外部插件接口异常。

建议查看 FastGPT 服务端日志。

4. 请求超时

可能原因：

• 模型响应较慢；
• 知识库检索耗时较长；
• 问题过于复杂；
• 网络不稳定；
• 后端超时时间设置过短。

解决方式：

• 开启流式输出；
• 增加请求超时时间；
• 优化知识库；
• 减少上下文长度；
• 检查模型服务状态。

5. 返回内容不准确

可能原因：

• 知识库内容不完整；
• 提示词设计不合理；
• 检索参数不合适；
• 用户问题太模糊；
• 模型能力不足。

优化方向：

• 完善知识库；
• 增加 FAQ；
• 优化应用提示词；
• 引导用户补充信息；
• 开启引用来源或详细返回信息进行排查。

十六、生产环境最佳实践

1. 不要在前端暴露 API Key

这是最重要的一点。
所有 FastGPT API 调用都应该经过你的服务端代理。

2. 增加限流机制

例如：

• 单用户每分钟最多请求 20 次；
• 单 IP 每小时最多请求 300 次；
• 未登录用户限制更严格；
• 异常请求自动封禁。

这样可以防止恶意刷接口。

3. 记录调用日志

建议记录：

• 用户 ID；
• 会话 ID；
• 用户问题；
• AI 回答；
• 响应时间；
• 是否成功；
• 错误信息；
• token 或费用消耗。

这些数据有助于后续排查问题和优化效果。

4. 做敏感信息过滤

在企业场景中，用户可能输入手机号、身份证号、银行卡号、合同信息等敏感数据。

建议在发送给 FastGPT 前做必要脱敏：

13812345678 → 138****5678

尤其是在涉及外部模型服务时，更要重视数据安全。

5. 设置合理的超时时间

AI 接口响应时间通常比普通接口更长。
建议后端超时时间设置在 30 秒到 120 秒之间，并根据业务情况调整。

对于长回答，优先使用流式输出。

6. 准备降级方案

生产环境中，模型服务可能出现不可用或响应慢的情况。
建议准备降级策略：

• 返回固定客服提示；
• 转人工客服；
• 切换备用模型；
• 使用缓存回答；
• 提示用户稍后重试。

十七、一个完整的调用流程总结

FastGPT API 接入流程可以总结为以下几步：

1. 创建 FastGPT 应用；
2. 配置模型、提示词、知识库或工作流；
3. 获取 API Key；
4. 获取 API 调用地址；
5. 在后端服务中封装调用方法；
6. 前端请求自己的后端接口；
7. 后端调用 FastGPT API；
8. 获取 AI 回复；
9. 返回给前端展示；
10. 记录日志并持续优化。

整体流程如下：

用户输入问题
    ↓
前端提交到业务后端
    ↓
业务后端校验用户身份和权限
    ↓
业务后端调用 FastGPT API
    ↓
FastGPT 执行应用、知识库检索或工作流
    ↓
大模型生成回答
    ↓
FastGPT 返回结果
    ↓
业务后端处理结果并记录日志
    ↓
前端展示 AI 回复

十八、结语

FastGPT API 的核心价值在于：
它让开发者不需要从零开发复杂的 AI 应用系统，而是可以先通过 FastGPT 的可视化能力快速搭建应用，再通过 API 将能力集成到自己的业务系统中。

对于普通对话场景，你只需要掌握 API Key、请求地址、chatId、messages 和 stream 等基础参数即可完成接入。
对于企业级场景，还需要重点关注知识库质量、权限控制、日志审计、限流策略、数据安全和系统稳定性。

如果你正在开发智能客服、企业知识库助手、AI 助理、业务流程机器人或内部自动化系统，那么 FastGPT API 是一个非常值得使用的接口能力。通过合理的应用配置和规范的接口封装，可以快速把 AI 能力稳定地接入到真实业务中。