FastGPT API接口调用教程｜附源码

在企业知识库问答、智能客服、内部助手、AI 工作流自动化等场景中，很多团队会选择使用 FastGPT 来搭建基于大模型的应用。FastGPT 的优势在于：支持知识库检索、应用编排、工作流、对话调试、API 调用以及多模型接入。对于开发者来说，最常见的需求就是：如何在自己的业务系统中调用 FastGPT 应用接口？

本文将围绕 FastGPT API 的调用方式进行完整讲解，并提供 curl、Node.js、Python 等多种示例源码，帮助你快速把 FastGPT 集成到网站、后台系统、企业微信、飞书机器人或自有 SaaS 产品中。

一、FastGPT API 调用适合哪些场景？

FastGPT 并不仅仅是一个可视化的 AI 应用搭建平台，它更重要的能力在于可以将已经配置好的应用通过 API 对外提供服务。

常见使用场景包括：

1. 网站智能客服
   将 FastGPT 应用接入官网、商城、帮助中心，实现自动答疑。

2. 企业内部知识库问答
   把公司制度、产品文档、售后文档、技术手册导入知识库，通过 API 接入内部系统。

3. 业务系统智能助手
   在 CRM、ERP、OA、工单系统中集成 FastGPT，实现智能总结、智能回复、数据解释。

4. 微信、飞书、钉钉机器人
   将用户消息转发给 FastGPT，再把 FastGPT 的回答返回到群聊或私聊。

5. AI 工作流自动化
   通过 FastGPT 编排多个节点，例如知识库检索、条件判断、HTTP 请求、文本生成等，然后由外部系统通过 API 调用。

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

在正式写代码之前，需要先完成 FastGPT 后台中的相关配置。

1. 创建 FastGPT 应用

进入 FastGPT 控制台后，可以创建一个新的应用，例如：

• 知识库问答应用
• 简单聊天应用
• 工作流应用
• 客服问答应用

创建完成后，建议先在 FastGPT 页面中进行调试，确认应用能够正常回答问题。

2. 获取 API Key

进入目标应用的配置页面，一般可以在类似以下位置找到 API 调用配置：

应用设置 / 发布渠道 / API 访问 / API Key

生成或复制 API Key。

API Key 是调用接口时的身份凭证，通常需要放在请求头中：

Authorization: Bearer YOUR_API_KEY

请注意：

• 不要将 API Key 直接暴露在前端代码中；
• 推荐由后端服务转发请求；
• 如果 API Key 泄露，应及时在 FastGPT 后台重新生成；
• 不同应用建议使用不同的 API Key，便于权限管理和问题排查。

3. 确认接口地址

如果你使用的是官方或云端 FastGPT，接口地址通常类似：

https://你的FastGPT域名/api/v1/chat/completions

如果你是私有化部署，则可能是：

http://你的服务器地址:端口/api/v1/chat/completions

例如：

https://fastgpt.example.com/api/v1/chat/completions

FastGPT 的对话接口在设计上通常兼容 OpenAI Chat Completions 的调用风格，因此接入成本较低。

三、FastGPT API 请求格式说明

一个常见的 FastGPT API 请求如下：

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

下面解释几个常用字段。

1. chatId

chatId 用于标识一次会话。

例如：

"chatId": "user_10001"

你可以将它设置为：

• 用户 ID
• 订单 ID
• 客服会话 ID
• 随机 UUID

如果希望同一个用户保持上下文，可以为该用户使用固定的 chatId。

如果希望每次都是全新对话，可以每次生成一个新的 chatId。

2. stream

stream 用于控制是否使用流式输出。

"stream": false

当设置为 false 时，接口会等待完整回答生成后一次性返回。

当设置为 true 时，接口会边生成边返回，适合聊天机器人、网页对话框等需要打字机效果的场景。

3. detail

detail 用于控制是否返回更详细的调试信息。

"detail": false

如果你只需要最终回答，设置为 false 即可。

如果你希望查看知识库引用、执行过程、工作流节点信息等，可以尝试设置为 true，具体返回内容会根据 FastGPT 版本和应用类型有所不同。

4. messages

messages 是对话消息数组，结构通常与 OpenAI Chat API 类似：

"messages": [
  {
    "role": "user",
    "content": "什么是 FastGPT？"
  }
]

常见角色包括：

通常调用 FastGPT 应用时，只需要传入用户问题即可。

四、使用 curl 调用 FastGPT API

最简单的测试方式是使用 curl。

请将下面代码中的：

• YOUR_FASTGPT_HOST
• YOUR_API_KEY

替换成你自己的地址和密钥。

curl --location 'https://YOUR_FASTGPT_HOST/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "chatId": "test-chat-001",
    "stream": false,
    "detail": false,
    "messages": [
      {
        "role": "user",
        "content": "请用三句话介绍一下 FastGPT"
      }
    ]
  }'

如果调用成功，你会收到类似下面的响应：

{
  "id": "chatcmpl-xxx",
  "model": "",
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 80,
    "total_tokens": 203
  },
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "FastGPT 是一个面向企业和开发者的 AI 应用搭建平台..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ]
}

