FastGPT API接口调用教程｜附完整命令

在企业知识库、智能客服、AI 助手和自动化工作流场景中，FastGPT 是一个非常常见且实用的开源 AI 应用平台。它可以帮助用户快速搭建基于大语言模型的知识库问答、工作流应用、对话机器人等系统。除了在 Web 页面中直接使用 FastGPT 之外，很多开发者更关心的是：如何通过 API 接口调用 FastGPT 应用，将其集成到自己的业务系统中？

本文将围绕 FastGPT API 接口调用进行完整讲解，包括 API 调用前的准备工作、接口地址、鉴权方式、请求参数说明、curl 命令示例、Node.js 示例、Python 示例，以及常见问题排查。阅读完本文后，你可以直接复制命令进行测试，并将 FastGPT 接入到自己的项目中。

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

FastGPT API 的核心价值在于：让你可以通过程序调用已经配置好的 FastGPT 应用能力。

常见使用场景包括：

1. 企业官网智能客服

   • 将 FastGPT 接入官网聊天窗口；
   • 用户输入问题后，由 FastGPT 根据知识库自动回答；
   • 支持产品介绍、售后说明、常见问题解答等。

2. 内部知识库问答系统

   • 将公司制度、操作手册、项目文档上传到 FastGPT；
   • 员工通过内部系统提问；
   • 后端调用 FastGPT API 返回答案。

3. 微信公众号 / 小程序机器人

   • 用户在公众号发送消息；
   • 服务端接收消息后调用 FastGPT API；
   • 将回答结果返回给用户。

4. 飞书、企业微信、钉钉机器人

   • 通过机器人消息事件触发调用；
   • FastGPT 返回结构化回答；
   • 用于内部办公自动化。

5. 自定义业务系统集成

   • CRM、ERP、工单系统、数据平台等；
   • 通过 API 将自然语言问答能力集成进去。

二、调用 FastGPT API 前需要准备什么？

在正式调用 FastGPT API 之前，你需要确认以下几项信息。

1. FastGPT 服务地址

如果你使用的是官方云服务，则接口地址通常是官方提供的域名。

如果你是私有化部署 FastGPT，则接口地址一般是你自己的服务域名，例如：

https://fastgpt.example.com

或本地测试地址：

http://localhost:3000

后续示例中，我们统一使用：

https://fastgpt.example.com

请在实际调用时替换成你的真实 FastGPT 地址。

2. API Key

FastGPT API 通常需要通过 API Key 鉴权。你需要在 FastGPT 控制台中找到对应应用的 API Key。

一般操作路径类似如下：

进入 FastGPT 后台
→ 选择目标应用
→ 找到“发布”或“API访问”
→ 创建或复制 API Key

API Key 通常类似：

fastgpt-xxxxxxxxxxxxxxxxxxxxxxxx

调用接口时，需要将它放在请求头中：

Authorization: Bearer fastgpt-xxxxxxxxxxxxxxxxxxxxxxxx

注意：API Key 具有调用权限，请不要暴露在前端代码、公开仓库或日志中。建议由后端服务统一保存和调用。

3. 应用 ID 或 Chat ID

根据 FastGPT 不同版本、不同接口设计，调用时可能需要指定应用相关信息。例如：

• App ID；
• Chat ID；
• Collection ID；
• 对话 ID；
• 用户 ID。

不过在 OpenAI 兼容接口中，通常只需要 API Key 和模型名称即可。FastGPT 会根据 API Key 识别对应应用。

三、FastGPT 常见 API 调用方式

FastGPT 常见 API 调用方式主要有两类：

1. OpenAI 兼容接口
2. FastGPT 原生接口

如果你的 FastGPT 版本支持 OpenAI 格式，那么推荐优先使用 OpenAI 兼容接口。因为这种方式更标准，迁移成本低，也方便接入已有的 OpenAI SDK。

四、OpenAI 兼容接口说明

OpenAI 兼容接口通常使用如下路径：

POST /api/v1/chat/completions

完整接口地址示例：

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

请求方式：

POST

请求头：

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体通常包含：

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下 FastGPT"
    }
  ],
  "stream": false
}

其中：

五、完整 curl 非流式调用命令

下面是一个可以直接使用的 curl 调用示例。

请将：

https://fastgpt.example.com

替换为你的 FastGPT 服务地址，将：

YOUR_API_KEY

替换为你的真实 API Key。

curl --location --request POST 'https://fastgpt.example.com/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "请用三句话介绍 FastGPT 的主要功能"
      }
    ],
    "stream": false
  }'

正常情况下，你会得到类似下面的返回结果：

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "FastGPT 是一个用于构建 AI 应用的平台，支持知识库问答、工作流编排和智能客服等场景。它可以将企业文档、网页内容等数据接入知识库，并结合大语言模型生成准确回答。开发者还可以通过 API 将 FastGPT 集成到网站、系统或机器人中。"
      },
      "finish_reason": "stop"
    }
  ]
}

