Coze 的 API 与 SDK

API 参考

Coze 支持将 AI 智能体和扣子应用发布为 API（Application Programming Interface 应用程序编程接口）服务，我们可以通过 HTTP 方式与其进行交互。有编程基础的情况下，能够给用户更多的自定义开发空间。

也就是说：

Coze 支持将 AI 智能体和扣子应用发布为 API（Application Programming Interface，应用程序编程接口）服务，本质是把我们的智能体 / 应用封装成一个可通过网络调用的标准化接口。

我们可以使用任意编程语言（如 Python、Java、C/C++、JavaScript、Go、PHP 等），通过 HTTP 协议向 Coze 提供的指定接口路由发送请求：

  • 在请求报文头中设置必填的鉴权字段（如 Authorization: Bearer ${Access_Token}），完成身份验证；
  • 在请求体中传入智能体所需的参数（如用户提问、业务数据等）；
  • 发送请求后，即可获取智能体 / 应用处理完成的响应结果（通常为 JSON 格式）；
  • 拿到响应后，你可以根据自身业务需求完全自主地处理结果：比如提取回复内容展示在前端、存储到数据库、接入其他系统、或进行二次加工与逻辑判断。

简单来说，Coze 把 AI 能力变成了一个通用的后端接口，我们呢只需要像调用普通 API 一样发起 HTTP 请求，就能获取 AI 的输出，再自由整合到自己的产品或流程中。

令牌鉴权

扣子 API 通过访问令牌（Access Token）进行 API 请求的鉴权。所有的 API 请求都必须在请求头的Authorization参数中包含你的访问令牌（Access Token）。

令牌鉴权 = 在请求头里写：

Authorization: Bearer ${Access_Token}

有以下三种令牌：

鉴权方式 特点 说明
个人访问令牌 个人访问令牌是扣子平台提供的短效令牌，用于 API 请求鉴权。我们可以在扣子平台中生成个人访问令牌，并为其授予本人拥有的指定空间、指定操作的权限。 Personal Access Token，简称 PAT。扣子平台中生成的个人访问令牌。每个令牌可以关联多个空间，并开通指定的接口权限。生成方式可参考添加个人访问令牌。
服务访问令牌 服务访问令牌（Service Access Token，简称 SAT）是以服务身份创建的长效令牌，用于服务 / 应用程序的身份验证和授权。服务访问令牌的有效期可设置为永久。 Service Access Token（简称 SAT）是以服务身份创建的访问凭证，可长期有效访问扣子资源，通常用于服务 / 应用程序的身份验证和授权。
OAuth 访问令牌 OAuth 访问令牌（Access Token）是一串代表权限的字符串，它允许一个应用程序（客户端）在指定的时间内，以特定的权限范围访问用户在某一个服务（资源服务器）上的受保护资源，而无需使用用户的用户名和密码。 OAuth Access Token，通过 OAuth 2.0 鉴权方式生成的 OAuth 访问令牌。该鉴权方式通常应用于应用程序的身份验证和授权，和 PAT 鉴权方式相比，令牌有效期短，安全性更高，适用于线上生产环境。

场景理解：校园外卖代拿

故事背景：你是一名大学生，我们叫你 “小明”。你不想去食堂吃饭，用 “饿了么” App 点了一份外卖。但是学校规定，外卖小哥不能进宿舍楼，只能把外卖放到宿舍区大门口的 “外卖架” 上。问题来了：你正在王者峡谷激战，不想亲自下楼去拿。怎么办？这时，你发现有一个叫 “小闪代拿” 的校园服务，专门帮同学去外卖架取外卖并送到寝室。你需要使用这个服务。

接下来，三种令牌依次登场：

个人访问令牌 - 你的 “学生证”场景：“小闪代拿” 服务为了安全起见，需要验证你是本校学生。它让你输入学号和密码登录学校的 “学生信息服务平台” 来确认你的身份。你觉得每次都要输密码很麻烦，而且把密码直接给一个第三方服务也不安全。于是，学校的 “学生信息服务平台” 提供了一个功能：“生成访问令牌”。你登录平台后，生成了一个名为 “用于小闪代拿” 的令牌（一长串无规律的字符）。以后，“小闪代拿” 只需要出示这个令牌，平台就知道是 “小明” 授权的，可以获取你的基本信息（如姓名、楼栋、寝室号），而无需知道你的密码。