最终回答通常可以从以下位置读取：

choices[0].message.content

五、Node.js 调用 FastGPT API 示例

下面示例适用于 Node.js 18 及以上版本，因为 Node.js 18 已经内置了 fetch。

1. 普通非流式调用

新建文件：

fastgpt-demo.js

写入以下代码：

const FASTGPT_API_URL = 'https://YOUR_FASTGPT_HOST/api/v1/chat/completions';
const FASTGPT_API_KEY = 'YOUR_API_KEY';

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

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

  const data = await response.json();
  return data?.choices?.[0]?.message?.content || '';
}

async function main() {
  try {
    const answer = await callFastGPT('请介绍一下 FastGPT API 的主要用途');
    console.log('FastGPT 回复：');
    console.log(answer);
  } catch (error) {
    console.error('调用失败：', error.message);
  }
}

main();

运行：

node fastgpt-demo.js

2. 使用环境变量保存 API Key

实际项目中，不建议把 API Key 写死在代码里。可以使用环境变量。

安装 dotenv：

npm install dotenv

创建 .env 文件：

FASTGPT_API_URL=https://YOUR_FASTGPT_HOST/api/v1/chat/completions
FASTGPT_API_KEY=YOUR_API_KEY

修改代码：

require('dotenv').config();

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

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

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

  const data = await response.json();
  return data.choices?.[0]?.message?.content;
}

callFastGPT('如何把 FastGPT 接入自己的业务系统？', 'user-9527')
  .then(console.log)
  .catch(console.error);

这样做的好处是：

• API Key 不会直接出现在代码仓库中；
• 不同环境可以使用不同配置；
• 部署时可以通过 Docker、PM2、CI/CD 注入环境变量。

六、Python 调用 FastGPT API 示例

Python 后端、数据处理脚本或自动化任务中也经常需要调用 FastGPT。

1. 安装 requests

pip install requests

2. 编写调用代码

创建文件：

fastgpt_demo.py

代码如下：

import requests

FASTGPT_API_URL = "https://YOUR_FASTGPT_HOST/api/v1/chat/completions"
FASTGPT_API_KEY = "YOUR_API_KEY"


def call_fastgpt(question: str, chat_id: str = "python-user-001") -> str:
    headers = {
        "Authorization": f"Bearer {FASTGPT_API_KEY}",
        "Content-Type": "application/json"
    }

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

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

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

    data = response.json()
    return data.get("choices", [{}])[0].get("message", {}).get("content", "")


if __name__ == "__main__":
    answer = call_fastgpt("请说明 FastGPT 知识库问答的工作原理")
    print("FastGPT 回复：")
    print(answer)

运行：

python fastgpt_demo.py

七、流式调用 FastGPT API

在真实聊天产品中，用户更希望 AI 能够像打字一样逐字输出，而不是等几十秒后一次性返回。这时就需要开启流式调用。

请求参数中设置：

"stream": true

1. curl 流式调用示例

curl --location 'https://YOUR_FASTGPT_HOST/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "chatId": "stream-chat-001",
    "stream": true,
    "detail": false,
    "messages": [
      {
        "role": "user",
        "content": "请写一段关于人工智能客服的介绍"
      }
    ]
  }'

流式响应通常会以 Server-Sent Events，也就是 SSE 的形式返回，例如：

data: {"choices":[{"delta":{"content":"人工"}}]}

data: {"choices":[{"delta":{"content":"智能"}}]}

data: {"choices":[{"delta":{"content":"客服"}}]}

data: [DONE]

2. Node.js 流式调用示例

下面是一个简化版的 Node.js 流式读取示例：

const FASTGPT_API_URL = 'https://YOUR_FASTGPT_HOST/api/v1/chat/completions';
const FASTGPT_API_KEY = 'YOUR_API_KEY';

async function streamFastGPT(question) {
  const response = await fetch(FASTGPT_API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${FASTGPT_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatId: 'node-stream-user-001',
      stream: true,
      detail: false,
      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');

  console.log('FastGPT 流式回复：');

  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:\s*/, '');

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

      try {
        const json = JSON.parse(data);
        const content = json.choices?.[0]?.delta?.content || '';
        process.stdout.write(content);
      } catch (err) {
        // 某些情况下 chunk 可能不完整，生产环境建议做更严谨的缓存处理
      }
    }
  }
}

streamFastGPT('请用通俗语言解释什么是 RAG')
  .catch(console.error);

这个示例会把 FastGPT 返回的内容实时输出到控制台。

八、在 Express 中封装 FastGPT 接口

很多项目会使用 Node.js 写后端接口。推荐做法是：前端请求你的后端，你的后端再去调用 FastGPT。

这样可以避免 API Key 暴露到浏览器。

1. 安装依赖

npm init -y
npm install express dotenv cors

2. 创建 .env

PORT=3000
FASTGPT_API_URL=https://YOUR_FASTGPT_HOST/api/v1/chat/completions
FASTGPT_API_KEY=YOUR_API_KEY

3. 创建 server.js

require('dotenv').config();

