Coze API接口调用教程｜适合站长

对于站长来说，网站的核心竞争力不再只是“内容展示”，而是能否为用户提供更高效、更智能、更个性化的服务。无论是企业官网、资讯站、工具站、资源站，还是电商网站、教育网站、社区网站，都可以通过接入 AI 能力来提升用户体验。

Coze（扣子）是一个面向 AI Bot 创建与应用的平台，站长可以在 Coze 中搭建自己的智能体，然后通过 API 接口把智能体能力接入到网站中，例如：

• 网站 AI 客服；
• 文章智能摘要；
• 用户问题自动回复；
• 站内搜索增强；
• SEO 标题和描述生成；
• 表单内容智能分析；
• 商品推荐与咨询；
• 用户留言自动分类；
• 内容审核辅助；
• 在线工具类 AI 助手。

本文将从站长实际使用角度出发，介绍 Coze API 的基础概念、准备工作、接口调用方式、网站集成方案、安全注意事项以及常见问题，帮助你快速把 Coze 智能体接入自己的网站。

一、Coze API是什么？

Coze API 可以理解为 Coze 平台提供给开发者的一套接口。你可以先在 Coze 后台创建一个 Bot，也就是智能体，然后通过接口把用户的问题发送给这个 Bot，Bot 处理后再把结果返回给你的网站。

简单来说，调用流程如下：

用户访问网站
    ↓
用户在网站输入问题
    ↓
网站后端调用 Coze API
    ↓
Coze Bot 生成回答
    ↓
网站把回答展示给用户

站长不需要自己训练大模型，也不需要单独部署复杂的 AI 服务，只要创建好 Bot，并通过 API 调用即可。

二、适合站长的使用场景

1. 网站智能客服

如果你的网站经常有访客咨询，例如产品价格、服务流程、售后政策、下载方法、会员规则等，可以把常见问题整理成知识库，让 Coze Bot 自动回答。

这样可以减少人工客服压力，也能提升用户响应速度。

2. 文章摘要与内容问答

对于内容型网站，可以让用户基于文章提问，例如：

• “这篇文章主要讲了什么？”
• “帮我总结为三点”
• “这篇教程适合新手吗？”
• “根据本文生成 SEO 描述”

这类功能非常适合博客、教程站、资讯站。

3. 站内搜索增强

传统站内搜索通常只能匹配关键词，而 AI 可以理解用户意图。

例如用户搜索：

我想找一个适合新手的网站备案教程

AI 可以帮助分析意图，然后返回更符合需求的内容。

4. 工具站功能增强

如果你运营的是工具类网站，可以接入 Coze API 实现：

• 文案生成；
• 标题生成；
• 正则表达式解释；
• 代码解释；
• 翻译润色；
• 表格内容分析；
• JSON 格式化说明；
• 邮件模板生成。

5. SEO辅助

站长还可以用 Coze API 自动生成：

• 文章标题；
• Meta Description；
• 文章摘要；
• FAQ 问答；
• 长尾关键词；
• 标签分类；
• 内容改写建议。

不过需要注意，AI 生成内容应经过人工审核，尤其是用于正式发布时。

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

在正式接入之前，你需要准备以下内容。

1. 注册并登录Coze平台

你需要先注册 Coze 账号。根据你的使用地区不同，可能会使用不同的 Coze 平台版本，例如国内版或海外版。

常见 API 域名可能包括：

https://api.coze.cn
https://api.coze.com

具体接口地址应以 Coze 官方文档为准。不同版本、不同地区的接口路径可能略有差异。

2. 创建Bot智能体

登录 Coze 后，进入 Bot 创建页面，配置你的智能体。

建议站长重点配置以下内容：

• Bot 名称；
• Bot 角色设定；
• 开场白；
• 回复风格；
• 知识库；
• 插件；
• 工作流；
• 用户问题处理规则。

例如你要做一个网站客服 Bot，可以设置提示词：

你是某某网站的智能客服，负责回答用户关于网站功能、会员服务、下载资源、售后政策等问题。
回答要简洁、准确、礼貌。如果用户问题超出网站业务范围，请提示用户联系人工客服。

3. 获取Bot ID

创建 Bot 后，通常可以在 Bot 详情页或发布配置中找到 Bot ID。

Bot ID 是调用 API 时非常重要的参数，用于告诉 Coze：你要调用哪一个智能体。

示例：

bot_id = 1234567890123456789

4. 获取API Token

API Token 用于接口鉴权。你可以在 Coze 开发者后台或个人设置中创建访问令牌。

Token 通常长这样：

pat_xxxxxxxxxxxxxxxxxxxxxxxxx

注意：API Token 一定不能直接写在前端页面里，否则任何人都可以在浏览器中看到并盗用你的接口额度。

正确做法是：