OAuth 访问令牌 - 你的 “一次性取餐码”场景：现在 “小闪代拿” 知道你是小明，住在 3 号楼 501 了。但它要去帮你拿外卖，还需要向 “外卖架” 证明：“我是小明授权来取他的外卖的”。外卖平台也有一个系统，每个订单都会生成一个取餐码（比如：8A3B）。这个码是动态的、一次性的（或短期有效）。于是，流程是这样的：

  1. “小闪代拿” 对你说：“请授权我去‘饿了么’拿你的外卖。”
  2. 你（小明）被引导到 “饿了么” 的授权页面，上面写着：“‘小闪代拿’申请获取你当前订单的外卖权限”。你点击 “同意”。
  3. “饿了么” 不给你密码，而是生成一个一次性的取餐码8A3B，交给 “小闪代拿”。
  4. “小闪代拿” 拿着这个码8A3B去外卖架，工作人员扫这个码，确认无误，就把标有8A3B的外卖交给了小闪。

服务访问令牌 - “小闪代拿” 公司的 “工作证”场景：“小闪代拿” 小哥拿到了外卖，现在要进入你的宿舍楼。宿舍楼阿姨可不会认 “饿了么” 的取餐码。“小闪代拿” 公司已经和学校后勤部门谈好了合作。后勤部门给 “小闪代拿” 公司发放了统一的工作证，所有持此证的工作人员都可以在特定时间（如 11:00-13:00）内出入宿舍楼。小哥向楼管阿姨出示这个公司工作证，阿姨验证后放行，最终把外卖送到了你手里。

总结

令牌类型 代表谁？ 授予谁的权限？ 生命周期
个人访问令牌（PAT） 代表你（用户） 一个应用代表你访问另一个服务 长期
OAuth 访问令牌 代表用户的授权 一个应用代表用户访问用户在其他服务的资源 短期
服务访问令牌（SAT） 代表应用本身 一个应用以自身身份访问另一个服务 长期

我们重点学习个人访问令牌（PAT）：创建个人访问令牌的时候，先访问网址：https://www.coze.cn/open/oauth/pats

点击「添加」按钮之后会出现添加个人访问令牌的页面。在添加个人访问令牌页面，可以指定令牌的名称、过期时间、分配权限点和访问工作空间。

等生成了令牌之后，需要把令牌保存下来，因为只显示一次。

API Playground

API Playground 是扣子提供的在线 API 调试工具，集成了扣子所有 OpenAPI，支持可视化调试 API、查看帮助文档、示例代码，帮助开发者快速体验扣子 OpenAPI 的基本能力。

扣子 API Playground 主要提供以下功能：

  • 可视化调试 API：支持在线可视化调试 API。只需根据页面提示填入必选参数，即可快速构建一个有效的 API 请求。API Playground 可以在线运行这个请求，并展示 API 的响应信息。
  • API 文档及说明：便于开发者理解 API 结构和查看 API 文档，文档中可视化展示 API 接口说明。
  • 示例代码：扣子支持 Python、JavaScript 等多种开发语言的 SDK，可简单便捷地调用扣子 API。

API Playground 网址：https://www.coze.cn/open/playground

核心 API

扣子接口文档：https://www.coze.cn/open/docs/developer_guides/coze_api_overview

工作空间

查看空间列表

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/workspaces

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
page_num Integer 可选 分页查询时的页码。默认为 1，即返回第一页数据。
page_size Integer 可选 分页大小，即每页返回多少个工作空间。默认为 20，最大为 50。
enterprise_id String 可选 企业 ID，企业 ID 的获取方法如下：切换到企业中，并在左侧导航栏中单击企业管理，URL 中enterprise参数后的数字就是enterprise_id。
user_id String 可选 扣子用户 ID，用于查询特定用户的工作空间信息。你可以单击扣子左下角的头像，选择账号设置，在页面底部查看扣子用户的 UID。
coze_account_id String 可选 扣子的组织 ID，用于查询特定组织的工作空间信息。・扣子个人版中，coze_account_id 即为 user_id。・扣子团队版和企业版中，coze_account_id 为组织 ID。超级管理员或管理员可以在企业设置或团队设置页面查看对应的组织 ID。

返回参数：

{
  "code": 0,                     // 响应状态码，0表示接口调用成功
  "data": {
    "total_count": 1,            // 工作空间总数量
    "workspaces": [              // 工作空间列表数组
      {
        "name": "个人空间",       // 工作空间名称
        "icon_url": "https://lf6-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_SPACE/personal.png?x-expires=1774003974&x-signature=OG2E%2F8HBqFZCt4v%2BtbLuJg4gtJg%3D",  // 工作空间图标地址
        "role_type": "owner",     // 当前用户在空间中的角色：owner=所有者
        "workspace_type": "personal",  // 空间类型：personal=个人空间
        "enterprise_id": "",      // 企业ID，个人空间为空
        "joined_status": "joined",      // 加入状态：joined=已加入
        "id": "7600239553282048042",   // 工作空间唯一标识ID（space_id）
        "owner_uid": "731620151670025", // 空间所有者用户ID
        "admin_uids": [],        // 空间管理员UID列表，空数组表示无管理员
        "description": "Personal Space" // 空间描述信息
      }
    ]
  },
  "msg": "",                     // 响应提示信息，成功时为空
  "detail": {
    "logid": "20260319185254968320161190521013C4"  // 请求日志ID，用于问题排查
  }
}

