Coze API 调用详细步骤

Made In SQL

12701人浏览 · 2025-08-05 07:26:55

Made In SQL · 2025-08-05 07:26:55 发布

1. 准备工作

1.1 注册与登录

访问 Coze 官网 (扣子) 注册账号
使用手机号或邮箱完成注册并登录

1.2 创建智能体

登录后进入控制台，点击 "创建智能体"
配置智能体基本信息 (名称、描述、头像等)
根据需求添加功能模块 (如 NLP 对话、意图识别等)
完成训练和测试

1.3 发布为 API 服务

在智能体开发页面，点击 "发布" 按钮
在发布选项中勾选 "Bot As API"
确认发布设置，完成 API 服务发布

2. 获取认证凭证

2.1 生成个人访问令牌 (PAT)

进入 Coze 控制台，点击右上角头像→"开发者设置"
在 "API 令牌" 页面，点击 "创建令牌"
设置令牌名称和权限范围 (至少勾选 "chat" 权限)
保存生成的令牌 (仅显示一次，需妥善保管)

2.2 获取智能体 ID (bot_id)

进入智能体开发页面
从 URL 中提取 bot_id 参数值，格式如下：
plaintext
```
https://www.coze.cn/space/{space_id}/bot/{bot_id}
```
其中bot参数后的数字即为bot_id

2.3 确认权限

确保 PAT 令牌与智能体属于同一账号
验证令牌具有所需 API 权限

3. API 调用基础

3.1 基本请求结构

plaintext

POST /v3/chat HTTP/1.1
Host: api.coze.cn
Authorization: Bearer {your_pat_token}
Content-Type: application/json

{
  "bot_id": "{your_bot_id}",
  "user_id": "unique_user_identifier",
  "content": "Hello, Coze!"
}

3.2 核心 API 端点

端点	方法	描述
`/v3/chat`	POST	发起对话
`/v1/workflow/run`	POST	执行工作流
`/v1/files/upload`	POST	上传文件
`/v3/conversation/{conversation_id}/messages`	GET	获取会话历史

3.3 认证方式

Coze API 使用 Bearer Token 认证，在请求头中添加：

plaintext

Authorization: Bearer {your_pat_token}

4. 发起对话 API 详解

4.1 请求参数

参数	类型	必填	描述
`bot_id`	string	是	智能体 ID
`user_id`	string	是	用户唯一标识
`stream`	boolean	否	是否启用流式响应，默认 false
`conversation_id`	string	否	会话 ID，用于维持上下文
`auto_save_history`	boolean	否	是否自动保存对话历史，默认 true
`additional_messages`	array	否	历史消息列表
`custom_variables`	object	否	自定义变量，用于动态替换 prompt 中的变量

4.2 additional_messages 结构

json

[
  {
    "role": "user",
    "content": "早上好",
    "content_type": "text"
  },
  {
    "role": "assistant",
    "content": "早上好！有什么可以帮助您的吗？",
    "content_type": "text"
  }
]

4.3 响应格式

非流式响应：

json

{
  "code": 0,
  "msg": "Success",
  "data": {
    "conversation_id": "conv_123456",
    "bot_id": "73428668****",
    "user_id": "123",
    "messages": [
      {
        "id": "msg_789",
        "role": "assistant",
        "content": "您好！我是智能助手，有什么可以帮助您的吗？",
        "content_type": "text",
        "created_at": 1717777777
      }
    ],
    "usage": {
      "input_tokens": 20,
      "output_tokens": 30,
      "total_tokens": 50
    }
  }
}

5. 代码示例

5.1 cURL 命令示例

bash

curl --location --request POST 'https://api.coze.cn/v3/chat' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \
--data-raw '{
  "bot_id": "73428668*****",
  "user_id": "123123***",
  "stream": false,
  "auto_save_history": true,
  "additional_messages": [
    {
      "role": "user",
      "content": "早上好",
      "content_type": "text"
    }
  ]
}'

5.2 JavaScript 示例 (Fetch API)

javascript