如果你只想获取最终回答文本，一般可以读取：

choices[0].message.content

六、完整 curl 流式调用命令

在聊天机器人、网页对话框、客服系统中，用户体验更好的方式通常是流式输出。流式输出可以让回答内容像打字一样逐步显示，而不是等完整回答生成后一次性返回。

将 stream 设置为 true 即可开启流式调用：

curl --location --request POST 'https://fastgpt.example.com/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "请详细说明 FastGPT 适合哪些业务场景"
      }
    ],
    "stream": true
  }'

流式返回通常是 SSE 格式，返回内容可能类似：

data: {"id":"chatcmpl-xxxx","choices":[{"delta":{"content":"FastGPT"},"index":0}]}

data: {"id":"chatcmpl-xxxx","choices":[{"delta":{"content":" 适合"},"index":0}]}

data: {"id":"chatcmpl-xxxx","choices":[{"delta":{"content":" 企业知识库"},"index":0}]}

data: [DONE]

在前端或后端处理中，需要逐行读取 data: 后面的 JSON，并拼接其中的：

choices[0].delta.content

七、携带上下文的多轮对话调用

如果你希望 FastGPT 能够理解上下文，就需要在 messages 中传入历史对话内容。

示例命令如下：

curl --location --request POST 'https://fastgpt.example.com/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业的企业知识库客服，请用简洁、准确的中文回答用户问题。"
      },
      {
        "role": "user",
        "content": "FastGPT 可以接入企业文档吗？"
      },
      {
        "role": "assistant",
        "content": "可以。FastGPT 支持将企业文档导入知识库，并结合大语言模型进行问答。"
      },
      {
        "role": "user",
        "content": "那它适合做内部员工问答系统吗？"
      }
    ],
    "stream": false
  }'

这里的关键点是：

• system 用于设置整体角色和回答风格；
• user 表示用户提问；
• assistant 表示历史回答；
• 最后一条通常是当前用户的问题。

需要注意的是，历史消息不能无限传入。消息越多，消耗的 token 越多，也会影响响应速度。因此在真实项目中，建议只保留最近几轮对话，或者对历史内容做摘要。

八、使用 Node.js 调用 FastGPT API

如果你的后端使用 Node.js，可以使用原生 fetch 或 axios 调用接口。下面以 Node.js 18+ 自带的 fetch 为例。

1. 非流式 Node.js 示例

创建文件：

touch fastgpt-chat.js

写入以下代码：

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

async function main() {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [
        {
          role: 'user',
          content: '请介绍一下 FastGPT API 的调用方式'
        }
      ],
      stream: false
    })
  });

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

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

main().catch(console.error);

运行命令：

node fastgpt-chat.js

2. Node.js 流式调用示例

流式调用适合实时输出内容：

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

async function main() {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [
        {
          role: 'user',
          content: '请写一段关于 FastGPT 应用场景的介绍'
        }
      ],
      stream: true
    })
  });

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

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

  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]') {
        process.stdout.write('\n');
        return;
      }

      try {
        const json = JSON.parse(data);
        const content = json.choices?.[0]?.delta?.content;
        if (content) {
          process.stdout.write(content);
        }
      } catch (err) {
        // 某些情况下 chunk 可能不是完整 JSON，可根据实际情况做缓冲处理
      }
    }
  }
}

main().catch(console.error);

运行：

node fastgpt-stream.js

九、使用 Python 调用 FastGPT API

Python 项目中可以使用 requests 库进行调用。

1. 安装 requests

pip install requests

如果你使用的是 Python 3，某些环境中需要执行：

pip3 install requests

2. Python 非流式调用示例

创建文件：

touch fastgpt_chat.py

写入代码：

import requests

API_URL = "https://fastgpt.example.com/api/v1/chat/completions"
API_KEY = "YOUR_API_KEY"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4o-mini",
    "messages": [
        {
            "role": "user",
            "content": "请用中文介绍 FastGPT 的 API 调用流程"
        }
    ],
    "stream": False
}

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

if response.status_code != 200:
    print("请求失败：", response.status_code)
    print(response.text)
else:
    data = response.json()
    print(data["choices"][0]["message"]["content"])

运行：

python fastgpt_chat.py

或：

python3 fastgpt_chat.py

3. Python 流式调用示例

import json
import requests

API_URL = "https://fastgpt.example.com/api/v1/chat/completions"
API_KEY = "YOUR_API_KEY"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4o-mini",
    "messages": [
        {
            "role": "user",
            "content": "请详细讲解 FastGPT 在智能客服中的应用"
        }
    ],
    "stream": True
}

response = requests.post(API_URL, headers=headers, json=payload, stream=True)