查看空间成员列表

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/workspaces/:workspace_id/members

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

Path 参数：

参数 类型 是否必选 说明
workspace_id String 必选 需要查看成员列表的空间 ID。进入指定空间，空间页面 URL 中space参数后的数字就是 Space ID。

请求参数：

参数 类型 是否必选 说明
page_num Integer 可选 分页查询时的页码。默认为 1，即返回第一页数据。
page_size Integer 可选 分页大小，即每页返回多少个工作空间。默认为 20，最大为 50。

返回参数：

{
  "msg": "",                                         // 响应提示信息，成功时为空
  "detail": {                                        // 响应详情信息
    "logid": "20260319191510EE8BCFFE733BC11B54D0"    // 请求日志ID，用于问题排查
  },
  "code": 0,                                         // 响应状态码，0表示接口调用成功
  "data": {                                          // 响应核心数据
    "total_count": 1,                                // 空间成员总数量
    "items": [                                       // 成员列表数组
      {
        "user_nickname": "RootUser_2119624379",      // 用户昵称
        "user_unique_name": "user3698275107",        // 用户唯一名称
        "avatar_url": "https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/coze_login/coze_default_profile_image.jpg",  // 用户头像地址
        "role_type": "owner",                        // 用户角色：owner=所有者
        "user_id": "731620151670025"                 // 用户唯一标识UID
      }
    ]
  }
}
智能体与应用

查看智能体列表

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/bots

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
workspace_id String 必选 智能体所在的工作空间的 Space ID。进入指定工作空间，空间页面 URL 中space参数后的数字就是 Space ID。
publish_status String 可选 智能体的发布状态，用于筛选不同发布状态的智能体。可选值如下：• all: 所有状态。• published_online:（默认值）已发布的正式版。• published_draft: 已发布但当前为草稿状态。• unpublished: 从未发布。
connector_id String 可选 渠道 ID，仅在智能体发布状态为published_online或published_draft时需要设置。用于筛选已上线或已发布草稿版本的智能体。版本 ID 和渠道 ID 可在 API 发布渠道下的「版本信息」中获取，默认版本为 1024，即获取调用 API 发布渠道下的最新版本。
page_num Integer 可选 分页查询时的页码。默认为 1，即从第一页数据开始返回。
page_size Integer 可选 分页大小。默认为 20，即每页返回 20 条数据。

返回参数：

{
  "code": 0,                                         // 响应状态码，0表示接口调用成功
  "data": {                                         // 响应核心数据体
    "items": [                                      // 智能体列表数组
      {
        "name": "旅途灵感家",                        // 智能体名称
        "description": "旅途灵感家是一个能根据你的需求生成个性化旅游攻略的智能体。它会推荐必去景点、特色美食，规划合理行程，还能提供当地文化与实用贴士，让你的旅行更精彩。",  // 智能体描述
        "is_published": true,                        // 是否已发布：true=已发布
        "updated_at": 1773657333,                    // 最后更新时间戳
        "owner_user_id": "731620151670025",          // 智能体所有者用户ID
        "id": "7600252439128358952",                 // 智能体唯一标识ID（bot_id）
        "published_at": 1773657333,                  // 发布时间戳
        "icon_url": "https://lf9-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/default_bot_icon1.png?lk3s=ca44e09c&x-expires=1774179660&x-signature=EJWQ2zs6g9Vd3XCskPux4FGPoR0%3D"  // 智能体头像地址
      }
    ],
    "total": 1                                       // 智能体总数量
  },
  "msg": "",                                         // 响应提示信息，成功时为空
  "detail": {                                        // 响应详情
    "logid": "20260319194100D2354998856515A3668F"    // 请求日志ID，用于问题排查
  }
}

