前面我们已经掌握了 Coze 平台可视化开发的全部能力，但可视化搭建只能在平台内使用，如果要把 AI 能力集成到自己的网站、APP、企业系统中，就需要用到Coze OpenAPI。

一、Coze API 简介

Coze API 是 Coze 平台对外开放的编程接口，允许开发者通过代码调用平台上已搭建好的智能体、工作流、知识库等全部 AI 能力，将 Coze 的能力无缝集成到自有业务系统中。

简单来说：可视化搭建负责快速实现 AI 逻辑，API 负责把 AI 能力嵌入到你的产品里，对外提供服务。

1.1 两种调用方式

1. HTTP API 原生调用：直接通过 HTTP 协议请求接口，灵活性最高，适配所有编程语言，但需要自行处理鉴权、参数组装、错误处理
2. 官方 SDK 调用：官方封装了 Python、Java、JavaScript 等多语言 SDK，底层仍是 HTTP，大幅简化开发，是绝大多数场景的首选

1.2 核心能力范围

通过 API 可以实现几乎所有平台操作：智能体对话、工作流运行、知识库管理、文件上传、智能体发布、工作空间管理、语音处理等，覆盖从开发到运维的全流程。

二、环境准备与鉴权方式

所有 Coze API 请求都需要鉴权，平台提供三类鉴权方案，分别适配不同的使用场景。

2.1 三类鉴权方式对比

鉴权方式	简称	核心特点	适用场景	安全性
个人访问令牌	PAT	个人账号生成，配置简单，可设置权限与有效期	本地开发、测试调试、个人项目	一般，需妥善保管
服务访问令牌	SAT	服务身份创建，可永久有效，配置简单	后端服务、自动化脚本、系统间调用	中等
OAuth 访问令牌	OAuth	标准 OAuth2.0 协议，令牌有效期短，支持多种授权模式	线上生产环境、面向 C 端的应用	最高

选型建议：教学与本地开发优先使用 PAT，快速上手；生产环境优先使用 OAuth，保障接口安全。

2.2 PAT 令牌生成

国内版生成地址：https://www.coze.cn/open/oauth/pats

1. 登录后点击「添加新令牌」
2. 设置令牌名称、有效期、关联空间、接口权限
3. 生成后立即复制保存，仅显示一次，丢失无法找回

注意：境外版 coze.com 国内无法直接访问，国内开发统一使用国内站令牌。

2.3 安装 Python SDK

Coze 官方提供了完善的 Python SDK，支持同步 / 异步调用、全量 API 接口，持续迭代更新。

第一步：创建 Python 环境（推荐）

conda create -n coze python=3.12.7
conda activate coze

第二步：安装 SDK

pip install cozepy

SDK 更新非常活跃，截至 2025 年 8 月已支持智能体创建 / 取消发布、工作流版本管理、工作空间成员管理、声纹识别等大量新接口，可通过 GitHub 官方示例仓库查看最新能力。

三、SDK 连通性测试实战

我们先通过查询工作空间列表，验证 SDK 是否能正常调用，熟悉客户端初始化流程。

3.1 完整示例代码

"""
功能：测试Coze Python SDK连通性，获取工作空间列表
"""
from cozepy import COZE_CN_BASE_URL, Coze, TokenAuth

# ========== 配置参数 ==========
# 替换为你自己的PAT令牌
COZE_API_TOKEN = "你的个人访问令牌"
# 国内站使用默认COZE_CN_BASE_URL，境外站需自行配置base_url
BASE_URL = COZE_CN_BASE_URL

# ========== 初始化客户端 ==========
# 1. 构建认证对象
auth = TokenAuth(token=COZE_API_TOKEN)
# 2. 创建同步客户端
coze_client = Coze(auth=auth, base_url=BASE_URL)

