一、基础定义与定位1. 名称与入口官方全称Coze OpenAPI Playground访问地址https://www.coze.cn/open/playground 定位官方在线可视化 API 调试控制台替代本地 Postman/Apifox、curl 命令零安装、网页直接调试扣子全部开放接口同时配套专用实时语音 / 视频 Realtime Playground。2. 核心作用可视化填参调试所有 Coze 开放接口智能体对话、会话、工作流、知识库、语音等自动生成多语言调用代码Bash curl、Python、Java、Go、JS原生支持 SSE 流式对话实时展示不用手动写-N等 curl 参数一键鉴权自动携带 Bearer Token省去手动拼接请求头查看完整响应头、响应体、全链路 Trace快速排查 401/404 / 流式断流问题区分于普通 Bot 聊天窗口Playground调用真实生产 OpenAPI会消耗模型积分 / 计费普通 Bot 预览窗口不计费。3. 两大 Playground 区分表格类型用途适用场景OpenAPI Playground主工具REST API 调试/v3/chat、会话、工作流、知识库curl 替代、后端集成调试、智能体流式对话Realtime Chat Playground实时语音 / 视频通话、语音流式对话语音智能体、实时打断、音色调试二、主界面五大核心区域详解① 左侧API 分类导航树覆盖扣子全量 OpenAPI按业务模块分组扣子对话核心最常用/v3/chat发起智能体对话流式 / 非流式/v3/chat/retrieve查询对话完整结果/v1/conversation/create新建会话维持上下文 conversation_id智能体管理创建 / 发布 / 下架 Bot、获取 Bot 配置会话管理查看消息、清空上下文、删除会话工作流同步 / 异步执行发布后的工作流 API知识库、文件上传、语音、空间成员、回调接口等② 接口基础信息区展示当前选中接口请求方法POST/GET、完整 URL、接口描述、入参出参文档、字段必填标记*。③ 请求参数配置区核心操作区分为三块Header、Query Params、Body JSONHeader 鉴权必配Authorization: Bearer {PAT令牌}两种获取方式 1页面一键授权自动填充临时 Token 2手动粘贴个人访问令牌个人中心→API 管理创建 pat_xxxQuery 参数接口路径携带参数如 chat_id、conversation_idRequest BodyJSON 可视化表单 / 代码编辑器双模式 以/v3/chat流式对话为例必填字段bot_id智能体唯一 IDuser_id自定义用户标识conversation_id会话 ID多轮上下文复用stream: true开启 SSE 流式additional_messages用户提问数组④ 代码生成面板填完所有参数后自动生成可直接复制的调用代码Bash curl和之前手写 curl 完全等价一键复制到终端运行Python SDK、Java、Go、JavaScript 等多语言示例 完美解决手写 curl 容易写错 Header、JSON 转义、遗漏Accept: text/event-stream的问题。⑤ 响应结果展示区基础信息HTTP 状态码、响应耗时、响应头普通接口完整 JSON 一次性返回SSE 流式stream:true实时逐行打印 data 分片自动解析 thought/tool_call/message/done 事件等同于 curl-N无缓冲效果高级Trace 调试链接可查看智能体内部执行链路知识库检索、工具调用、LLM 推理耗时。三、实操完整流程调试 /v3/chat 流式智能体 API步骤 1准备前置资源Coze 账号创建智能体发布并开启「Agent as API」复制 Bot ID个人中心创建 PAT 访问令牌pat_开头。步骤 2进入 Playground 并选择接口左侧导航 → 对话 →POST /v3/chat。步骤 3配置鉴权 HeaderHeader 添加Authorization: Bearer pat_你的密钥或点击页面授权按钮自动填充临时 Token。步骤 4填写请求 Body JSON流式对话json{ bot_id: 123456789, user_id: user_001, conversation_id: conv_00001, stream: true, auto_save_history: true, additional_messages: [ { role: user, content_type: text, content: 查询南京今日天气给出穿搭建议 } ] }步骤 5发送请求查看流式实时输出点击【运行】右侧实时滚动 SSE 分片 thought 思考事件 → tool_call 工具调用 → message 文本增量 → done 结束标记。步骤 6复制生成 curl 命令到本地终端验证代码面板选择 Bash复制完整 curl 命令在本地 shell 直接运行效果和 Playground 完全一致。四、Playground vs 手写 curl 对比表格对比维度Coze Playground手动 curl 命令使用门槛网页可视化表单零命令行基础需要掌握 curl 参数、JSON 转义、Header 写法SSE 流式支持原生自动实时展示无需额外配置必须手动加-N、Accept: text/event-stream鉴权一键授权自动填充 Token手动拼接 Bearer 密钥容易空格错误 401多轮上下文可视化修改 conversation_id手动修改 JSON 字符串转义易出错代码生成一键输出全语言示例手动逐行编写易漏参数排错能力自动展示完整响应头、Trace 链路需加-v参数才能看请求日志环境依赖浏览器直接打开无安装本地需要终端环境共同点调用同一套线上生产 API均消耗积分返回标准 SSE 事件格式五、关键注意事项避坑计费消耗Playground 请求走真实生产环境chat 对话、工作流执行会扣除积分 / 按量扣费查询类接口查会话、查 Bot 信息免费。会话上下文机制同一conversation_id自动保存云端历史每次更换 conv_id 会新建空白会话和 curl 行为完全一致。流式开关区别stream:trueSSE 长连接分片输出stream:false一次性返回完整 JSON无实时打字效果。写入类接口谨慎操作创建 / 删除智能体、清空知识库等修改型接口Playground 会真实修改线上资源测试注意区分测试 Bot。临时授权 Token 有效期短页面一键授权生成的临时令牌仅短期有效长期调试、线上业务使用必须手动创建永久 PAT 令牌。六、Realtime 语音 Playground 补充拓展独立语音调试工具专门调试实时语音通话 API配置项访问令牌、智能体 Bot、音色、降噪、语音模型能力麦克风实时对话、随时打断 AI 回复、切换音色输出实时展示语音信令、ASR 转文字、TTS 合成事件流适用语音机器人、车载实时对话、电话智能体开发调试。七、总结Coze Playground 是官方一体化 API 调试工具完美替代本地 curl/Postman核心优势是可视化填参、自动生成 curl 代码、原生支持 SSE 流式实时解析、一键鉴权排障开发流程标准链路Playground 调试验证接口 → 复制生成 curl 命令本地复测 → 复制 SDK 代码集成自有系统云原生微服务、K8s 业务服务。