查看应用列表

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/apps

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
workspace_id String 必选 扣子应用所在的工作空间的 Space ID。Space ID 是工作空间的唯一标识，在空间页面 URL 中space参数后的数字就是 Space ID。
publish_status String 可选 扣子应用的发布状态，用于筛选不同发布状态的应用。可选值如下：• all: 所有状态。• published_online:（默认值）已发布的正式版。• published_draft: 已发布但当前为草稿状态。• unpublished: 从未发布。
connector_id String 可选 渠道 ID，仅在应用发布状态为published_online或published_draft时需要设置。用于筛选已上线或已发布草稿版本的应用，包括已发布的线上正式版和已发布的草稿版本。默认版本为 1024，即获取调用 API 发布渠道下的最新版本。
page_num Integer 可选 分页查询时的页码。默认为 1，即从第一页数据开始返回。
page_size Integer 可选 分页大小。默认为 20，即每页返回 20 条数据。

返回参数：

{
  "code": 0,                                         // 响应状态码，0表示接口调用成功
  "data": {                                         // 响应核心数据体
    "total": 1,                                     // 应用/智能体总数量
    "items": [                                      // 应用/智能体列表数组
      {
        "id": "7618492240675323955",                 // 应用/智能体唯一标识ID
        "owner_user_id": "731620151670025",          // 所有者用户ID
        "is_published": true,                        // 是否已发布：true=已发布
        "updated_at": 1773910922,                    // 最后更新时间戳
        "published_at": 1773910922,                  // 发布时间戳
        "name": "玫瑰翻译",                          // 应用/智能体名称
        "description": "根据要翻译的语言目标，输出想要翻译的结果",  // 应用/智能体描述
        "icon_url": "https://lf9-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/731620151670025_1773823392664318828.jpeg?lk3s=ca44e09c&x-expires=1774179693&x-signature=UZsg6iKl7DMjh%2F%2BRFBfLN9va01A%3D"  // 应用/智能体头像地址
      }
    ]
  },
  "msg": "",                                         // 响应提示信息，成功时为空
  "detail": {                                        // 响应详情
    "logid": "202603191941339D64E13FCA6B26058B77"    // 请求日志ID，用于问题排查
  }
}

查看智能体配置

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/bots/:bot_id

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

Path 参数：

参数 类型 是否必选 说明
bot_id String 必选 要查看的智能体 ID，开发页面 URL 中bot参数后的数字就是 bot_id。

请求参数：

参数 类型 是否必选 说明
publish Boolean 可选 拟查看的发布状态对应版本。默认值为true。• true: 查看已发布版本的配置。• false: 查看当前草稿版本的配置。

返回参数：

{
  "msg": "",                                         // 响应提示信息，成功时为空
  "code": 0,                                         // 响应状态码，0表示接口调用成功
  "data": {                                         // 响应核心数据
    "owner_user_id": "247833709252424",              // 智能体所有者用户ID
    "name": "动物世界",                              // 智能体名称
    "description": "用户可以用一句自然语言描述，生成精彩动物视频。智能解析用户输入，快速制作丰富多样的动物内容，带您畅游神奇的“动物世界”。",  // 智能体描述
    "icon_url": "https://lf733-apstore-sign.oceancloudapi.com/ocean-cloud-tos/...",  // 智能体图标地址
    "publish_info": {                                // 发布配置信息
      "created_at": 1754814,                         // 创建时间戳
      "created_time": 1754814,                       // 创建时间戳（同created_at）
      "bot_mode": "after",                           // 智能体运行模式
      "back_role": {                                 // 角色设定信息
        "prompt": "你好！我热衷于创造精彩的视频世界，能为你带来独特体验。",  // 系统提示词
        "prologue": "你好！我热衷于创造精彩的视频世界，能为你带来独特体验。"  // 开场白
      },
      "workflow_info_list": [                        // 关联工作流列表
        {
          "icon_url": "https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/coze_login/coze_default_profile_image.jpg",  // 工作流图标地址
          "name": "动物世界",                         // 工作流名称
          "workflow_id": "l_26-apstore-sign.oceancloudapi.com/ocean-cloud-tos/...",  // 工作流ID
          "prompt_mode": "standard",                 // 提示词模式
          "use_vision_config": false,                // 是否使用视觉配置
          "vision_config": {}                        // 视觉配置内容
        },
        {
          "name": "视频助手",                        // 工作流名称
          "workflow_id": "l_26-apstore-sign.oceancloudapi.com/ocean-cloud-tos/...",  // 工作流ID
          "prompt_mode": "standard",                 // 提示词模式
          "use_vision_config": false,                // 是否使用视觉配置
          "vision_config": {}                        // 视觉配置内容
        }
      ],
      "max_tokens": 4096,                            // 最大token限制
      "theme_color": "#000000",                      // 主题颜色
      "parameter": {                                 // 模型调用参数
        "temperature": 0.3,                          // 温度系数，控制输出随机性
        "top_p": 0.8                                 // 核采样参数，控制输出多样性
      }
    }
  },
  "detail": {                                        // 响应详情
    "logid": "20250905069500A7D64E38FB3275626C"       // 请求日志ID，用于问题排查
  }
}
对话