# ========== 查询工作空间列表 ==========
if __name__ == "__main__":
    try:
        # 调用工作空间列表接口，返回迭代器自动分页
        workspaces = coze_client.workspaces.list()
        
        print("===== 我的工作空间 =====")
        for ws in workspaces:
            # 打印工作空间信息
            print(f"空间ID：{ws.id}")
            print(f"空间名称：{ws.name}")
            print("-" * 30)
        
        # 打印请求日志ID，排错必备
        print(f"请求日志ID：{workspaces.response.logid}")
        
    except Exception as e:
        print(f"调用失败：{str(e)}")

3.2 关键说明

1. COZE_CN_BASE_URL 是 SDK 内置的国内站地址，无需手动拼接
2. 工作空间列表返回的是迭代器，遍历会自动分页拉取全部数据
3. 每个接口响应都附带 logid，遇到问题可凭此 ID 排查故障
4. 开发学习不用死记硬背 API，优先参考官方示例代码，按需修改即可

四、对话 API 核心概念与实战

对话调用是最常用的 API 能力，在正式写代码前，先搞懂四个核心概念，避免逻辑混淆。

4.1 对话四大核心对象

表格

概念	说明
会话（Conversation）	用户与智能体的一整段交互，包含多条消息，自动管理上下文
消息（Message）	单条交互内容，支持文本、图片、文件、音频等多模态
对话（Chat）	一次具体的模型调用请求，智能体接收输入并执行任务，生成回复
上下文段落（Section）	会话内的上下文分段，清除上下文即创建新 Section，隔离历史消息

简单理解：一次对话是一次问答，多个问答组成一个会话，Section 用来分隔不同的对话主题。

4.2 实战：多模态文件解析对话

下面实现一个完整场景：上传本地简历文档，调用智能体解析文档内容，采用流式输出实时展示结果。

"""
功能：上传文件 + 调用智能体解析内容 + 流式输出
场景：上传简历文档，调用多功能机器人提取简历信息
"""
import os
from pathlib import Path
from cozepy import COZE_CN_BASE_URL, ChatEventType, Coze, TokenAuth, Message, MessageObjectString

# ========== 基础配置 ==========
COZE_API_TOKEN = "你的个人访问令牌"
BOT_ID = "你的智能体ID"  # 智能体网页链接末尾的数字
USER_ID = "test_user_001"  # 自定义用户标识，用于区分不同用户

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


# ========== 1. 文件上传函数 ==========
def upload_file(file_path: str):
    """上传本地文件到Coze，返回文件对象"""
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"文件不存在：{file_path}")
    
    # 单文件最大512MB
    if os.path.getsize(file_path) > 512 * 1024 * 1024:
        raise ValueError("文件大小超过512MB限制")
    
    file_obj = coze.files.upload(file=Path(file_path))
    print(f"✅ 文件上传成功，ID：{file_obj.id}")
    return file_obj


# ========== 2. 执行流式对话 ==========
def chat_with_file(file_id: str):
    """携带文件发起流式对话"""
    # 构建多模态消息：包含文件
    messages = [
        Message.build_user_question_objects([
            MessageObjectString.build_file(file_id=file_id),
        ])
    ]
    
    print("\n===== 智能体回复 =====")
    is_first_reasoning = True
    is_first_content = True
    
    # 发起流式请求
    stream = coze.chat.stream(
        bot_id=BOT_ID,
        user_id=USER_ID,
        additional_messages=messages,
    )
    
    print(f"请求日志ID：{stream.response.logid}\n")
    
    # 遍历流式事件
    for event in stream:
        # 消息增量事件：实时输出内容
        if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
            # 推理内容（思考过程）
            if event.message.reasoning_content:
                if is_first_reasoning:
                    print("【思考中...】", end="", flush=True)
                    is_first_reasoning = False
                print(event.message.reasoning_content, end="", flush=True)
            # 正式回复内容
            else:
                if not is_first_reasoning and is_first_content:
                    print("\n\n【回复内容】")
                    is_first_content = False
                print(event.message.content, end="", flush=True)
        
        # 对话完成事件
        elif event.event == ChatEventType.CONVERSATION_CHAT_COMPLETED:
            print("\n")
            print(f"本次消耗Token：{event.chat.usage.token_count}")
            break
        
        # 对话失败事件
        elif event.event == ChatEventType.CONVERSATION_CHAT_FAILED:
            print(f"\n❌ 对话失败：{event.chat.last_error}")
            break