• 前端请求你自己的网站后端；
• 后端再调用 Coze API；
• Token 保存在服务器环境变量中。

四、Coze API基本调用流程

以常见的聊天接口为例，调用时一般需要以下信息：

一个典型请求流程如下：

1. 用户在网页输入问题
2. 前端把问题提交到网站后端
3. 后端携带 Token 请求 Coze API
4. Coze 返回回答结果
5. 后端把结果返回给前端
6. 前端展示回答内容

五、使用Curl测试Coze API

在正式写代码之前，建议先使用 Curl 测试接口是否可用。

下面示例仅供参考，具体接口路径和参数请以官方文档为准：

curl -X POST 'https://api.coze.cn/v3/chat' \
  -H 'Authorization: Bearer YOUR_COZE_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "bot_id": "YOUR_BOT_ID",
    "user_id": "site_user_001",
    "stream": false,
    "auto_save_history": true,
    "additional_messages": [
      {
        "role": "user",
        "content": "你好，请介绍一下这个网站的主要服务",
        "content_type": "text"
      }
    ]
  }'

如果接口调用成功，你通常会得到一段 JSON 响应。部分接口可能不会立即返回完整答案，而是返回一个会话 ID 或任务 ID，需要再调用查询接口获取结果。

例如：

curl -X GET 'https://api.coze.cn/v3/chat/retrieve?conversation_id=xxx&chat_id=xxx' \
  -H 'Authorization: Bearer YOUR_COZE_API_TOKEN'

不同接口版本的返回结构可能不同，站长在开发时要仔细阅读官方文档，重点关注：

• 请求地址；
• 请求方法；
• 鉴权方式；
• 参数格式；
• 返回字段；
• 错误码；
• 是否支持流式输出。

六、Node.js调用Coze API示例

如果你的网站后端使用 Node.js，可以使用 fetch 调用 Coze API。

1. 安装环境

Node.js 18 以上通常已经内置 fetch，如果版本较低，可以安装 node-fetch。

2. 示例代码

const COZE_API_TOKEN = process.env.COZE_API_TOKEN;
const COZE_BOT_ID = process.env.COZE_BOT_ID;

async function askCoze(question, userId = 'site_user_001') {
  const response = await fetch('https://api.coze.cn/v3/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${COZE_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      bot_id: COZE_BOT_ID,
      user_id: userId,
      stream: false,
      auto_save_history: true,
      additional_messages: [
        {
          role: 'user',
          content: question,
          content_type: 'text'
        }
      ]
    })
  });

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

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

// 测试
askCoze('请介绍一下本站的会员服务')
  .then(console.log)
  .catch(console.error);

3. Express接口封装

站长通常需要把 Coze 调用封装成自己网站的接口。

import express from 'express';

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

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

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

    const result = await askCoze(message, userId || 'guest_user');

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

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

前端只需要请求你自己的接口：

async function sendMessage(message) {
  const res = await fetch('/api/ai-chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message,
      userId: 'user_10001'
    })
  });

  return await res.json();
}

这样可以避免 Token 暴露在浏览器中。

七、PHP调用Coze API示例

很多站长使用的是 PHP 网站，例如 WordPress、Typecho、Discuz、帝国 CMS、织梦 CMS 或自己写的 PHP 程序。下面是一个 PHP 示例。

 $bot_id,
        'user_id' => $user_id,
        'stream' => false,
        'auto_save_history' => true,
        'additional_messages' => [
            [
                'role' => 'user',
                'content' => $question,
                'content_type' => 'text'
            ]
        ]
    ];

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $api_token,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        return [
            'success' => false,
            'error' => $error
        ];
    }

    curl_close($ch);

    return json_decode($response, true);
}

$result = ask_coze('请介绍一下本站提供哪些服务');
print_r($result);

如果你要在 WordPress 中使用，可以把这段逻辑封装成插件接口，或者写入主题的自定义接口中。不过不建议直接在模板文件中调用外部 API，因为页面加载会变慢。

更好的方式是：

用户提交问题
    ↓
Ajax 请求 WordPress 后端接口
    ↓
后端调用 Coze API
    ↓
返回结果给前端

八、Python调用Coze API示例

如果你的网站后端使用 Python，例如 Flask、FastAPI、Django，可以参考下面代码。

import os
import requests

COZE_API_TOKEN = os.getenv("COZE_API_TOKEN")
COZE_BOT_ID = os.getenv("COZE_BOT_ID")

def ask_coze(question, user_id="site_user_001"):
    url = "https://api.coze.cn/v3/chat"

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

    payload = {
        "bot_id": COZE_BOT_ID,
        "user_id": user_id,
        "stream": False,
        "auto_save_history": True,
        "additional_messages": [
            {
                "role": "user",
                "content": question,
                "content_type": "text"
            }
        ]
    }

    response = requests.post(url, headers=headers, json=payload, timeout=30)
    response.raise_for_status()

    return response.json()