async function sendMessageToCoze(message) {
  const apiKey = 'YOUR_PAT_TOKEN';
  const botId = 'YOUR_BOT_ID';
  const userId = 'USER_IDENTIFIER';
  
  try {
    const response = await fetch('https://api.coze.cn/v3/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        bot_id: botId,
        user_id: userId,
        stream: false,
        additional_messages: [
          {
            role: 'user',
            content: message,
            content_type: 'text'
          }
        ]
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data.data.messages[0].content;
  } catch (error) {
    console.error('Error:', error);
    return null;
  }
}

// 使用示例
sendMessageToCoze('你好，Coze！').then(reply => {
  console.log('智能体回复:', reply);
});

5.3 Python 示例 (requests)

python

import requests
import json

def send_coze_message(api_key, bot_id, user_id, message):
    url = "https://api.coze.cn/v3/chat"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "bot_id": bot_id,
        "user_id": user_id,
        "stream": False,
        "auto_save_history": True,
        "additional_messages": [
            {
                "role": "user",
                "content": message,
                "content_type": "text"
            }
        ]
    }
    
    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # 抛出HTTP错误
        data = response.json()
        return data["data"]["messages"][0]["content"]
    except requests.exceptions.RequestException as e:
        print(f"请求错误: {e}")
        return None

# 使用示例
api_key = "YOUR_PAT_TOKEN"
bot_id = "YOUR_BOT_ID"
user_id = "USER_IDENTIFIER"
message = "你好，Coze！"

reply = send_coze_message(api_key, bot_id, user_id, message)
print(f"智能体回复: {reply}")

5.4 SDK 使用示例

安装 SDK:

bash

npm install @coze/api
# 或
pnpm install @coze/api

使用示例:

javascript

import { CozeAPI, COZE_CN_BASE_URL, RoleType } from '@coze/api';

// 初始化客户端
const client = new CozeAPI({
  token: 'your_pat_token',
  baseURL: COZE_CN_BASE_URL, // 中国区使用此URL
});

// 发送消息
async function quickChat() {
  const response = await client.chat.createAndPoll({
    bot_id: 'your_bot_id',
    additional_messages: [
      {
        role: RoleType.User,
        content: 'Hello, Coze!',
        content_type: 'text',
      },
    ],
  });

  if (response.chat.status === 'completed') {
    for (const message of response.messages) {
      console.log(`[${message.role}]: ${message.content}`);
    }
    console.log('Token使用情况:', response.chat.usage);
  }
}

// 调用函数
quickChat();

6. 版本差异说明

6.1 v2 与 v3 版本主要差异

特性	v2 版本	v3 版本
API 端点	`/open_api/v2/chat`	`/v3/chat`
用户标识	`user`参数	`user_id`参数
消息参数	`query`(字符串)	`additional_messages`(数组)
流式响应	基础支持	增强支持，多事件类型
自定义变量	不支持	支持`custom_variables`参数
权限控制	基础权限	细粒度权限控制

6.2 v3 版本新增功能

支持多轮对话上下文管理
自定义变量替换
增强的错误处理机制
更详细的使用统计

7. 工作流 API 调用

7.1 执行工作流

python

import requests
import json

def run_workflow(api_key, workflow_id, parameters):
    url = "https://api.coze.cn/v1/workflow/run"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "workflow_id": workflow_id,
        "parameters": parameters,
        "is_async": False  # 同步执行
    }
    
    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"请求错误: {e}")
        return None

# 使用示例
parameters = {
    "input": "生成分布式系统的思维导图"
}
result = run_workflow(api_key, workflow_id, parameters)
print(result)

7.2 文件上传与处理

python

def upload_file(api_key, file_path):
    url = "https://api.coze.cn/v1/files/upload"
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    
    with open(file_path, "rb") as file:
        files = {"file": file}
        response = requests.post(url, headers=headers, files=files)
        
    if response.status_code == 200:
        return response.json()["data"]["id"]  # 返回file_id
    else:
        print(f"上传失败: {response.text}")
        return None