发起对话

  • 请求方式：POST
  • 请求地址：https://api.coze.cn/v3/chat

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

Query

参数 类型 是否必选 说明
conversation_id String 可选 标识对话发生在哪一次会话中。会话是智能体和用户之间的一段问答交互。一个会话包含一或多条消息和消息。对话是一段问答对智能体的一次调用，智能体会将对话中产生的消息添加到会话中。

Body

参数 类型 是否必选 说明
bot_id String 必选 要进行会话聊天的智能体 ID。进入智能体的开发页面，开发页面 URL 中bot参数后的数字就是智能体 ID。
user_id String 必选 标识当前与智能体对话的用户，由使用方自行定义、生成与维护。user_id用于标识对话中的不同用户，不同的user_id，其对话的上下文消息、数据、等对话记忆数据互相隔离。
additional_messages Array of object 可选 对话的附加信息。你可以通过此字段传入历史消息和本次对话中用户的问题。数组长度限制为 100，即最多传入 100 条消息。・若未设置additional_messages，智能体收到的消息只有会话中已有的消息内容，其中最后一条作为本次对话的用户输入，其他内容均为本次对话的上下文。・若设置了additional_messages，智能体收到的消息包括会话中已有的消息和additional_messages消息，其中additional_messages最后一条消息会作为本次对话的用户输入，其他内容均为本次对话的上下文。
stream Boolean 可选 是否启用流式返回。• true: 采用流式响应。“流式响应” 将模型的实时响应提供给客户端，类似打字机效果。你可以实时获取服务端返回的对话、消息事件，并在客户端中同步处理、实时展示，也可以直接在completed事件中获取智能体最终的、完整的回复。• false:（默认）采用非流式响应。“非流式响应” 是指响应中仅包含本次对话的状态等元数据。此时应同时开启auto_save_history，在本次对话处理结束后查看模型回复等完整内容。
custom_variables Map<String , String> 可选 智能体提示词中定义的变量。在智能体prompt中设置变量{{key}}后，可以通过该参数传入变量值，同时支持 Jinja2 语法。
auto_save_history Boolean 可选 是否保存本次对话记录。• true:（默认）会话中保存本次对话记录，包括additional_messages中指定的所有消息、本次对话的模型回复结果、会话中不存在的上下文。• false: 会话中不保存本次对话记录，后续也无法通过任何方式查看本次对话信息、消息详情。在同一个会话中再次发起对话时，本次会话不会作为上下文传递给模型。
meta_data Map 可选 附加信息，通常用于封装一些业务相关的字段。查看对话详情时，扣子会透传此附加信息，查看消息列表时不会返回该附加信息。
extra_parameters Map<String , String> 可选 附加参数，通常用于特殊场景下指定一些必要参数供模型判断，例如指定经纬度，并询问智能体此位置的天气。该参数不会传给工作流。
shortcut_command Object 可选 快捷指令信息。你可以通过此参数指定此次对话执行的快捷指令，必须是智能体已绑定的快捷指令。
parameters Map<String, Any> 可选 给自定义参数赋值并传给对话流。你可以根据实际业务需求，在对话流开始节点的parameters参数中设置自定义参数，调用本接口发起对话时，可以通过parameters参数传入自定义参数的值并传给对话流。
enable_card Boolean 可选 设置问答节点返回的内容是否为卡片形式。默认为false。
publish_status String 可选 智能体的发布状态，用于指定与已发布版本或草稿版本的智能体对话。• published_online: 与已发布的线上版本的智能体对话。• unpublished_draft: 与草稿版本的智能体对话。
bot_version String 可选 指定智能体的版本号，用于与历史版本的智能体进行对话。默认与最新版本的智能体对话。

返回参数：

参数 类型 说明
data Object 本次对话的基本信息。详细说明可参考 Chat Object。
code Integer 状态码。0 代表调用成功。
msg String 状态信息。API 调用失败时可通过此字段查看详细错误信息。 
{
  "data": {
    "id": "7546176019566510130",
    "conversation_id": "7546176019566460978",
    "bot_id": "7533068816994074659",
    "created_at": 17568981022,
    "last_error": {
      "code": 0,
      "msg": ""
    }
  },
  "status": "in_progress",
  "code": 0,
  "msg": ""
}

