【Coze-AI智能体平台】Coze OpenAPI 开发手册：鉴权、接口调用与 SDK 实践

小龙报2026-04-07 14:40

🔥小龙报：个人主页

🎬作者简介：C++研发，嵌入式，机器人方向学习者

❄️个人专栏：《coze智能体开发平台》
✨ 永远相信美好的事情即将发生

文章目录

  • 前言
  • 一、API参考
    • [1.1 令牌鉴权](#1.1 令牌鉴权)
    • [1.2 API Playground](#1.2 API Playground)
    • [1.3 核心API](#1.3 核心API)
      • 1.3.1工作空间
        • [1.3.1.1 查看空间列表](#1.3.1.1 查看空间列表)
        • [1.3.1.2 查看空间成员列表](#1.3.1.2 查看空间成员列表)
      • [1.3.2 智能体与应用](#1.3.2 智能体与应用)
        • [1.3.2.1 查看智能体列表](#1.3.2.1 查看智能体列表)
        • [1.3.2.2 查看应用列表](#1.3.2.2 查看应用列表)
        • [1.3.2.3 查看智能体配置](#1.3.2.3 查看智能体配置)
      • [1.3.3 对话](#1.3.3 对话)
        • [1.3.3.1 发起对话](#1.3.3.1 发起对话)
        • [1.3.3.2 查看对话详情](#1.3.3.2 查看对话详情)
        • [1.3.3.3 查看对话消息](#1.3.3.3 查看对话消息)
        • [1.3.3.4 查看对话消息详情](#1.3.3.4 查看对话消息详情)
      • [1.3.4 工作流](#1.3.4 工作流)
        • [1.3.4.1 查看工作流列表](#1.3.4.1 查看工作流列表)
        • [1.3.4.2 执行工作流](#1.3.4.2 执行工作流)
  • 二、SDK参考
    • [2.1 什么是SDK](#2.1 什么是SDK)
    • [2.2 在pyCharm安装扣子SDK](#2.2 在pyCharm安装扣子SDK)
    • [2.3 调用SDK](#2.3 调用SDK)
  • 总结与每日励志

前言

在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参数：

请求参数：

返回参数：

html 复制代码 
{
    "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参数：

请求参数：

html 复制代码 
{
    "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 请求头参数

请求参数：

返回参数：

html 复制代码 
{
    "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参数：

请求参数：

返回参数：

html 复制代码 
{
    "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参数：

请求参数：

返回参数：

html 复制代码 
{
    "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：

返回参数：

html 复制代码 
{
    "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参数：

请求参数：

返回参数：

html 复制代码 
{
    "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参数 ：

请求参数 ：

返回参数：

html 复制代码 
{
    "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 参数

请求参数

返回参数

html 复制代码 
{
  "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文件

html 复制代码 
COZE_API_TOKEN = 
pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB

.py文件

html 复制代码 
#导入功能模块
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开发的道路上收获属于自己的成果，不负每一份坚持与付出。

相关推荐
科技苑2 小时前
告别付费枷锁：在家电脑自建大模型，Token自由不是梦
人工智能·时序数据库
TDengine （老段）2 小时前
TDengine IDMP 可视化 —— 饼图
大数据·数据库·人工智能·物联网·时序数据库·tdengine·涛思数据
神の愛2 小时前
利用json-to-ts工具进行转换,放置在typeScript.ts文件中
javascript·typescript·json
databook2 小时前
理论都会，实战就废？7个分析模板，帮你打通任督二脉
python·数据挖掘·数据分析
Flying pigs~~2 小时前
从“踩坑”到“可控”：大模型 Prompt 工程实战总结与进阶方法论
大数据·人工智能·大模型·prompt·提示词工程
safestar20122 小时前
Agent系统架构中的「注意力聚焦模式」：从理论到工程实践
人工智能·ai·系统架构·ai编程
星马梦缘3 小时前
rl库 AttributeError: ‘bool‘ object has no attribute ‘items‘ 的解决方案
人工智能·深度学习·机器学习·强化学习
China_Yanhy3 小时前
Gemini said动手学大模型第二篇学习总结：从“调参”到“调教”
人工智能
老马95273 小时前
opencode2-初步体验
人工智能·后端
热门推荐
01GitHub 镜像站点02OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程03Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）04AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南05VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）06Claude Code 未登录 使用第三方模型07Oh My Codex 快速使用指南08【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线09最新更新版本，OpenClaw v2026.4.2 深度解读剖析：Task Flow 重磅回归与安全架构的全面硬化10UV安装并设置国内源