开发者指南：通过API将扣子AI能力接入自有应用程序

星野

发布时间：2026-09-20| 4人浏览过

原创

明明在扣子平台上调试好的 Bot 逻辑很顺畅，一到自己的代码里就报错“401 Unauthorized”或者返回空内容，这种挫败感很多刚接触 API 集成的朋友都经历过。其实问题往往不在复杂的算法，而在于鉴权步骤和参数传递的细节没对上。

最直接需要检查的是 Personal Access Token (PAT) 是否生成正确，以及请求头中是否包含了必要的认证信息。只要这两个基础环节打通，剩下的就是按照文档规范发送 JSON 数据而已。

获取并配置访问令牌

扣子平台采用标准的 Bearer Token 鉴权机制。你需要先登录扣子开发者后台，进入个人设置或 API 管理页面，创建一个新的 Personal Access Token。

注意，这个 Token 相当于你的密码，生成后请立即复制保存，因为关闭弹窗后通常无法再次查看明文。在代码中，建议将其放入环境变量，避免硬编码在源文件里泄露风险。

在扣子后台创建并复制 Personal Access Token

在扣子后台创建并复制 Personal Access Token

拿到 Token 后，它在每次 HTTP 请求中都要放在 Header 的 Authorization 字段里，格式固定为 Bearer <你的Token>。如果这里少写了 Bearer 前缀，或者多带了空格，服务器都会直接拒绝访问。

构造对话请求

调用扣子 Bot 的核心接口通常是 /v3/chat 或类似的对话端点。你需要准备三个关键参数：Bot ID、用户输入内容和会话 ID。

Bot ID 可以在扣子工作区的 Bot 详情页 URL 中找到，是一串唯一的标识符。会话 ID (Conversation ID) 用于维持上下文记忆，如果是单轮问答可以传空或每次生成新的 UUID；如果需要多轮连续对话，则必须复用同一个 Conversation ID。

下面是一个使用 Python requests 库发起非流式请求的基础示例：

import requests
import json

url = "https://api.coze.cn/v3/chat"
headers = {
    "Authorization": "Bearer your_personal_access_token",
    "Content-Type": "application/json"
}

payload = {
    "bot_id": "your_bot_id",
    "user_id": "123456",
    "stream": False,
    "additional_messages": [
        {
            "role": "user",
            "content": "你好，请介绍一下你自己",
            "content_type": "text"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

这段代码发送了一个简单的文本消息。注意 additional_messages 是一个数组，即使只有一条消息也要用列表包裹。如果返回结果中包含 data 字段且有具体的回复内容，说明连接已成功建立。

处理流式响应提升体验

在实际应用中，等待几秒后一次性吐出整段文字会让用户觉得卡顿。扣子 API 支持 Server-Sent Events (SSE) 流式输出，能让文字像打字机一样逐字显示。

要启用流式模式，只需将 payload 中的 stream 字段设为 True。此时，服务端会返回一个持续的数据流，每一行以 data: 开头。

流式模式下数据逐行返回的处理流程

流式模式下数据逐行返回的处理流程

处理流式数据需要逐行读取响应内容，并解析其中的 JSON 片段。以下是一个简化的处理逻辑：

import requests

url = "https://api.coze.cn/v3/chat"
headers = {
    "Authorization": "Bearer your_personal_access_token",
    "Content-Type": "application/json"
}

payload = {
    "bot_id": "your_bot_id",
    "user_id": "123456",
    "stream": True,
    "additional_messages": [
        {
            "role": "user",
            "content": "讲个笑话",
            "content_type": "text"
        }
    ]
}

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

for line in response.iter_lines():
    if line:
        decoded_line = line.decode('utf-8')
        if decoded_line.startswith('data:'):
            json_str = decoded_line[5:].strip()
            if json_str == '[DONE]':
                break
            try:
                chunk = json.loads(json_str)
                # 根据实际返回结构提取内容，通常在 content 或 message 字段
                if 'content' in chunk:
                    print(chunk['content'], end='', flush=True)
            except json.JSONDecodeError:
                continue

这段代码通过 iter_lines() 实时读取数据块。注意要过滤掉 [DONE] 结束标记，并妥善处理可能出现的 JSON 解析异常。这样前端就能接收到连续的文本片段，实现流畅的交互效果。