const express = require('express');
const cors = require('cors');

const app = express();

app.use(cors());
app.use(express.json());

app.post('/api/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: userId || 'anonymous-user',
        stream: false,
        detail: false,
        messages: [
          {
            role: 'user',
            content: question
          }
        ]
      })
    });

    if (!response.ok) {
      const errorText = await response.text();
      return res.status(response.status).json({
        message: 'FastGPT API 调用失败',
        error: errorText
      });
    }

    const data = await response.json();

    res.json({
      answer: data.choices?.[0]?.message?.content || '',
      raw: data
    });
  } catch (error) {
    res.status(500).json({
      message: '服务器内部错误',
      error: error.message
    });
  }
});

app.listen(process.env.PORT, () => {
  console.log(`Server running at http://localhost:${process.env.PORT}`);
});

启动服务：

node server.js

测试：

curl --location 'http://localhost:3000/api/chat' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "user_001",
    "question": "FastGPT 适合做企业知识库吗？"
  }'

九、前端页面调用后端接口示例

如果你有一个简单的网页，可以通过前端请求自己的后端接口。

  
  


  
FastGPT 聊天示例

  
  

  发送

  
回答：
  


  

需要注意，前端页面不要直接请求 FastGPT API 并携带 API Key，否则用户可以通过浏览器开发者工具看到密钥。

十、常见错误与排查方法

1. 401 Unauthorized

原因通常是 API Key 错误或请求头格式不正确。

请检查：

Authorization: Bearer YOUR_API_KEY

常见错误写法包括：

Authorization: YOUR_API_KEY

或者：

Authorization: Bearer

2. 404 Not Found

可能原因：

• API 地址写错；
• FastGPT 服务没有正常启动；
• 部署时反向代理路径配置错误；
• 接口版本路径不正确。

建议检查接口地址是否为：

/api/v1/chat/completions

3. 500 Internal Server Error

可能原因：

• FastGPT 应用配置异常；
• 模型服务不可用；
• 知识库检索异常；
• 工作流节点配置错误；
• 上游模型 API Key 无效。

建议先在 FastGPT 控制台中手动调试应用，确认应用本身可以正常运行。

4. 请求超时

AI 生成内容需要一定时间，如果问题复杂或知识库检索较慢，可能会超时。

优化建议：

• 后端请求设置更长 timeout；
• 使用流式输出；
• 优化知识库分段和索引；
• 减少不必要的工作流节点；
• 控制用户问题长度。

十一、生产环境最佳实践

1. API Key 必须放在服务端

不要把 FastGPT API Key 写在：

• Vue 前端代码
• React 前端代码
• 小程序前端代码
• App 客户端代码

推荐架构：

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

2. 为不同用户维护 chatId

如果你希望每个用户都有独立上下文，可以这样设计：

const chatId = `user_${user.id}`;

如果是客服会话，可以这样设计：

const chatId = `ticket_${ticketId}`;

如果是订单助手，可以这样设计：

const chatId = `order_${orderId}`;

3. 做好限流和审计

为了防止接口被刷，建议在自己的后端增加：

• 用户登录校验；
• IP 限流；
• 用户每日调用次数限制；
• 敏感词过滤；
• 请求日志；
• 异常报警。

4. 合理处理错误信息

不要把 FastGPT 或模型服务返回的完整错误信息直接暴露给普通用户。可以在服务端记录详细日志，对用户返回更友好的提示。

例如：

{
  "message": "AI 服务暂时不可用，请稍后再试"
}

5. 配置知识库引用展示

如果你的应用是知识库问答，可以考虑开启详细返回，并在前端展示引用来源。这样可以提升回答可信度。

例如展示：

参考资料：
1. 《售后服务政策》第 3 条
2. 《产品使用手册》第 2 章

具体字段需要根据 FastGPT 实际返回结构进行解析。

十二、完整项目结构示例

一个简单的 FastGPT API 接入项目可以这样组织：

fastgpt-api-demo/
├── .env
├── package.json
├── server.js
└── public/
    └── index.html

其中：

• .env 保存 FastGPT 地址和 API Key；
• server.js 封装后端接口；
• index.html 作为简单测试页面；
• 前端只访问自己的后端，不直接访问 FastGPT。

十三、总结

本文介绍了 FastGPT API 的完整调用流程，包括：

• 如何创建应用并获取 API Key；
• FastGPT API 的常用请求参数；
• 使用 curl 进行接口测试；
• 使用 Node.js 调用 FastGPT；
• 使用 Python 调用 FastGPT；
• 实现流式输出；
• 在 Express 中封装后端接口；
• 前端如何安全调用；
• 常见错误排查和生产环境最佳实践。

总体来说，FastGPT API 的接入方式非常接近 OpenAI Chat Completions 风格。只要准备好应用、API Key 和接口地址，就可以很快接入自己的业务系统。

如果只是测试，可以直接使用 curl 或 Python 脚本；如果是生产项目，则建议通过后端服务统一封装 FastGPT 调用逻辑，并增加权限校验、限流、日志和异常处理。这样既能保证安全性，也方便后续维护和扩展。