if response.status_code != 200:
    print("请求失败：", response.status_code)
    print(response.text)
else:
    for line in response.iter_lines():
        if not line:
            continue

        decoded_line = line.decode("utf-8")

        if not decoded_line.startswith("data:"):
            continue

        data = decoded_line.replace("data:", "").strip()

        if data == "[DONE]":
            print()
            break

        try:
            json_data = json.loads(data)
            content = json_data["choices"][0].get("delta", {}).get("content")
            if content:
                print(content, end="", flush=True)
        except Exception:
            pass

运行：

python fastgpt_stream.py

十、使用 OpenAI SDK 调用 FastGPT

如果 FastGPT 提供 OpenAI 兼容接口，你也可以使用 OpenAI SDK，只需要将 base_url 修改为 FastGPT 的接口地址。

1. Python OpenAI SDK 示例

安装 SDK：

pip install openai

示例代码：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://fastgpt.example.com/api/v1"
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "请介绍 FastGPT 的 OpenAI 兼容接口"
        }
    ]
)

print(completion.choices[0].message.content)

运行：

python openai_fastgpt.py

2. Node.js OpenAI SDK 示例

安装 SDK：

npm install openai

示例代码：

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://fastgpt.example.com/api/v1'
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      {
        role: 'user',
        content: '请说明如何用 Node.js 调用 FastGPT API'
      }
    ]
  });

  console.log(completion.choices[0].message.content);
}

main();

如果你的项目没有启用 ES Module，可以在 package.json 中加入：

{
  "type": "module"
}

运行：

node openai_fastgpt.js

十一、FastGPT 原生接口调用示例

部分 FastGPT 部署版本可能还提供原生接口，例如：

POST /api/v1/chat/completions

或者某些应用专用接口。不同版本参数可能略有差异，常见请求参数包括：

{
  "chatId": "my-chat-id",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "content": "你好，请介绍一下你自己",
      "role": "user"
    }
  ]
}

示例 curl：

curl --location --request POST 'https://fastgpt.example.com/api/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "chatId": "test-chat-001",
    "stream": false,
    "detail": false,
    "messages": [
      {
        "role": "user",
        "content": "FastGPT 如何接入企业知识库？"
      }
    ]
  }'

这里的 chatId 可以理解为一次会话的标识。对于同一个用户的连续对话，可以复用同一个 chatId，这样系统更容易管理上下文。

提醒：不同 FastGPT 版本的接口字段可能存在差异。如果调用失败，应以你当前部署版本的官方接口文档为准。

十二、接口参数详解

下面对常见参数做进一步说明。

1. model

"model": "gpt-4o-mini"

在 OpenAI 兼容接口中，model 是必填字段。对于 FastGPT 而言，实际使用哪个模型可能已经在应用配置中指定，因此这里的模型名称在某些环境中只是兼容字段。

建议写法：

"model": "gpt-4o-mini"

或根据你的 FastGPT 配置填写真实模型名。

2. messages

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

messages 是对话内容数组，最少需要包含一条用户消息。

常见角色包括：

3. stream

"stream": true

是否使用流式输出：

• false：等待完整结果后一次性返回；
• true：边生成边返回，适合聊天界面。

4. temperature

部分接口支持 temperature 参数，用于控制回答随机性：

"temperature": 0.7

一般来说：

• 0.1 到 0.3：回答更稳定，适合知识库问答；
• 0.5 到 0.8：回答更灵活，适合内容创作；
• 1.0 以上：随机性更强，但可能不够稳定。

知识库问答建议使用较低 temperature，例如：

"temperature": 0.2

5. max_tokens

部分接口支持限制回答长度：

"max_tokens": 1000

如果你的业务场景希望回答更简短，可以适当调小该值。

十三、在后端项目中的推荐封装方式

在真实项目中，不建议在业务代码各处直接写 curl 或重复请求逻辑。更推荐将 FastGPT API 调用封装成一个独立服务方法。

例如你可以封装成：

fastgptService.chat(userId, message)

内部处理：

1. 读取 API Key；
2. 拼接请求头；
3. 维护用户会话 ID；
4. 发送请求；
5. 解析返回结果；
6. 记录必要日志；
7. 处理异常情况。

伪代码如下：

async function chatWithFastGPT(userId, message) {
  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({
      model: 'gpt-4o-mini',
      messages: [
        {
          role: 'user',
          content: message
        }
      ],
      stream: false
    })
  });

  if (!response.ok) {
    throw new Error('FastGPT API 调用失败');
  }

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

环境变量配置示例：

FASTGPT_API_URL=https://fastgpt.example.com/api/v1/chat/completions
FASTGPT_API_KEY=YOUR_API_KEY

这样可以避免 API Key 硬编码在代码中，提高安全性和可维护性。

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