if __name__ == "__main__":
    print(ask_coze("帮我总结本站的主要功能"))

九、前端聊天窗口设计建议

对于站长来说，API 接通只是第一步，真正影响用户体验的是前端交互。

一个简单的 AI 聊天窗口可以包含：

• 输入框；
• 发送按钮；
• 加载状态；
• 用户消息气泡；
• AI 回复气泡；
• 错误提示；
• 清空对话；
• 联系人工客服按钮。

简单 HTML 示例：

  


  

    
    发送
  

JavaScript 示例：

async function submitQuestion() {
  const input = document.getElementById('userInput');
  const message = input.value.trim();

  if (!message) return;

  appendMessage('user', message);
  input.value = '';

  appendMessage('bot', '正在思考中...');

  try {
    const res = await fetch('/api/ai-chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ message })
    });

    const data = await res.json();

    // 根据你的后端返回结构进行调整
    updateLastBotMessage(JSON.stringify(data));
  } catch (e) {
    updateLastBotMessage('请求失败，请稍后再试。');
  }
}

function appendMessage(role, content) {
  const box = document.getElementById('chatMessages');
  const div = document.createElement('div');
  div.className = role === 'user' ? 'msg user' : 'msg bot';
  div.innerText = content;
  box.appendChild(div);
}

function updateLastBotMessage(content) {
  const bots = document.querySelectorAll('.msg.bot');
  if (bots.length > 0) {
    bots[bots.length - 1].innerText = content;
  }
}

正式上线时，建议对 UI 做进一步优化，例如增加 Markdown 渲染、代码高亮、打字机效果、移动端适配等。

十、是否需要使用流式输出？

流式输出指的是 AI 一边生成内容，一边把内容逐步返回给前端。用户看到的效果类似 ChatGPT：文字逐字或逐段出现。

非流式输出优点

• 实现简单；
• 适合新手站长；
• 后端处理容易；
• 对服务器要求较低。

非流式输出缺点

• 用户需要等待完整结果生成；
• 如果回答较长，等待时间较明显。

流式输出优点

• 用户体验更好；
• 适合聊天机器人；
• 适合长文本生成场景。

流式输出缺点

• 开发复杂度更高；
• 需要处理 SSE 或流响应；
• 前端需要持续接收数据；
• 错误处理更复杂。

如果你是第一次接入 Coze API，建议先使用非流式模式，把整体流程跑通。等功能稳定后，再考虑使用流式输出。

十一、站长接入Coze API的安全注意事项

1. 不要把Token写在前端

这是最重要的一点。

错误示例：

const token = 'pat_xxxxxxxxx';

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

正确做法：

Token保存在服务器端
前端只请求自己的后端接口
后端再请求Coze API

2. 设置访问频率限制

如果你的网站开放 AI 聊天功能，一定要做频率限制。例如：

• 每个 IP 每分钟最多请求 10 次；
• 未登录用户每天最多请求 20 次；
• 登录用户按会员等级限制次数；
• 对异常请求自动封禁。

否则可能出现接口被刷、额度被消耗的问题。

3. 过滤用户输入

用户输入不能完全信任。建议做：

• 长度限制；
• 敏感词过滤；
• HTML 标签过滤；
• SQL 注入防护；
• 脚本代码转义。

尤其是你把 AI 回复展示到网页上时，不要直接渲染未经处理的 HTML，否则可能造成 XSS 风险。

4. 控制成本

AI API 调用通常和请求次数、Token 消耗等因素有关。站长上线前要做好成本评估：

• 是否所有用户都开放；
• 是否只对会员开放；
• 是否限制每日次数；
• 是否对长文本单独计费；
• 是否缓存常见问题答案；
• 是否记录调用日志。

5. 日志与隐私

如果用户可能输入手机号、邮箱、订单号等隐私信息，你需要在隐私政策中说明数据处理方式。

同时，后台日志中不要明文保存过多敏感信息，必要时进行脱敏处理。

十二、如何优化Coze Bot的回答质量？

API 接通后，如果回答质量不理想，通常不是代码问题，而是 Bot 配置问题。

你可以从以下几个方面优化。

1. 优化角色提示词

不要只写：

你是一个客服。

更好的写法是：

你是某某网站的智能客服，主要负责解答用户关于账号注册、会员购买、资源下载、发票申请、售后服务等问题。
你的回答应简洁、准确、友好。
如果用户问题不属于本站业务范围，请礼貌说明无法回答，并引导用户联系人工客服。

2. 建立知识库

如果你的网站有大量固定资料，例如：

• 产品介绍；
• 服务说明；
• 常见问题；
• 价格规则；
• 使用教程；
• 售后政策；
• 联系方式；