# ========== 主程序 ==========
if __name__ == "__main__":
    try:
        # 替换为你的本地文件路径
        local_file = "02-简历.docx"
        # 上传文件
        file_info = upload_file(local_file)
        # 发起对话
        chat_with_file(file_info.id)
        
    except Exception as e:
        print(f"\n程序异常：{str(e)}")

4.3 代码要点解析

1. 文件上传：所有文件必须先上传到 Coze 平台获取file_id，才能在对话中使用，支持文档、图片、音频等格式
2. 流式输出：通过chat.stream方法实现逐字输出，体验更流畅，适合前端展示
3. 事件处理：区分消息增量、对话完成、对话失败三类事件，分别处理
4. 推理内容：支持获取模型的思考过程，可用于调试或展示给用户
5. Token 统计：对话完成事件中包含详细的用量数据，可用于成本核算

五、全量 API 能力速查

Coze SDK 覆盖的能力非常多，不用全部记住，开发时根据需求去官方示例仓库查找对应 Demo，修改即可快速复用。

核心能力分类速览：

能力模块	常用示例文件	功能说明
鉴权类	auth_pat.py、auth_oauth_web.py	各类鉴权方式的初始化示例
对话类	chat_stream.py、chat_no_stream.py	流式 / 非流式对话、多模态对话
会话类	conversation_create.py、conversation_delete.py	会话的创建、查询、删除、管理
工作流类	workflow_stream.py、workflow_async.py	同步 / 异步运行工作流、查询历史
智能体管理	bot_create.py、bot_publish.py	创建、更新、发布、下架智能体
工作空间	workspaces_list.py、workspaces_members_create.py	空间查询、成员管理
知识库	dataset_create.py	创建知识库、上传文档
语音类	audio.py、websockets_audio_*.py	语音合成、识别、实时语音通话
工具类	files_upload.py、exception.py	文件上传、异常处理、超时配置

官方示例地址：https://github.com/coze-dev/coze-py/tree/main/examples，根据文件名即可快速定位到对应功能的完整 Demo。

六、开发最佳实践与避坑

1. 令牌安全：严禁将 PAT 硬编码到代码中，生产环境使用环境变量或配置中心存储，优先使用 OAuth 鉴权
2. 流式优先：面向用户的对话场景优先使用流式接口，降低等待感，提升交互体验
3. 错误处理：所有接口调用都要做异常捕获，记录 logid，方便快速排查问题
4. 文件限制：单文件最大 512MB，注意格式支持范围，大文件建议分片处理
5. 用户标识：user_id 参数务必传入真实业务用户 ID，用于上下文隔离、用量统计与权限控制
6. 版本兼容：SDK 更新较快，建议固定版本号，避免升级带来的接口变动影响线上业务

七、本章总结

1. Coze API 是连接可视化 AI 能力与自有业务系统的桥梁，支持 HTTP 原生调用与官方 SDK 两种方式
2. 三类鉴权方式各有侧重，测试用 PAT，生产用 OAuth，选型遵循最小权限原则
3. Python SDK 封装完善，通过「文件上传 + 流式对话」即可快速实现多模态交互集成
4. 全量 API 能力无需死记硬背，掌握官方示例的查找方法，按需复用效率最高

---

上述内容会根据大家的评论和实际情况进行实时更新和改进。

麻烦小伙伴们动一动发财的小手，给小弟点个赞和收藏，如果能获得小伙伴的关注将是我无上的荣耀和前进的动力。

小伙伴们，我是AI大佬的小弟，希望大家喜欢！！！

晚安，兄弟们。