开篇介绍：

hello 大家，本篇博客比较轻松，我们学习一下coze的三种令牌以及API，相信我，真的很轻松。

Coze（扣子）作为字节跳动推出的低代码 AI 开发平台，不仅提供了拖拽式的可视化开发能力，更通过完善的 API 与令牌体系，让有编程基础的开发者能将 Coze 的 AI 能力无缝集成到自有系统、自动化脚本或企业级应用中。

一、Coze API 与 SDK：为什么它是 AI 应用开发的 “进阶钥匙”？

在讲解具体的技术细节前，我们先搞清楚一个核心问题：已经能用 Coze 的可视化界面开发 AI 应用了，为什么还要学 API？

1.1 Coze API 的核心价值：突破可视化的边界

Coze 的可视化开发（拖拽组件、配置工作流）解决了 “0 代码开发 AI 应用” 的问题，但在实际开发中，我们往往需要更灵活的自定义能力：

  • 系统集成：将 Coze 的 AI 能力（如翻译、智能问答）嵌入到你的自有系统（官网、小程序、ERP）中，而非仅使用 Coze 生成的独立应用链接；
  • 自动化流程：通过脚本批量创建智能体、执行工作流、导出对话记录，替代重复的手动操作；
  • 定制化交互：自定义前端界面的交互逻辑，比如用自己的 UI 框架实现对话界面，仅调用 Coze 的对话 API 处理核心逻辑；
  • 批量数据处理：通过 API 批量向 Coze 知识库导入数据、批量查询智能体配置，提升开发效率。

Coze API 本质上是一套 HTTP 接口规范，它将 Coze 平台的所有核心能力（工作空间管理、智能体开发、对话交互、工作流执行）封装成可调用的接口，让你能通过代码 “操控” Coze 的所有功能。

1.2 Coze SDK：让 API 调用更简单

为了降低开发者的调用成本，Coze 提供了 Python、JavaScript 等主流编程语言的 SDK（软件开发工具包）。SDK 是对原生 API 的封装，它帮你处理了请求头构造、参数序列化、响应解析、异常处理等底层细节，让你只需调用简单的函数就能完成 API 请求。

比如，原生 API 需要手动构造 HTTP 请求、处理 JSON 序列化，而 SDK 可能只需要一行代码：

# SDK调用示例（简化版）
from coze import CozeClient

client = CozeClient(access_token="你的令牌")
response = client.chat.create(bot_id="智能体ID", user_id="用户ID", query="你好")

本文会以原生 API为核心讲解（因为 SDK 本质是 API 的封装，理解原生 API 后能轻松掌握 SDK），同时提供 Python 语言的 API 调用示例（最易上手，适合新手）

1.3 Coze API 的整体架构：一切围绕 “鉴权” 展开

Coze 的所有 API 请求都遵循两个核心规则：

  1. 鉴权必选：所有请求必须在请求头中携带有效的访问令牌（Access Token），否则会直接返回 “鉴权失败”；
  2. 格式统一：请求参数以 JSON 格式传递，响应结果也为 JSON 格式，且包含固定的状态码字段（code=0代表成功）。

接下来，我们先攻克 Coze API 的 “第一道关卡”—— 令牌鉴权。

二、Coze 令牌体系：鉴权的核心基石

鉴权（身份验证与授权）是所有 API 的安全基础，Coze 通过三种不同类型的令牌实现精细化的权限控制。我们可以先记住一个核心结论：

令牌的本质是 “权限凭证”，不同令牌代表不同的 “身份” 和 “权限范围”，就像你进入不同场所需要的不同证件（临时通行证、长期工作证、授权委托书）。

2.1 令牌鉴权的本质：为什么需要它？

想象一个场景：如果 Coze API 不需要鉴权，任何人都能调用你的智能体、删除你的工作流、查看你的对话记录 —— 这显然是不可接受的。

令牌鉴权的作用有两个：

  1. 身份验证：确认调用 API 的 “是谁”（是某个用户、某个应用，还是某个第三方服务）；
  2. 权限控制：确认这个 “身份” 能做什么（比如只能查看智能体列表，还是能执行工作流）。

Coze 要求所有 API 请求的Authorization请求头中携带令牌，格式为：

Authorization: Bearer 你的令牌字符串

比如：

Authorization: Bearer pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB

2.2 三种令牌的深度解析：从 “校园外卖代拿” 理解本质

为了让新手能彻底理解三种令牌的区别，我们用 “校园外卖代拿” 的场景，再结合技术细节拆解。

2.2.1 个人访问令牌（PAT：Personal Access Token）