查看对话详情

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v3/chat/retrieve

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
conversation_id String 必选 Conversation ID，即会话的唯一标识。可以在发起对话接口 Response 中查看conversation_id字段。
chat_id String 必选 Chat ID，即对话的唯一标识。可以在发起对话接口 Response 中查看chat_id字段，如果是流式响应，则在chat事件中，id字段即为chat_id。

返回参数：

{
  "code": 0,
  "data": {
    "id": "7533068816994074659",
    "conversation_id": "1756898103",
    "created_at": 1756898103,
    "status": "completed",
    "usage": {
      "input_count": 4210,
      "input_tokens": {
        "cached_tokens": 0,
        "output_tokens": 251s
      },
      "output_tokens": {
        "reasoning_tokens": 194
      },
      "token_count": 4470
    },
    "detail": {
      "logid": "20250904181959F742487ECF64A335D7F"
    }
  },
  "msg": ""
}

查看对话消息

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/conversation/message/list

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
conversation_id String 必选 Conversation ID，即会话的唯一标识。

返回参数：

{
  "code": 0,
  "data": [
    {
      "bot_id": "7533068816994074659",
      "chat_id": "7546176019566510130",
      "content": "请问 C/C++ 研发方向、Java 研发方向、JVM 研发方向和测试开发方向的就业毕业率为 90.15%。",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 175697107982,
      "meta_data": {
        "reasoning_content": "我现在需要查看你提供的数据内容，找到相关的就业信息。\n\n首先，你的问题是关于就业率的，所以我需要提取这部分数据。同时，根据用户的要求，图片标签需要展示，但是问题是关于 C++ 的，所以我需要提取 C++ 研发方向的就业毕业率。\n\n从用户的问题中，我看到 C/C++ 研发方向、Java 研发方向、JVM 研发方向和测试开发方向的就业毕业率为 90.15%（含 C/C++ 研发方向、Java 研发方向、JVM 研发方向和测试开发方向）。\n\n用户的问题是关于就业率的，所以我需要提取这部分数据，同时，用户的要求是，如果图片标签需要展示，应该包含在回答中。\n\n所以，我的回答应该包括 C/C++ 研发方向的就业毕业率，而要确保数据准确无误，直接引用数据集中的内容。\n\n回答应该包括：C/C++ 研发方向的就业毕业率为 90.15%。",
        "role": "assistant"
      },
      "role": "assistant",
      "section_user": "7546176019566460978",
      "type": "answer",
      "updated_at": 1756981029
    },
    {
      "bot_id": "",
      "chat_id": "7546176019566510130",
      "content": "请问 C/C++ 研发方向的就业毕业率怎么样？",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 175697107982,
      "meta_data": {},
      "reasoning_content": "",
      "role": "user",
      "section_user": "7546176019566460978",
      "type": "question"
    }
  ],
  "detail": {
    "logid": "202509041825251361396636235FF4E971"
  },
  "first_id": "f45e61f603157767982",
  "last_id": "7546176019566493746",
  "msg": ""
}

查看消息详情

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v3/chat/message/list

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
conversation_id String 必选 Conversation ID，即会话的唯一标识。可以在发起对话接口 Response 中查看conversation_id字段。
chat_id String 必选 Chat ID，即对话的唯一标识。可以在发起对话接口 Response 中查看chat_id字段，如果是流式响应，则在chat事件中，id字段即为chat_id。
conversation_id String 可选 Conversation ID，即会话的唯一标识。
page_num Integer 可选 分页查询时的页码。默认为 1，即从第一页数据开始返回。
page_size Integer 可选 分页大小。默认为 20，即每页返回 20 条数据。

返回参数：

{
  "code": 0,
  "data": [
    {
      "chat_id": "7533068816994074659",
      "content": "{\"lm\":{\"type\":\"text\",\"content\":\"I'm a student majoring in computer science.\"}}",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 1754289894,
      "role": "assistant",
      "type": "verbose",
      "updated_at": 1754289894
    },
    {
      "bot_id": "7533068816994074659",
      "chat_id": "7533068816994074659",
      "content": "{\"lm\":{\"type\":\"text\",\"content\":\"I'm a student majoring in computer science.\"}}",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 1754289895,
      "role": "assistant",
      "type": "verbose",
      "updated_at": 1754289895
    },
    {
      "bot_id": "7533068816994074659",
      "chat_id": "7533068816994074659",
      "content": "I'm a student majoring in computer science.",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 1754289895,
      "meta_data": {
        "reasoning_content": "I'm a student majoring in computer science.",
        "refusal_reason": ""
      },
      "role": "assistant",
      "type": "answer",
      "updated_at": 1754289895
    },
    {
      "bot_id": "7533068816994074659",
      "chat_id": "7533068816994074659",
      "content": "Hello, who are you?",
      "content_type": "text",
      "conversation_id": "7546176019566460978",
      "created_at": 1754289892,
      "meta_data": {},
      "reasoning_content": "",
      "role": "user",
      "type": "question",
      "updated_at": 1754289892
    }
  ],
  "detail": {
    "logid": "202509041825251361396636235FF4E971"
  },
  "first_id": "f45e61f603157767982",
  "last_id": "7546176019566493746",
  "msg": ""
}
工作流