建议整理成知识库，让 Bot 基于知识库回答。这样比单纯依赖模型自由发挥更可靠。

3. 限制回答范围

站长做客服 Bot 时，不建议让 AI 无边界回答所有问题。可以明确要求：

只回答与本站业务相关的问题。
不要编造不存在的服务、价格、承诺或联系方式。
遇到不确定的问题，请提示用户联系人工客服。

4. 添加兜底话术

当用户问到无法回答的问题时，可以让 Bot 返回固定提示：

抱歉，我暂时无法确认这个问题。你可以联系人工客服，或查看本站帮助中心获取更准确的信息。

十三、常见错误与排查方法

1. 401 Unauthorized

通常是鉴权失败。

检查：

• Token 是否正确；
• 请求头是否包含 Authorization: Bearer xxx；
• Token 是否过期；
• 是否使用了错误的平台域名；
• 是否有接口权限。

2. 400 Bad Request

通常是请求参数错误。

检查：

• bot_id 是否正确；
• JSON 格式是否正确；
• additional_messages 是否符合要求；
• content_type 是否填写；
• 字段名称是否和文档一致。

3. 404 Not Found

可能是接口地址错误。

检查：

• 是否使用了正确 API 域名；
• 是否使用了正确版本路径；
• 国内版和海外版接口是否混用。

4. 响应很慢

可能原因：

• 用户问题过长；
• Bot 使用了复杂工作流；
• 知识库检索耗时；
• 网络连接不稳定；
• 没有使用流式输出。

优化方法：

• 缩短输入；
• 简化 Bot 工作流；
• 缓存常见问题；
• 使用异步请求；
• 使用流式响应。

5. 回答不准确

通常需要调整 Bot，而不是改接口代码。

检查：

• 提示词是否清晰；
• 知识库是否完整；
• 是否存在过期资料；
• 是否让模型自由发挥过多；
• 是否加入了禁止编造的规则。

十四、站长上线前检查清单

在正式把 Coze API 功能上线前，建议检查以下事项：

• [ ] Bot 已发布或具备 API 调用权限；
• [ ] Bot ID 正确；
• [ ] API Token 可用；
• [ ] Token 未暴露在前端；
• [ ] 后端接口已完成封装；
• [ ] 已设置请求频率限制；
• [ ] 已处理接口错误；
• [ ] 已设置超时时间；
• [ ] 已做好用户输入过滤；
• [ ] 已做好 AI 回复内容转义；
• [ ] 已测试移动端显示；
• [ ] 已准备人工客服兜底；
• [ ] 已评估调用成本；
• [ ] 已记录必要日志；
• [ ] 已更新隐私政策或用户协议。

十五、适合站长的最佳实践

1. 从小功能开始

不要一开始就做复杂 AI 系统。建议先做一个简单场景，例如：

• 首页 AI 客服；
• 文章页 AI 摘要；
• 帮助中心 AI 问答；
• 后台 SEO 描述生成。

跑通后再逐步扩展。

2. 优先接入后端

即使你的网站是静态站，也建议通过 Serverless Function、云函数或反向代理调用 Coze API，不要直接在浏览器中请求。

可选方案包括：

• Node.js 后端；
• PHP 后端；
• Python 后端；
• Cloudflare Workers；
• Vercel Functions；
• Netlify Functions；
• 宝塔面板部署接口服务。

3. 对常见问题做缓存

如果大量用户都问同样的问题，例如“如何注册账号”“如何下载资源”，可以缓存 AI 回复，减少 API 调用成本。

缓存方式包括：

• Redis；
• MySQL；
• 文件缓存；
• CDN 边缘缓存；
• WordPress Transient。

4. 给用户明确提示

AI 不是人工客服，建议在聊天窗口中标注：

AI回复仅供参考，重要问题请联系人工客服确认。

这样可以降低误解和纠纷风险。

结语

对于站长而言，Coze API 的价值在于：不用从零开发 AI 模型，也不用搭建复杂的智能体系统，就可以把 AI 问答、智能客服、内容生成、SEO 辅助等能力接入网站。

实际接入时，建议遵循以下路线：

创建Bot
    ↓
配置提示词和知识库
    ↓
获取Bot ID和API Token
    ↓
使用Curl测试接口
    ↓
后端封装API
    ↓
前端接入聊天窗口
    ↓
增加限流、安全和日志
    ↓
上线并持续优化

如果你是新手站长，建议先从非流式接口开始，完成一个简单的 AI 客服功能；如果你已经有一定开发经验，可以进一步尝试流式输出、知识库问答、工作流调用、用户画像结合等高级玩法。

只要设计合理，Coze API 可以成为网站的重要增强能力，让你的网站从“静态展示”升级为“智能交互”。