核心定位：代表 “用户个人” 的权限凭证，是新手最常用的令牌。

（1）通俗理解：你的 “学生证”

你（小明）不想每次都输入学号密码给 “小闪代拿”，于是学校给你生成了一个 “学生证令牌”—— 这个令牌能证明你是本校学生，“小闪代拿” 用这个令牌就能查到你的寝室号，但拿不到你的密码，也只能做你授权的事（比如查寝室号，不能查你的成绩单）。

（2）技术定义与特点
  • 身份代表：代表 Coze 平台的 “个人用户”，令牌的权限范围与生成令牌的用户权限一致；
  • 生命周期：短效令牌（可自定义过期时间，比如 1 天、7 天、30 天）；
  • 权限范围：可精细化配置（比如仅允许 “查看智能体”、“执行工作流”，不允许 “删除资源”）；
  • 创建方式：手动在 Coze 平台生成（地址：https://www.coze.cn/open/oauth/pats）；
  • 使用场景：个人开发、测试环境、临时脚本调用。
（3）PAT 的创建步骤（新手必看）
  1. 访问 PAT 生成页面：https://www.coze.cn/open/oauth/pats；
  2. 点击 “添加” 按钮，进入添加页面；
  3. 配置关键信息：
    • 令牌名称：自定义（比如 “测试用 PAT”）；
    • 过期时间：建议测试用选 7 天，避免长期令牌泄露；
    • 权限点：根据需求勾选（比如 “智能体读取”、“工作流执行”）；
    • 访问工作空间：选择需要授权的工作空间；
  4. 点击 “生成”，此时会显示唯一一次的令牌字符串（比如pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB），务必立即保存（关闭页面后无法再查看）
（4）使用注意事项
  • PAT 是 “个人权限的延伸”，泄露后他人可能以你的身份操作 Coze 资源，因此：
    • 不要在代码中硬编码 PAT（比如直接写在.py文件里），建议用环境变量；
    • 权限最小化：只勾选需要的权限（比如仅 “执行工作流”，不勾选 “删除工作流”）；
    • 定期轮换：比如每月重新生成一次，失效旧令牌。
2.2.2 服务访问令牌（SAT：Service Access Token）

核心定位：代表 “应用 / 服务” 本身的权限凭证，适合生产环境长期使用，使用了这个令牌，就能访问服务了

（1）通俗理解：“小闪代拿” 公司的 “工作证”

“小闪代拿” 公司和学校谈好了合作，学校给公司发了统一的 “工作证”—— 所有持这个证的小哥都能在指定时间进入宿舍楼，这个证代表的是 “公司”，而非某个员工，且长期有效。

（2）技术定义与特点
  • 身份代表：代表 “服务 / 应用程序”，而非个人用户；
  • 生命周期：长效令牌（可设置为永久有效）；
  • 权限范围：与服务的角色权限一致（需在企业版 / 团队版配置）；
  • 创建方式：仅 Coze 企业版 / 团队版支持，在 “服务管理” 中创建；
  • 使用场景：生产环境、企业级应用、长期运行的服务。
（3）SAT 与 PAT 的核心区别
维度个人访问令牌（PAT）服务访问令牌（SAT）
代表身份个人用户应用 / 服务
生命周期短效（最多 30 天）长效（可永久）
适用版本个人版 / 团队版 / 企业版仅团队版 / 企业版
使用场景个人开发 / 测试生产环境 / 企业应用
安全风险泄露影响个人权限泄露影响企业服务
2.2.3 OAuth 访问令牌（OAuth Access Token）

核心定位：代表 “用户授权第三方应用” 的临时凭证，安全性最高。

（1）通俗理解：你的 “一次性取餐码”

“小闪代拿” 需要帮你拿外卖，于是你授权它获取饿了么的 “一次性取餐码”—— 这个码只能用一次，只能拿这一单的外卖，过期自动失效，即使泄露也不会有大风险。

（2）技术定义与特点
  • 身份代表：代表 “第三方应用获得的用户授权”，而非用户本人；
  • 生命周期：超短效（通常几分钟到几小时）；
  • 权限范围：仅用户明确授权的范围（比如仅允许 “发起对话”，不允许查看智能体配置）；
  • 创建方式：通过 OAuth 2.0 协议自动生成（无需手动创建）；
  • 使用场景：线上生产环境、第三方应用集成、多用户场景。
（3）OAuth 令牌的核心优势