查看工作流列表

  • 请求方式：GET
  • 请求地址：https://api.coze.cn/v1/workflows

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
workspace_id String 必选 工作空间 ID，用于指定要查询的工作空间。
page_num Integer 必选 查询结果分页展示时，此参数用于设置查看的页码。最小值为 1。
page_size Integer 可选 查询结果分页展示时，此参数用于设置每页返回的数据量。取值范围为 1~30，默认为 10。
workflow_mode String 可选 工作流类型，默认为空，即查询所有工作流类型。枚举值：• workflow: 工作流。• chatflow: 对话流。
app_id String 可选 扣子应用 ID，用于查询指定应用关联的工作流。默认为空，即不指定应用。
publish_status String 可选 工作流的发布状态，用于筛选不同发布状态的工作流。枚举值：• all: 所有状态。• published_online:（默认值）已发布的正式版。• unpublished_draft: 当前为草稿状态。

返回参数：

{
  "detail": {
    "logid": "202509041903031316f6fC775EAD0F8ED11"
  },
  "data": {
    "has_more": true,
    "items": [
      {
        "spaces": [],
        "description": "用来学习基础节点的使用",
        "icon_url": "https://lf3-81d4c505-sign.oceancloudapi.com/ocean-cloud-tos/plugin_icon/workflow.png?lk3s=81d4c505&x-expires=1756987231&x-signature=Xi0rCYt9Byaa99%2B31Y59jcPwC3D%3D",
        "created_at": 17569154757,
        "workflow_id": "7546063221589950505",
        "app_id": "",
        "creator": {
          "id": "247833709252424",
          "name": "用户7920835014178",
          "avatar_url": "https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/coze_login/coze_default_profile_image.jpg"
        },
        "updated_at": 1756929428,
        "workflow_name": "jichu_workflow"
      }
    ]
  },
  "code": 0,
  "msg": ""
}

执行工作流

  • 请求方式：POST
  • 请求地址：https://api.coze.cn/v1/workflow/run

header 参数：

参数 取值 说明
Authorization Bearer ${Access_Token} 用于验证客户端身份的访问令牌。
Content-Type application/json 解释请求正文的方式。

请求参数：

参数 类型 是否必选 说明
workflow_id String 必选 待执行的 Workflow ID，此工作流应已发布。
parameters String 可选 工作流开始节点的输入参数及取值，以 JSON 序列化字符串形式传入。你可以在指定工作流的编排页面查看输入参数列表。
bot_id String 可选 需要关联的智能体 ID。部分工作流执行时需要指定关联的智能体，例如存在数据库节点、变量节点等节点的工作流。
app_id String 可选 该工作流关联的扣子应用的 ID。
ext JSON Map 可选 用于指定一些额外的字段，以 Map [String][String] 格式传入。例如某些插件会隐式用到的运行后等字段。
is_async Boolean 可选 是否异步执行。异步的话可通过本接口返回的 execute_id 调用查询工作流异步执行结果 API 获取工作流的最终执行结果。• true: 异步运行。• false:（默认）同步运行。
workflow_version String 可选 工作流的版本号，仅当运行的工作流属于资源库工作流时有效。未指定版本号时默认执行最新版本的工作流。

返回参数：

{
  "code": 0,
  "data": "{\"output\":\"\\République populaire de Chine\"}",
  "execute_id": "7546417726528066596",
  "debug_url": "https://www.coze.cn/work_flow?space_id=752678451385135928&workflow_id=7534995507010682906&ex&ex&ex&ex&mode=2",
  "msg": "Success",
  "usage": {
    "input_count": 643,
    "output_count": 849,
    "token_count": 849
  }
}

SDK 参考

什么是 SDK？

SDK（Software Development Kit - 软件开发工具包）由平台提供给开发者的一个 “一站式工具包”，里面包含了创建该平台应用所必需的代码库、工具、说明书和规范。

我们前面学习了扣子的 API 开发，为什么还要学习 SDK 呢？因为相比原生 API，SDK 使用起来更加方便！！

举个例子：麻婆豆腐