# 使用示例
file_id = upload_file(api_key, "test.jpg")
if file_id:
    # 将file_id用于工作流参数
    workflow_params = {
        "question": "请描述图中的内容",
        "image": json.dumps({"file_id": file_id})
    }
    # 调用工作流...

8. 限制与计费

8.1 限流策略

用户类型	API 流控 (QPS)	模型流控 (RPM)
个人免费版	20	300
个人进阶版	200	1000
团队版	500	5000
企业版	定制	12000

8.2 请求体大小限制

工作流相关 API: 20MB
其他 API: 15MB

8.3 计费说明

个人免费版：累计 100 次免费调用额度
付费版：根据输入输出 Token 数量计费
工作流执行、对话流等操作消耗资源点
具体费率参考 Coze 官方定价页面

9. 常见问题与错误处理

9.1 认证失败

错误表现: 401 Unauthorized
解决方法:
1. 检查 PAT 令牌是否正确
2. 确认令牌未过期
3. 验证令牌权限是否完整
4. 确保令牌与智能体属于同一账号

9.2 跨域问题 (CORS)

错误表现: 前端调用时出现 CORS 错误
解决方法:
1. 使用后端代理转发请求
2. 配置 CORS 允许的源域名
3. 使用 Coze SDK (已处理 CORS)

9.3 限流处理

错误表现: 429 Too Many Requests
解决方法:
1. 实现请求重试机制 (带退避策略)
2. 优化请求频率，避免高峰期集中调用
3. 根据业务需求升级账号类型

9.4 网络问题

解决方法:
1. 实现超时重试机制
2. 使用 API 代理服务提高稳定性
3. 监控网络状态，及时反馈给用户

10. 最佳实践

10.1 会话管理

为每个用户维护唯一user_id
使用conversation_id管理多轮对话
定期清理过期会话，节省资源

10.2 安全措施

不要在前端暴露 PAT 令牌
使用环境变量存储敏感信息
定期轮换 API 令牌
实施最小权限原则

10.3 性能优化

合理设置超时时间 (建议 10-30 秒)
对大型请求使用异步处理
利用流式响应提升用户体验
缓存常见请求结果

10.4 监控与日志

记录 API 调用日志
监控 Token 消耗情况
跟踪 API 响应时间
设置异常告警机制

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

上海AI实验室 Intern Lumina U2 上线 AtomGit AI，昇腾千卡训练提效 1.85 倍

AtomGit开源社区

本周 G-Star 开源项目推荐

AtomGit开源社区

逾百高校火热竞逐中国电信星辰杯算子开发挑战赛‌，赛事奖金追加热度持续攀升

AtomGit开源社区

所有评论(0)

查看更多评论

Made In SQL

@NIIT0532

已为社区贡献10条内容

Coze API 调用详细步骤

Made In SQL

1. 准备工作

1.1 注册与登录

1.2 创建智能体

1.3 发布为 API 服务

2. 获取认证凭证

2.1 生成个人访问令牌 (PAT)

2.2 获取智能体 ID (bot_id)

2.3 确认权限

3. API 调用基础

3.1 基本请求结构

3.2 核心 API 端点

3.3 认证方式

4. 发起对话 API 详解

4.1 请求参数

4.2 additional_messages 结构

4.3 响应格式

5. 代码示例

5.1 cURL 命令示例

5.2 JavaScript 示例 (Fetch API)

5.3 Python 示例 (requests)

5.4 SDK 使用示例

6. 版本差异说明

6.1 v2 与 v3 版本主要差异

6.2 v3 版本新增功能

7. 工作流 API 调用

7.1 执行工作流

7.2 文件上传与处理

8. 限制与计费

8.1 限流策略

8.2 请求体大小限制

8.3 计费说明

9. 常见问题与错误处理

9.1 认证失败

9.2 跨域问题 (CORS)

9.3 限流处理

9.4 网络问题

10. 最佳实践

10.1 会话管理

10.2 安全措施

10.3 性能优化

10.4 监控与日志

所有评论(0)

温馨提示：您尚未绑定手机号

Made In SQL