OAuth 的核心是 “授权不授密码”，比如你开发了一个面向普通用户的 AI 应用，用户无需告诉你他们的 Coze 账号密码，只需授权你的应用获取临时 OAuth 令牌，你的应用就能以用户的权限调用 Coze API，且令牌过期后自动失效，安全性远高于 PAT/SAT。

2.2.4 三种令牌的选型指南
令牌类型推荐使用场景不推荐场景核心优势
个人访问令牌个人开发、测试脚本、临时调试生产环境、多用户应用配置简单、新手友好
服务访问令牌企业内部服务、长期运行程序个人开发、测试环境长期有效、适配企业权限
OAuth 访问令牌线上生产环境、第三方应用集成个人开发、临时脚本安全性高、符合行业标准

2.3 令牌的安全最佳实践

无论使用哪种令牌，都必须遵守以下规则，否则可能导致资源泄露或被恶意操作：

  1. 绝不硬编码令牌：不要将令牌直接写在代码文件中（比如token = "pat_xxx"），建议用环境变量： 
    # 正确做法：从环境变量读取
import os
access_token = os.getenv("COZE_ACCESS_TOKEN")
  2. 权限最小化：只给令牌授予 “必须的权限”，比如仅需要执行工作流，就不要勾选 “删除工作流”；
  3. 定期轮换：即使是长效 SAT，也建议每 3-6 个月轮换一次；
  4. 及时失效：如果令牌泄露，立即在 Coze 平台将其标记为 “失效”，避免被恶意使用；
  5. 仅在 HTTPS 下传输：调用 API 时必须使用 HTTPS 协议，避免令牌在传输过程中被截获。

三、Coze API Playground：零代码调试 API 的利器

Coze API Playground 是字节跳动 Coze（扣子）平台官方的在线工具，说白了就是「Coze 各类 API 的试玩 / 调试工作台」，不用自己搭开发环境、不用写完整代码，点几下填点信息，就能直接测试、调用 Coze 的所有 API，核心是让你零成本、快速度地摸透 Coze API 怎么用，试成功了再用到自己的项目里，像个「API 的试衣间 + 调试器 + 代码生成器」

用大白话讲，它的核心用处就 5 个，全是帮你省时间、避坑的：

1. 「零配置试 API」，不用折腾开发环境

想调用 Coze 的 API（比如做智能聊天机器人、调用机器人的功能插件、管理 Coze 机器人等），正常需要写代码、配开发环境、处理网络请求，而在这个 Playground 里，你只需要填几个关键信息（比如自己的 Coze API 密钥、想发的请求内容），点「运行」，就能直接看到 API 的返回结果，哪怕是编程新手，也能马上试出效果。

2. 「快速排错」，API 调用出问题直接查

如果自己写代码调用 Coze API 时遇到报错（比如参数填错、权限不够、格式不对），不用在自己的项目里慢慢找 bug，直接把相同的参数放到 Playground 里运行，工具会清晰显示请求的完整内容、返回的错误码 / 错误信息，一眼就能看出问题在哪（比如少填了某个参数、API 密钥过期），比自己查代码高效多了。

3. 「生成现成代码」，试成功了直接抄走用

这是最实用的功能之一：你在 Playground 里调通某个 API 后（比如成功实现了和 Coze 机器人的对话），工具能直接生成不同编程语言的可直接运行的代码（比如 Python、Java、JavaScript、Go 等），你只需要把代码复制粘贴到自己的项目里，稍作修改就能用，不用自己手写 API 调用的代码，省超多时间。

4. 「直观熟悉 API」，比看文字文档更管用

Coze 有很多 API（对话 API、机器人管理 API、消息推送 API、功能插件调用 API 等），纯看官方文字文档会很抽象，而在 Playground 里，你可以挨个点进去试，搞清楚每个 API 需要什么参数、能实现什么功能、返回什么内容，相当于把「文字说明书」变成了「实操台」，上手快十倍。

5. 「验证需求可行性」，先试再做不白忙活

如果你想做一个基于 Coze 的项目（比如自己做个智能客服、聊天机器人、小程序内嵌 Coze 对话功能），可以先在 Playground 里测试核心 API，看能不能实现你想要的效果（比如让机器人精准回复特定问题、调用第三方插件查天气），确认可行了再正式开发，避免开发到一半发现 API 实现不了需求，白忙活一场。

最后一句话总结

Coze API Playground 就是字节给所有想对接 Coze 的人做的 **「懒人工具」**，主打「不用搭环境、不用写代码、试完抄代码」，不管是专业开发者还是编程新手，想对接 Coze API，先在这试一遍，准没错。

适用人群：想做 Coze 机器人、把 Coze 集成到自己的 APP / 小程序 / 网站、用 Coze API 做二次开发的所有人。

