【Coze-AI智能体平台】Coze OpenAPI 开发手册：鉴权、接口调用与 SDK 实践
🔥小龙报：个人主页
🎬作者简介：C++研发，嵌入式，机器人方向学习者
❄️个人专栏：《coze智能体开发平台》
✨ 永远相信美好的事情即将发生
文章目录
前言
在AI智能体开发领域，Coze平台为开发者提供了灵活高效的开发路径，而API与SDK正是解锁其自定义开发能力的核心钥匙。本文将从令牌鉴权入手，逐步拆解Coze核心API的使用方法，再对比API与SDK的差异，讲解SDK的安装与调用，帮助有编程基础的开发者快速上手，零成本体验Coze OpenAPI能力，高效实现智能体与应用的二次开发，开启AI开发的全新可能。
一、API参考
Coze 支持将 AI 智能体和扣子应用发布为 API（Application Programming Interface 应用程序编程接口）服务，你可以通过 HTTP 方式与其进行交互。有编程基础的情况下，能够给用户更多的自定义开发空间。
1.1 令牌鉴权
我们来用⼀个“校园外卖代拿”的场景，帮你彻底理解这三个概念的区别与联系。
故事背景你是一名大学生，我们叫你 “小明”。你不想去食堂吃饭，用 “饿了么” App 点了一份外卖。但是学校规定，外卖小哥不能进宿舍楼，只能把外卖放到宿舍区大门口的 “外卖架” 上。问题来了：你正在王者峡谷激战，不想亲自下楼去拿。怎么办？这时，你发现有一个叫 “小闪代拿” 的校园服务，专门帮同学去外卖架取外卖并送到寝室。你需要使用这个服务。接下来，三种令牌依次登场：
1.个人访问令牌 - 你的 “学生证”
场景：
“小闪代拿” 服务为了安全起见，需要验证你是本校学生。它让你输入学号和密码登录学校的 “学生信息服务平台” 来确认你的身份。
你觉得每次都要输密码很麻烦，而且把密码直接给一个第三方服务也不安全。于是，学校的 “学生信息服务平台” 提供了一个功能：“生成访问令牌”。
你登录平台后，生成了一个名为 “用于小闪代拿” 的令牌（一长串无规律的字符）。以后，“小闪代拿” 只需要出示这个令牌，平台就知道是 “小明” 授权的，可以获取你的基本信息（如姓名、楼栋、寝室号），而无需知道你的密码。
2.OAuth 访问令牌 - 你的 “一次性取餐码”
场景：
现在 “小闪代拿” 知道你是小明，住在 3 号楼 501 了。但它要去帮你拿外卖，还需要向 “外卖架” 证明：“我是小明授权来取他的外卖的”。
外卖平台也有一个系统，每个订单都会生成一个取餐码（比如：8A3B）。这个码是动态的、一次性的（或短期有效）。
于是，流程是这样的：
“小闪代拿” 对你说：“请授权我去‘饿了么’拿你的外卖。”
你（小明）被引导到 “饿了么” 的授权页面，上面写着：“小闪代拿申请获取你当前订单的外卖权限”。你点击 “同意”。
“饿了么” 不给你密码，而是生成一个一次性的取餐码 8A3B，交给 “小闪代拿”。
“小闪代拿” 小哥拿着这个码 8A3B 去外卖架，工作人员扫这个码，确认无误，就把标有 8A3B 的外卖交给了小哥。
3.服务访问令牌 - “小闪代拿” 公司的 “工作证”
场景：
“小闪代拿” 小哥拿到了外卖，现在要进入你的宿舍楼。宿舍楼阿姨可不会认 “饿了么” 的取餐码，她只认自己系统的规矩。
“小闪代拿” 公司已经和学校后勤部门谈好了合作。后勤部门给 “小闪代拿” 公司发放了统一的工作证，所有持此证的工作人员都可以在特定时间（如 11:00-13:00）内出入宿舍楼。
小哥向楼管阿姨出示这个公司工作证，阿姨验证后放行，最终把外卖送到了你手里。
总结
我们重点学习个人访问令牌（PAT）
创建个人访问令牌的时候，个人访问令牌（PAT）
点击添加按钮之后会出现添加个人访问令牌的页面
在添加个人访问令牌页面，可以指定令牌的名称、过期时间、分配权限点和访问工作空间
pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB等生成了令牌之后，需要把令牌保存下来，因为只显示⼀次
1.2 API Playground
API Playground 是扣子（Coze）官方提供的在线 API 调试工具，核心定位是帮助开发者零成本、可视化地快速体验扣子 OpenAPI 能力，无需搭建本地开发环境。
API Playground网址：API Playground
1.3 核心API
扣子接口文档：网址
1.3.1工作空间
1.3.1.1 查看空间列表
请求方式：GET
GET请求地址 ：地址
header参数：
请求参数：
返回参数：
{ "code": 0, "data": { "total_count": 2, "workspaces": [ { "name": "上课", "enterprise_id": "", "owner_uid": "247833709252424", "id": "7540958230303162414", "icon_url": "https://lf6-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_SPACE/team.png?lk3s=50ccb0c5x-&expires=1757123185&x-signature=N8fE7CLf1v8s4P2UhTkYPf8uo0%3D", "role_type": "owner", "workspace_type": "team", "joined_status": "joined", "description": "", "admin_uids": [] } ] }, "msg": "", "detail": { "logid": "20250905094625889C23E948B98E62AF73" } } 1.3.1.2 查看空间成员列表
请求方式: GET
请求低址: 地址
header参数：
path参数：
请求参数：
{ "code": 0, "data": { "total_count": 1, "items": [ { "role_type": "owner", "user_id": "247833709252424", "user_nickname": "科技-", "user_unique_name": "", "avatar_url": "https://lf3-coze-web.oceancloudapi.com/obj/platform-web-user-center/7540221695526256678/avatar/1735962306827976192.png" } ] }, "msg": "", "detail": { "logid": "20250908143554B48D9B057229E01A24E" } } 1.3.2 智能体与应用
1.3.2.1 查看智能体列表
请求方式：GET
请求地址：网址
Header 请求头参数
请求参数：
返回参数：
{ "data": { "total": 1, "items": [ { "is_published": true, "updated_at": 1755593536, "icon_url": "https://lf3-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/247833709252424_1755244732481931594.jpeg?lk3s=ca44e09c&x-expires=1757123241&x-signature=672Paco1ZgSAIsWbTbBcr1z75WU%3D", "id": "7536152918114779162", "published_at": 1755593536, "owner_user_id": "247833709252424", "name": "动物世界", "description": "动物世界机器人专业生成精彩动物视频，智能解析用户输入，快速制作丰富多样的动物内容，带您畅游神奇的动物世界。" } ] }, "msg": "", "detail": { "logid": "202509050947214BCB51EB71C7D00B4804" }, "code": 0 } 1.3.2.2 查看应用列表
请求方式：GET
请求地址：网址
header参数：
请求参数：
返回参数：
{ "code": 0, "data": { "total": 1, "items": [ { "name": "翻译助手", "description": "", "icon_url": "https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/247833709252424_1754705142427878739.jpeg?lk3s=ca44e09c&x-expires=1757123286&x-signature=FnELaMkqoIoM6vhFSHL4u%2B25ncN3D%3D", "id": "7535545682137595923", "published_at": 1754722053, "owner_user_id": "247833709252424", "is_published": true, "updated_at": 1754722053 } ] }, "msg": "", "detail": { "logid": "20250905894806A7F4D19245CE006E9939" } } 1.3.2.3 查看智能体配置
请求方式：GET
请求地址：
header参数：
path参数：
请求参数：
返回参数：
{ "msg": "", "detail": { "logid": "202509050907ATD4E30EFB1275G5262" }, "code": 0, "data": { "owner_user_id": "247833709252424", "description": "动物世界机器人专业生成精彩动物视频，智能解析用户输入，快速制作丰富多样的动物内容，带您畅游神奇的动物世界。", "version": "1755593535305", "shortcut_commands": [], "plugin_info_list": [], "knowledge": { "knowledge_infos": [] }, "create_time": 1754648214, "name": "动物世界", "bot_mode": 0, "background_image_info": { "mobile_background_image": { "origin_image_url": "", "image_url": "", "theme_color": "", "gradient_position": [], "canvas_position": {} }, "web_background_image": { "gradient_position": [], "canvas_position": {}, "origin_image_url": "", "image_url": "", "theme_color": "" } }, "model_info": { "model_name": "豆包1.5·Pro·32k", "cache_type": "closed", "parameters": {}, "temperature": 0.8, "context_round": 3, "max_tokens": 4096, "model_id": "1737521813" }, "workflow_info_list": [ { "icon_url": "https://lf6-appstore-sign.oceancloudapi.com/ocean-cloud-tos/plugin_icon/workflow.png?lk3s=81d4c505&x-expires=1757048607&x-signature=KNGQh3F7fan5MJ8fjDHMkRfb/pgl3D/", "id": "7536125153777401804", "name": "animals_workflow", "description": "该工作流用于生成动物世界相关视频\n" } ], "voice_info_list": [], "default_user_input_type": "text", "variables": [], "update_time": 1755593535, "bot_id": "7536152918114779162", "prompt_info": { "prompt": "# 角色\n你是一个专业的「动物世界」视频生成者。\n\n## 技能\n### 技能：生成视频\n1. 用户无论输入什么，都调用工作流{#Library@block id=\"7536125153777401804\" uuid=\"reXt5oCGY5fwGdDPcs1R\" type=\"workflow\"#}animals_workflow{/#Library@block#}，其中输入的内容作为工作流的input参数", "prompt_mode": "standard" }, "media_config": { "is_voice_call_closed": false }, "icon_url": "https://lf6-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/247833709252424_1755244732481931594.jpeg?lk3s=50ccb0c5&x-expires=1757641007&x-signature=G1KA528M41BufW4aasf579c7u0sE3JD/", "onboarding_info": { "prologue": "嗨，你好！我热衷于创造精彩的视频世界，能为你带来独特体验。", "suggested_questions": [ "你能生成哪些动物的视频？", "视频的画质怎么样？", "制作一个视频需要多久？" ] }, "suggest_reply_info": { "reply_mode": "enable", "customized_prompt": "" } } } 1.3.3 对话
1.3.3.1 发起对话
请求方式：POST
请求地址：地址
header参数：
请求参数：
Query：
Body：
返回参数：
{ "bot_id": "7536152918114779162", "user_id": "user_123456", "additional_messages": [ { "role": "user", "content": "帮我生成一个狮子的视频" } ], "stream": true, "auto_save_history": true, "custom_variables": { "style": "高清4K" } } 1.3.3.2 查看对话详情
请求方式：GET
请求地址：地址
header参数：
请求参数：
返回参数：
{ "code": 0, "data": { "bot_id": "7533068816994074659", "completed_at": 1756981032, "conversation_id": "7546176019566460978", "created_at": 1756981023, "id": "7546176019566510130", "status": "completed", "usage": { "input_count": 4219, "input_tokens_details": { "cached_tokens": 0 }, "output_count": 251, "output_tokens_details": { "reasoning_tokens": 194 }, "token_count": 4470 } }, "detail": { "logid": "202509041819593F7424B7ECF64A335D7F" }, "msg": "" } 1.3.3.3 查看对话消息
请求方式：GET
请求地址：地址
header参数：
请求参数：
1.3.3.4 查看对话消息详情
请求方式：GET
请求地址：地址
header参数：
请求参数：
注意：1.3.3.3和1.3.3.4返回消息过长不做展示啦
1.3.4 工作流
1.3.4.1 查看工作流列表
请求方式: GET
请求地址: 网址
header参数：
请求参数 ：
返回参数：
{ "detail": { "logid": "202509041900313166FC7775EAD0FEED11" }, "data": { "has_more": true, "items": [ { "description": "用来学习基础节点的使用", "icon_url": "https://lf3-appstore-sign.oceancloudapi.com/ocean-cloud-tos/plugin_icon/workflow.png?lk3s=81d4c505&x-expires=1756987231&x-signature=Xi0rCYt97clDB9yaa99%2B31yTPjc%3D", "created_at": 1756954757, "workflow_id": "7546063221589950505", "app_id": "0", "creator": { "id": "247833709252424", "name": "用户7920835014178" }, "updated_at": 1756959245, "workflow_name": "jichu_workflow" } ] }, "code": 0, "msg": "" } 1.3.4.2 执行工作流
请求方式：POST
请求地址：网址
Header 参数
请求参数
返回参数
{ "code": 0, "data": "{\"output\":\"République populaire de Chine\"}", "debug_url": "https://www.coze.cn/workflow?execute_id=754616829066596&space_id=75267845135159284&workflow_id=7534995507010686&execute_code=2", "usage": { "input_count": 843, "output_count": 6, "token_count": 849 }, "msg": "Success" } 二、SDK参考
2.1 什么是SDK
sdk（SoftwareDevelopmentKit-软件开发工具包）由平台方提供给开发者的⼀个“一站式工具包”，里面包含了创建该平台应用所必需的代码库、工具、说明书和规范。
我们前面学习了扣子的部分主要API，为什么还要学习SDK呢？因为相比较与API，SDK使用起来更加方便！！！
比如：你想做⼀道正宗的麻婆豆腐。
API就相当于麻婆豆腐的菜谱，菜谱上写着：
1.需要：豆腐500克、牛肉末100克、郫县豆瓣酱40克、豆豉10克、辣椒粉5克、花椒粉2克、蒜苗少许…
2.步骤：豆腐切块焯水、牛肉炒酥、炒香豆瓣酱和豆豉、加入高汤煮沸、下豆腐小火入味、勾芡三次、撒花椒粉和蒜苗。
你需要做：
• 你需要自己去菜市场购买所有原材料，并判断它们的好坏。
• 你需要自己熬制高汤。
• 你需要自己将豆豉剁碎。
• 你需要自己将花椒焙香气再研磨成粉。
• 最终你可能因为火候、刀工、原料品质等问题做失败。
SDK 就相当于麻婆豆腐料理包，这个料理包里包含：
1.预处理的食材：已经切好并焯过水的豆腐块、调配好的秘制酱料包（已经混合了精确比例的豆瓣酱、豆豉、辣椒粉）。
2.简单的说明书：1. 热锅放油；2. 倒入酱料包炒香；3. 加入豆腐和少量水煮 3 分钟。
你需要做：
• 你不需要去采购和预处理任何食材。
• 你不需要担心调料的比例和火候（酱料包已经帮你优化好了）。
• 你只需要有一口最普通的锅，按照最简单的三步操作。
• 你几乎 100% 能还原出大师级别的味道，速度快，零失败。
SDK相比与API的优点：
• 开箱即用：所有东西都准备好了，直接开始核心步骤。
• 封装复杂：将最复杂的原料预处理和风味调配都封装在了酱料包里，你无需关心。
• 降低门槛：即使你是个厨房小白，也能做出专业级菜品。
2.2 在pyCharm安装扣子SDK
执行命令：pip install cozepy
2.3 调用SDK
安装依赖：pip install python-dotenv
查看空间列配置文件：使用配置文件可以保护敏感信息和增强代码的可维护性
.evn文件
COZE_API_TOKEN = pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB .py文件
#导入功能模块 import os from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL #加载环境变量 from dotenv import load_dotenv load_dotenv() #获取工作空间的列表 def get_space_list(): # 声明访问令牌 api_token = os.environ.get("COZE_API_TOKEN") if not api_token: print("请先设置一下个人令牌") return # 原代码漏了return，导致空令牌继续执行 # 初始化coze客户端 coze = Coze( # 声明令牌 auth= TokenAuth(token=api_token), # 声明域名 base_url= COZE_CN_BASE_URL, ) # 创建完coze客户端之后，就可以进行调用了 try: spaces = coze.workspaces.list() if hasattr(spaces, "items"): spaces = spaces.items print(spaces) except Exception as e: print(f"调用访问空间列表SDK失败：{str(e)}") if __name__ == "__main__": get_space_list() 总结与每日励志
✨本文详细讲解了Coze平台的API参考与SDK使用，从令牌鉴权、API Playground调试，到核心API的请求与返回，再到SDK的安装调用，完整覆盖了开发者入门所需的关键知识点。掌握这些内容，能帮助我们高效利用Coze的开发能力，降低AI智能体二次开发的门槛。技术学习从来不是一蹴而就，每一次调试成功、每一次知识点突破，都是成长的印记。永远相信美好的事情即将发生，保持热爱、深耕不辍，终会在AI开发的道路上收获属于自己的成果，不负每一份坚持与付出。
![【程序员副业指南】KwaiKAT AI制作小红薯[特殊字符]卡片MCP](https://qiniu.meowparty.cn/coder.2023/2026-04-11/cover_1775897631334_1be1ecb55e294966ae6d5e87606208ae.png)