API 场景：你想做一道正宗的麻婆豆腐。

  1. 需要：豆腐 500 克、牛肉末 100 克、郫县豆瓣 40 克、豆豉 10 克、辣椒 5 克、花椒粉 2 克、蒜苗少许……
  2. 步骤：豆腐切块焯水、牛肉末炒酥、炒香豆瓣酱和豆豉、加入高汤煮沸、下豆腐小火入味、勾芡三次、撒花椒粉和蒜苗。
  3. 问题：你需要自己去菜市场买所有原材料、自己熬高汤、自己将花椒研碎再研磨成粉…… 最后还可能因为火候、刀工、原料问题导致失败。

SDK 场景：SDK 相当于麻婆豆腐料理包，这个料理包里包含：

预处理好的食材：已经切好并焯过水的豆腐、调配好的秘制酱料包（已经混合了精确比例的豆瓣、酱油、盐、辣椒、花椒粉）。

简单的说明书：1. 热锅放油，2. 倒入酱料包炒香，3. 加入豆腐和少量水煮 5 分钟。

你需要做：

  • 你不需要去采购和预处理任何食材。
  • 你不需要担心调料的比例和火候（酱料包已经帮你优化好了）。
  • 你只需要有一口能煮东西的锅，按照简单的二步操作。
  • 你几乎 100% 能做出大师级别的味道，速度快，零失败。

SDK 相比 API 的优点：

  • 开箱即用：SDK 为你封装好了所有底层核心步骤。
  • 封装复杂：将最复杂的原料预处理和风味调配都封装在了 “酱料包” 里，你无需关心。
  • 降低门槛：即使你是个厨房小白，也能做出专业级菜品。

安装 Python SDK

为什么选择 Python 的 SDK？

简洁、专注于业务细节，开发效率极高；语法简洁清晰，拥有海量的现成 “库”，让你能快速实现想法，专注于核心业务开发，不用及效率极高，省去底层网络处理，拥有海量的现成库，让你能快速实现想法。

文档地址：https://www.coze.cn/open/docs/developer_guides/python_overview

Python 环境与编辑器的安装

安装 Python

登录 Python 官网：https://www.python.org/

  1. 点击下载
  2. 安装 python.exe
  3. 配置环境变量
  4. 查看 python 版本
python --version
# 或
python3 --version
安装 PyCharm

登录 PyCharm 社区：https://www.jetbrains.com.cn/edu/products/download/download-thanks

  1. 下载 PyCharm Community 版安装包
  2. 安装 pycharm.exe
  3. 启动 PyCharm，创建新项目
安装 SDK

执行命令：

pip install python-coze
# 或
pip3 install python-coze

查看已安装列表：

pip list

下面我们写一个简单的代码来调用 SDK：

spaces.py

# 导入功能模块
import os
from dotenv import load_dotenv  # 必须加这个
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL

load_dotenv()

# 获取工作空间列表
def get_space_list():
    # 从环境变量获取个人令牌
    api_token = os.getenv("COZE_API_TOKEN")

    # 必须判断并退出
    if not api_token:
        print("请先设置 COZE_API_TOKEN 环境变量！")
        return

    # 初始化 Coze 客户端
    coze = Coze(
        auth=TokenAuth(token=api_token),
        base_url=COZE_CN_BASE_URL
    )

    try:
        workspaces = coze.workspaces.list()

        print("=== 工作空间列表 ===")
        for space in workspaces:
            print(f"空间名称：{space.name}")
            print(f"空间ID：{space.id}")
            print(f"角色：{space.role_type}")
            print("-" * 30)

    except Exception as e:
        print(f"调用失败：{str(e)}")


if __name__ == "__main__":
    get_space_list()

.env

COZE_API_TOKEN = pat_eTqQO7cNbiSL08mhQBBsuExprhqh45iF5meP4o5ZYKRoRvmleC15Yc3LnyhCvpHh

运行结果：

E:\pythonPlace\.venv\Scripts\python.exe E:\pythonPlace\WorkSpqce\Coze\space.py 
=== 工作空间列表 ===
空间名称：个人空间
空间ID：7600239553282048042
角色：WorkspaceRoleType.OWNER
------------------------------

进程已结束，退出代码为 0

# AI
Logo
AtomGit开源社区

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

更多推荐

cover

彻底爆了！一文吃透AIGC、Agent、MCP的概念和关系

avatar AtomGit开源社区
cover

大模型应用新手必看：收藏这份AI网关实战指南，轻松解决成本、安全、扩展难题！

avatar AtomGit开源社区
cover

基于springboot+vue公务员备考系统hx0954

avatar AtomGit开源社区