3.1 API Playground 的核心价值

  • 可视化调试：无需写代码，只需填写参数就能发起 API 请求，查看响应结果；
  • 实时文档：每个 API 的参数说明、枚举值、响应格式都能在页面上直接查看；
  • 示例代码生成：调试通过后，可直接复制 Python/JavaScript 等语言的调用代码；
  • 全覆盖接口：包含 Coze 所有 OpenAPI，从工作空间管理到对话交互都能调试。

3.2 API Playground 的使用步骤

  1. 访问地址：https://www.coze.cn/open/playground；
  2. 选择要调试的 API：比如左侧菜单 “对话”→“发起对话”；
  3. 配置请求参数：
    • 第一步：选择鉴权方式（比如 PAT），输入你的令牌；
    • 第二步：填写必选参数（比如bot_id、user_id）；
    • 第三步：填写可选参数（比如stream是否开启流式响应）；
  4. 点击 “发送请求”，页面会显示：
    • 请求信息：完整的 URL、请求头、请求体；
    • 响应信息：状态码、响应体、响应时间；
  5. 调试通过后，点击 “示例代码”，选择你熟悉的语言（比如 Python），即可复制可直接运行的代码。

3.3 新手调试小技巧

  • 先调试简单的 API（比如 “查看空间列表”），确认令牌有效后，再调试复杂 API（比如 “发起对话”）；
  • 遇到错误时，优先查看响应中的msg字段（比如 “token 无效”、“权限不足”），根据提示修正；
  • 保存调试通过的参数（比如workspace_id、bot_id），后续写代码时直接复用。

四、Coze 核心 API 全解析（实战为主）

在这一部分，我们会拆解 Coze 最常用的核心 API，每个 API 都包含 “接口说明、参数详解、代码示例、响应解析”，所有示例均使用 Python 的requests库

4.1 API 调用的通用规则（先记牢，避免重复踩坑）

4.1.1 通用请求头

所有 Coze API 请求都需要携带以下请求头：

请求头参数取值示例说明
AuthorizationBearer pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArv令牌鉴权，格式为 Bearer + 空格 + 令牌
Content-Typeapplication/json请求体为 JSON 格式
4.1.2 通用响应格式

所有 Coze API 的响应都是 JSON 格式，包含以下核心字段：

{
  "code": 0,          // 状态码：0=成功，非0=失败
  "data": {},         // 核心响应数据（不同API返回不同内容）
  "msg": "",          // 状态信息：失败时显示错误原因
  "detail": {
    "logid": ""       // 日志ID：排查问题时可提供给Coze客服
  }
}
4.1.3 如何获取关键 ID

很多 API 需要workspace_id（工作空间 ID）、bot_id（智能体 ID）、app_id（应用 ID），获取方式如下：

  • workspace_id：进入 Coze 工作空间，URL 中space=后的数字（比如https://www.coze.cn/space/7540958230303162414，则 ID 为 7540958230303162414）；
  • bot_id：进入智能体开发页面，URL 中bot=后的数字；
  • app_id：进入应用开发页面，URL 中app=后的数字；
  • conversation_id/chat_id：发起对话 API 的响应中会返回，用于后续查询对话详情。

4.2 工作空间相关 API：管理你的 Coze 资源归属

工作空间是 Coze 资源（智能体、应用、工作流）的容器，所有 API 操作都需要指定工作空间 ID。

4.2.1 查看空间列表

接口说明：查询当前令牌有权访问的所有工作空间，新手可先通过这个接口验证令牌是否有效。

（1）接口参数
维度参数名类型是否必选说明
请求方式-GET--
请求地址-https://api.coze.cn/v1/workspaces-
请求头AuthorizationString是Bearer + 令牌
请求头Content-TypeString是application/json
请求参数（Query）page_numInteger可选页码，默认 1
请求参数（Query）page_sizeInteger可选每页数量，默认 20，最大 50
（2）代码示例
import requests

# 1. 配置基础信息
access_token = "你的PAT令牌"
url = "https://api.coze.cn/v1/workspaces"

# 2. 构造请求头
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# 3. 构造请求参数（可选）
params = {
    "page_num": 1,
    "page_size": 10
}

# 4. 发送请求
response = requests.get(url, headers=headers, params=params)