1. 401 Unauthorized

错误原因通常是鉴权失败。

可能情况包括：

• API Key 写错；
• 请求头没有携带 Authorization；
• Authorization 格式错误；
• API Key 已被删除或禁用。

正确格式应为：

Authorization: Bearer YOUR_API_KEY

注意 Bearer 后面有一个空格。

2. 404 Not Found

常见原因：

• 接口地址写错；
• FastGPT 服务地址不正确；
• 当前版本不支持该接口路径；
• 反向代理没有正确转发 /api 路径。

可以先测试服务是否可访问：

curl -I https://fastgpt.example.com

然后确认接口路径是否为：

/api/v1/chat/completions

3. 400 Bad Request

通常表示请求参数格式不正确。

建议检查：

• JSON 是否合法；
• messages 是否为数组；
• role 是否填写正确；
• content 是否为空；
• Content-Type 是否为 application/json。

你可以使用下面的命令检查 JSON 格式：

echo '{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "stream": false
}' | jq

如果没有安装 jq，可以使用：

brew install jq

或：

apt install jq

4. 响应很慢

可能原因包括：

• 模型本身响应较慢；
• 知识库检索内容过多；
• 提问过长；
• 历史上下文过多；
• 服务器资源不足；
• 网络链路不稳定。

优化建议：

1. 开启流式输出；
2. 减少历史消息数量；
3. 优化知识库分段；
4. 降低召回数量；
5. 使用更快的模型；
6. 检查服务器 CPU、内存和网络情况。

5. 返回内容不符合预期

如果 FastGPT 返回的答案不准确，可以从以下方面排查：

• 知识库文档是否已经成功导入；
• 文档分段是否合理；
• 向量模型是否配置正确；
• 应用提示词是否清晰；
• 问题是否过于模糊；
• 是否召回了错误的知识片段；
• temperature 是否过高。

对于知识库问答应用，建议在系统提示词中明确要求：

请优先根据知识库内容回答。如果知识库中没有相关信息，请明确说明“未在知识库中找到相关内容”，不要编造答案。

十五、生产环境调用建议

如果你准备在生产环境中使用 FastGPT API，建议重点关注以下几点。

1. API Key 不要放在前端

错误示例：

const API_KEY = 'fastgpt-xxxx';

如果这段代码出现在浏览器前端，用户可以通过开发者工具直接看到你的 API Key。

正确做法是：

• 前端请求你的业务后端；
• 后端调用 FastGPT；
• 后端将结果返回给前端。

2. 设置超时时间

调用大模型接口可能存在超时风险，建议在后端设置合理超时时间。例如 30 秒或 60 秒。

3. 记录请求日志

建议记录：

• 用户 ID；
• 请求时间；
• 问题内容；
• 响应状态；
• 耗时；
• 错误信息。

但不要记录敏感信息，如完整 API Key、用户隐私数据等。

4. 做好限流

如果应用面向大量用户，建议做限流，例如：

• 单用户每分钟最多请求 10 次；
• 单 IP 每分钟最多请求 30 次；
• 高峰期排队处理。

这样可以避免恶意请求导致成本失控。

5. 对输出内容做安全处理

如果 FastGPT 的回答会展示给终端用户，建议对输出做必要处理：

• HTML 转义；
• 敏感词过滤；
• Markdown 渲染安全检查；
• 避免直接执行模型返回的代码。

十六、一键测试脚本示例

你也可以写一个简单的 Shell 脚本，快速测试 FastGPT API 是否可用。

创建脚本：

touch test-fastgpt.sh
chmod +x test-fastgpt.sh

写入：

#!/bin/bash

API_URL="https://fastgpt.example.com/api/v1/chat/completions"
API_KEY="YOUR_API_KEY"

curl --location --request POST "$API_URL" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "你好，请确认 FastGPT API 是否调用成功"
      }
    ],
    "stream": false
  }'

执行：

./test-fastgpt.sh

如果返回了正常的 JSON 结果，说明 API 调用成功。

十七、总结

FastGPT API 调用的核心流程并不复杂，可以概括为四步：

1. 获取 FastGPT 服务地址；
2. 创建或复制 API Key；
3. 按照接口要求组装请求头和请求体；
4. 通过 curl、Node.js、Python 或 OpenAI SDK 发起调用。

最常用的接口形式是：

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

最关键的请求头是：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

最基础的请求体是：

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "stream": false
}

对于普通问答测试，推荐先使用非流式 curl 命令；对于聊天机器人和前端对话场景，建议使用流式调用，以获得更好的交互体验。生产环境中，要特别注意 API Key 安全、超时控制、限流、日志记录和异常处理。

只要掌握了本文中的命令和示例，你就可以快速将 FastGPT 集成到网站、业务系统、企业微信机器人、微信公众号、小程序或内部知识库平台中。