# 5. 处理响应
if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        print("查询成功！")
        print(f"总工作空间数：{result['data']['total_count']}")
        # 遍历工作空间列表
        for workspace in result["data"]["workspaces"]:
            print(f"工作空间名称：{workspace['name']}")
            print(f"工作空间ID：{workspace['id']}")
            print(f"角色类型：{workspace['role_type']}（owner=所有者，member=成员）")
            print("-" * 50)
    else:
        print(f"查询失败：{result['msg']}")
else:
    print(f"请求失败，状态码：{response.status_code}")
（3）响应示例（关键字段解析）
{
  "code": 0,
  "data": {
    "total_count": 2,  // 总工作空间数
    "workspaces": [
      {
        "name": "我的第一个工作空间",  // 工作空间名称
        "id": "7540958230303162414", // 工作空间ID（重点保存）
        "role_type": "owner",        // 你的角色（所有者）
        "workspace_type": "team"     // 工作空间类型
      }
    ]
  },
  "msg": "",
  "detail": {
    "logid": "20250905094625889C23E948B98E62AF73"
  }
}
4.2.2 查看空间成员列表

接口说明：查询指定工作空间的所有成员，适用于企业 / 团队版管理。

（1）接口参数
维度参数名类型是否必选说明
请求方式-GET--
请求地址-https://api.coze.cn/v1/workspaces/:workspace_id/members-
路径参数workspace_idString是工作空间 ID
请求头AuthorizationString是Bearer + 令牌
请求参数（Query）page_numInteger可选页码，默认 1
（2）代码示例
import requests

access_token = "你的PAT令牌"
workspace_id = "7540958230303162414"  # 替换为你的工作空间ID
url = f"https://api.coze.cn/v1/workspaces/{workspace_id}/members"

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

params = {
    "page_num": 1,
    "page_size": 10
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        print(f"工作空间{workspace_id}的成员列表：")
        for member in result["data"]["items"]:
            print(f"用户昵称：{member['user_nickname']}")
            print(f"用户ID：{member['user_id']}")
            print(f"角色类型：{member['role_type']}")
            print("-" * 50)
    else:
        print(f"查询失败：{result['msg']}")

4.3 智能体与应用相关 API：管理你的 AI 应用

智能体是 Coze 的核心能力载体，应用是智能体的前端呈现形式，这部分 API 用于查询和管理智能体 / 应用的配置。

4.3.1 查看智能体列表

接口说明：查询指定工作空间下的所有智能体，可筛选发布状态。

（1）接口参数
维度参数名类型是否必选说明
请求方式-GET--
请求地址-https://api.coze.cn/v1/bots-
请求头AuthorizationString是Bearer + 令牌
请求参数（Query）workspace_idString是工作空间 ID
请求参数（Query）publish_statusString可选发布状态：published_online（已发布）、unpublished_draft（草稿）
（2）代码示例
4.3.2 查看智能体配置

接口说明：查询指定智能体的详细配置（包括提示词、模型信息、工作流关联等），是定制化开发的核心接口。

（1）代码示例
import requests

access_token = "你的PAT令牌"
bot_id = "7536152918114779162"  # 替换为你的智能体ID
url = f"https://api.coze.cn/v1/bots/{bot_id}"

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

params = {
    "is_published": True  # 查看已发布版本的配置
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        print("智能体详细配置：")
        print(f"名称：{result['data']['name']}")
        print(f"模型信息：{result['data']['model_info']['model_name']}")
        print(f"温度参数：{result['data']['model_info']['temperature']}")
        print(f"提示词：{result['data']['prompt_info']['prompt']}")
        # 查看关联的工作流
        if result['data']['workflow_info_list']:
            print("关联的工作流：")
            for workflow in result['data']['workflow_info_list']:
                print(f"- {workflow['name']}（ID：{workflow['id']}）")
    else:
        print(f"查询失败：{result['msg']}")

4.4 对话相关 API：Coze AI 能力的核心调用方式

对话 API 是最常用的 API，用于发起与智能体的对话、获取对话结果，支持同步 / 流式响应（流式响应更适合实时交互）。

4.4.1 发起对话（核心中的核心）

接口说明：向指定智能体发起对话请求，获取 AI 回复，支持同步和流式两种模式。

（1）关键参数详解（新手重点看）
参数名类型是否必选核心说明
bot_idString是智能体 ID
user_idString是自定义用户 ID（用于区分不同用户，比如 "user_001"）
streamBoolean可选是否流式响应：true = 流式，false = 同步（默认）
additional_messagesArray可选对话附加消息（包含历史消息和本次问题）
auto_save_historyBoolean可选是否保存对话记录（默认 true）
（2）同步响应示例（适合简单场景）
import requests
import json

access_token = "你的PAT令牌"
url = "https://api.coze.cn/v3/chat"

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

# 构造请求体
data = {
    "bot_id": "7536152918114779162",  # 智能体ID
    "user_id": "test_user_001",       # 自定义用户ID
    "stream": False,                  # 同步响应
    "additional_messages": [
        {
            "role": "user",           # 角色：user=用户，assistant=AI
            "content": "你好，请介绍一下Coze",  # 用户问题
            "content_type": "text"
        }
    ]
}

# 发送请求
response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        print("对话发起成功！")
        print(f"对话ID：{result['data']['id']}")
        print(f"会话ID：{result['data']['conversation_id']}")
        # 同步响应需要后续调用“查看对话消息”获取回复
        print("请使用conversation_id和chat_id查询对话结果")
    else:
        print(f"发起失败：{result['msg']}")
（3）流式响应示例（适合实时交互，比如聊天界面）

流式响应的特点是 “边生成边返回”，类似 ChatGPT 的打字机效果，适合前端实时展示：

import requests
import json

access_token = "你的PAT令牌"
url = "https://api.coze.cn/v3/chat"

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

data = {
    "bot_id": "7536152918114779162",
    "user_id": "test_user_001",
    "stream": True,  # 开启流式响应
    "additional_messages": [
        {
            "role": "user",
            "content": "用100字介绍Coze",
            "content_type": "text"
        }
    ]
}

# 发送流式请求
response = requests.post(url, headers=headers, json=data, stream=True)

if response.status_code == 200:
    print("流式响应开始：")
    # 逐行解析响应
    for line in response.iter_lines():
        if line:
            # 去除前缀"data: "（流式响应的标准格式）
            line = line.decode("utf-8").replace("data: ", "")
            if line == "[DONE]":  # 响应结束标志
                break
            # 解析JSON
            try:
                chunk = json.loads(line)
                # 提取AI回复内容
                if chunk.get("event") == "message":
                    content = chunk.get("data", {}).get("content", "")
                    print(content, end="")  # 不换行，模拟打字机效果
            except json.JSONDecodeError:
                continue
    print("\n\n流式响应结束！")
else:
    print(f"请求失败：{response.status_code}")
4.4.2 查看对话消息（获取 AI 回复结果）

发起同步对话后，需要调用此接口获取 AI 的具体回复内容：

import requests

access_token = "你的PAT令牌"
conversation_id = "7546176019566460978"  # 发起对话返回的会话ID
url = "https://api.coze.cn/v1/conversation/message/list"

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

params = {
    "conversation_id": conversation_id
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        # 遍历消息列表，找到AI的回复
        for message in result["data"]:
            if message["role"] == "assistant":  # assistant=AI回复
                print(f"AI回复：{message['content']}")
            elif message["role"] == "user":     # user=用户问题
                print(f"你的问题：{message['content']}")
    else:
        print(f"查询失败：{result['msg']}")

4.5 工作流相关 API：执行自定义业务逻辑

工作流是 Coze 实现复杂业务逻辑的核心，通过工作流 API 可批量执行自定义逻辑（比如翻译、数据处理）。

4.5.1 执行工作流

接口说明：直接执行已发布的工作流，支持同步 / 异步模式。

（1）代码示例（同步执行）
import requests
import json

access_token = "你的PAT令牌"
url = "https://api.coze.cn/v1/workflow/run"

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

# 构造请求体
data = {
    "workflow_id": "7534995507010682906",  # 工作流ID
    "parameters": json.dumps({
        "content": "你好，世界",            # 工作流输入参数
        "language": "英语"
    }),
    "is_async": False  # 同步执行
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    if result["code"] == 0:
        print("工作流执行成功！")
        print(f"执行结果：{result['data']}")
        print(f"调试链接：{result['debug_url']}")  # 可查看执行详情
    else:
        print(f"执行失败：{result['msg']}")

五、实战案例：构建自定义翻译助手 API

为了让你彻底掌握 Coze API 的使用，我们以 “翻译助手” 为例，构建一个可集成到自有系统的翻译 API。

5.1 案例背景

我们需要开发一个 Python 函数，接收 “原文” 和 “目标语言”，调用 Coze 的工作流 API 完成翻译，并返回结果 —— 这个函数可以嵌入到你的网站、小程序或自动化脚本中。

5.2 实现步骤

步骤 1：准备工作
  1. 生成 PAT 令牌（勾选 “工作流执行” 权限）；
  2. 获取工作流 ID：进入 Coze 工作流编辑页面，URL 中workflow=后的数字；
  3. 确认工作流的输入参数：比如content（原文）、language（目标语言）。
步骤 2：编写翻译函数
import requests
import json

def coze_translate(access_token, workflow_id, content, target_language):
    """
    调用Coze工作流实现翻译
    :param access_token: Coze的PAT令牌
    :param workflow_id: 翻译工作流ID
    :param content: 要翻译的原文
    :param target_language: 目标语言（如英语、日语、法语）
    :return: 翻译结果或错误信息
    """
    # 1. 配置接口信息
    url = "https://api.coze.cn/v1/workflow/run"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    # 2. 构造请求参数
    data = {
        "workflow_id": workflow_id,
        "parameters": json.dumps({
            "content": content,
            "language": target_language
        }),
        "is_async": False
    }

    # 3. 发送请求
    try:
        response = requests.post(url, headers=headers, json=data, timeout=30)
        response.raise_for_status()  # 抛出HTTP异常
        result = response.json()

        # 4. 处理响应
        if result["code"] == 0:
            # 解析工作流返回的结果（假设返回JSON格式{"output":"翻译结果"}）
            workflow_result = json.loads(result["data"])
            return {
                "success": True,
                "translation": workflow_result.get("output", "")
            }
        else:
            return {
                "success": False,
                "error": f"工作流执行失败：{result['msg']}"
            }
    except requests.exceptions.Timeout:
        return {"success": False, "error": "请求超时"}
    except requests.exceptions.RequestException as e:
        return {"success": False, "error": f"请求异常：{str(e)}"}
    except json.JSONDecodeError:
        return {"success": False, "error": "响应解析失败"}

# 步骤3：测试函数
if __name__ == "__main__":
    # 替换为你的实际信息
    ACCESS_TOKEN = "你的PAT令牌"
    WORKFLOW_ID = "7534995507010682906"
    
    # 测试翻译
    result = coze_translate(
        access_token=ACCESS_TOKEN,
        workflow_id=WORKFLOW_ID,
        content="你好，欢迎使用Coze翻译助手",
        target_language="英语"
    )

    if result["success"]:
        print(f"翻译结果：{result['translation']}")
    else:
        print(f"翻译失败：{result['error']}")
步骤 3：测试与验证

运行上述代码，若配置正确，会输出：

翻译结果：Hello, welcome to use Coze Translator

5.3 案例拓展

你可以将这个函数封装成 Web API（比如用 FastAPI/Flask），对外提供 HTTP 接口，实现跨系统调用：

from fastapi import FastAPI
import uvicorn

app = FastAPI(title="Coze翻译助手API")

# 注册接口
@app.post("/translate")
def translate(content: str, target_language: str):
    result = coze_translate(
        access_token=ACCESS_TOKEN,
        workflow_id=WORKFLOW_ID,
        content=content,
        target_language=target_language
    )
    return result

# 启动服务
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

启动后，你可以通过POST http://localhost:8000/translate调用翻译接口，实现自有系统的集成。

咳咳咳，python我们还没学，所以看起来就很复杂，不过不必担心各位，现在ai发展嘎嘎快，我们完全可以让ai帮助我们实现这一块内容，我们只需要告诉ai要怎么做。

六、常见问题与避坑指南

在使用 Coze API 的过程中，容易遇到以下问题，我们逐一给出解决方案：

6.1 令牌相关问题

问题 1：鉴权失败（code 非 0，msg 包含 “token 无效”）
  • 原因：令牌错误、令牌已失效、令牌权限不足；
  • 解决方案：
    1. 检查令牌是否填写正确（注意不要有空格）；
    2. 登录 Coze 平台查看令牌是否已失效；
    3. 确认令牌是否有对应的权限（比如执行工作流需要 “workflow:run” 权限）。
问题 2：令牌泄露
  • 解决方案：
    1. 立即在 Coze 平台将泄露的令牌标记为失效；
    2. 重新生成新令牌；
    3. 检查代码 / 配置文件，确保没有硬编码令牌。

6.2 API 调用相关问题

问题 1：参数错误（比如 workspace_id/bot_id 填写错误）
  • 原因：ID 填写错误、ID 对应的资源不存在；
  • 解决方案：
    1. 重新核对 ID（从 URL 中复制，不要手动输入）；
    2. 通过 “查看空间列表 / 智能体列表”API 确认 ID 是否有效。
问题 2：流式响应解析失败
  • 原因：未处理流式响应的前缀（data: ）、未处理[DONE]结束标志；
  • 解决方案：参考 4.4.1 的流式响应示例，逐行解析并去除前缀。
问题 3：响应状态码为 404/403
  • 404：接口地址错误（比如拼写错误）；
  • 403：令牌权限不足；
  • 解决方案：核对接口地址、检查令牌权限。

6.3 工作流执行相关问题

问题 1：工作流执行失败（msg 包含 “工作流未发布”）
  • 原因：调用的工作流未发布；
  • 解决方案：在 Coze 平台发布工作流后再调用。
问题 2：异步执行工作流后无法获取结果
  • 解决方案：异步执行会返回execute_id，通过 “查询工作流异步执行结果 API” 获取结果： 
    # 查询异步执行结果
def get_workflow_result(access_token, execute_id):
    url = f"https://api.coze.cn/v1/workflow/result?execute_id={execute_id}"
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(url, headers=headers)
    return response.json()

七、总结与展望

7.1 核心知识点回顾

  1. 令牌体系：PAT（个人、短效、新手首选）、SAT（服务、长效、企业用）、OAuth（授权、超短效、高安全），核心是 “权限最小化” 和 “安全存储”；
  2. API 调用规则：所有请求必须携带Authorization头，响应code=0代表成功，关键 ID（workspace_id/bot_id）需从 URL 中获取；
  3. 核心 API：对话 API（发起聊天）、工作流 API（执行自定义逻辑）是最常用的接口，流式响应适合实时交互；
  4. 实战关键：先通过 API Playground 调试，再写代码，优先使用 Python 的requests库，避免直接硬编码令牌。

7.2 Coze API 的应用场景拓展

掌握 Coze API 后，你可以实现更多复杂场景：

  • 自动化脚本：批量导入知识库数据、批量创建智能体、定时执行工作流；
  • 自有系统集成：将 Coze 的 AI 能力嵌入到官网、小程序、ERP、CRM 中；
  • 多平台联动：结合飞书 / 钉钉机器人、微信公众号，实现智能问答；
  • 批量数据处理：调用 Coze 的大模型能力批量处理文本（翻译、摘要、纠错）。

结语

写到这里，这篇 “轻松版” Coze API 与令牌指南也该收尾了。其实你会发现，看似涉及 “API”“令牌”“鉴权” 这些偏技术的词汇，但核心逻辑一点都不复杂 ——Coze 的整个 API 体系，本质上就是给你一把 “钥匙”，让你能跳出可视化界面的限制，把字节的 AI 能力变成自己的 “工具箱”，想怎么用就怎么用。

不用怕代码看起来复杂，就像我们提到的，哪怕你还没系统学过 Python，也可以把这些 API 调用的需求丢给 AI，让它帮你生成可用的代码，你只需要搞懂 “令牌该选哪种”“参数该填什么”“怎么验证调用成功” 这些核心问题就够了。毕竟技术的核心是解决问题，而不是死记硬背代码。

不妨从最简单的步骤开始：先去 Coze 平台生成一个 PAT 令牌，打开 API Playground 调试一次 “发起对话” 接口，看看你的智能体能不能通过 API 给出回复 —— 当你第一次看到请求成功的返回结果时，会发现这事儿真的就像我们开篇说的那样，轻松又有成就感。

Coze 作为字节的 AI 开发平台，正在把复杂的大模型能力拆成一个个简单的 API 和可视化组件，不管你是想做个自用的智能小工具，还是想把 AI 能力集成到自己的项目里，这套令牌和 API 体系都是你打通 “低代码可视化” 和 “自定义开发” 的桥梁。

最后想说：不用追求一次掌握所有细节，先动手试，遇到问题翻一翻这篇指南里的避坑点，慢慢你就会发现，原来把 AI 能力装进自己的系统里，真的没那么难。祝你玩得开心，也期待你用 Coze API 做出属于自己的 AI 小应用～

# 人工智能 # python
Logo
EazyDevelop社区

一站式 AI 云服务平台

更多推荐

24小时自助健身房系统软件开发实战指南：从零到部署完整流程

24小时自助健身房的核心在于“无人值守、智能计费、远程管控”。本文将从技术选型、数据库设计、核心模块开发到部署上线，完整拆解一套适配24小时自助健身房的系统开发流程。参考业内常见的共享空间管理系统（如无人台球室、无人洗车系统）技术模式，后台服务推荐使用Spring Boot + MyBatis Plus + MySQL，用户端采用UniApp（Vue语法）实现跨端（小程序 + App），管理后台使

avatar EazyDevelop社区
cover

零代码快速开发平台，AI 如何重塑应用搭建流程

avatar EazyDevelop社区
cover

零代码快速开发平台选型，AI 原生产品带来新体验

avatar EazyDevelop社区