如何获取 Coze开放平台 API 密钥(分步指南)

1. 获取Coze开放平台 API密钥步骤

获取Coze开放平台 API密钥的过程相对简单，只需几个步骤即可完成：

1.访问官方网站注册/登录：https://www.coze.cn/

2.进入扣子API页面：登录成功以后会进入到控制台首页，然后点击左侧导航栏中的扣子API。

3.进入扣子API页面后选择授权->个人访问令牌->添加。

4.根据自己的需求选择对应的权限。

5.这样就可以得到令牌信息。提示：令牌只在创建的时候显示一次，要保存好。

2. Coze开放平台 API密钥可用性测试

在获取API密钥后，进行可用性测试是确保其正常工作的重要步骤。以下是使用curl进行测试的一个案例

以下接口为Coze开放平台接口中 对话->发起对话 接口。

输入：

//图文问答
curl --location --request POST 'https://api.coze.cn/v3/chat?conversation_id=7374752000116113452' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \
--data-raw '{
  "bot_id": "737946218936519****",
  "user_id": "123456789",
  "stream": true,
  "auto_save_history":true,
  "additional_messages":[
      {
          "role":"user",
          "content":"[{\"type\":\"image\",\"file_url\":\"https://lf-bot-studio-plugin-resource.coze.cn/obj/bot-studio-platform-plugin-tos/artist/image/4ca71a5f55d54efc95ed9c06e019ff4b.png\"},{\"type\":\"text\",\"text\":\"帮我看看这张图片里都有什么\"}]",
          "content_type":"object_string"
      }
  ]
}'

输出：

结果以 JSON 格式返回，包含了对话全过程中各类事件的详细信息。例如：会话状态的变化、模型输出的内容、消息的角色和类型、以及每条消息的 Token 使用情况等。这些信息可用于跟踪一次完整对话的执行流程与模型行为。

event:conversation.chat.created
// 在 chat 事件里，data 字段中的 id 为 Chat ID，即会话 ID。
data:{"id":"7382158397837344768","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792697,"last_error":{"code":0,"msg":""},"status":"created","usage":{"token_count":0,"output_count":0,"input_count":0}}

event:conversation.chat.in_progress
data:{"id":"7382158397837344768","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792697,"last_error":{"code":0,"msg":""},"status":"in_progress","usage":{"token_count":0,"output_count":0,"input_count":0}}

event:conversation.message.completed
data:{"id":"7382158491307212815","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"function_call","content":"{\"name\":\"tupianlijie-imgUnderstand\",\"arguments\":{\"text\":\"描述图片里有什么\",\"url\":\"https://lf-bot-studio-plugin-resource.coze.cn/obj/bot-studio-platform-plugin-tos/artist/image/4ca71a5f55d54efc95ed9c06e019ff4b.png\"},\"plugin_id\":7379227414322217010,\"api_id\":7379227414322233394,\"plugin_type\":1,\"thought\":\"需求为描述图片（https://lf-bot-studio-plugin-resource.coze.cn/obj/bot-studio-platform-plugin-tos/artist/image/4ca71a5f55d54efc95ed9c06e019ff4b.png）里都有什么，需要调用tupianlijie-imgUnderstand工具理解图片\"}","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.completed
data:{"id":"7382158637826998312","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"tool_response","content":"{\"content_type\":1,\"response_for_model\":\" 这幅图像描绘了一片宁静而神秘的森林景象。画面中心是一条蜿蜒流淌的小溪，溪水清澈见底，溪床上散布着几块大小不一的石头。溪流两岸覆盖着厚厚的青苔，与周围的树木形成鲜明对比。树木高大挺拔，树干粗壮，树皮呈深褐色，树枝上长满了翠绿的针叶，阳光透过树叶的缝隙洒在地面上，形成斑驳的光影。整个场景被一层淡淡的雾气笼罩，增添了一丝神秘和幽静的氛围。画面远处的树木逐渐变得模糊，与天空的灰白色融为一体，整个画面色彩以绿色和棕色为主，营造出一种深邃而古老的感觉。整体上，这幅图像传达了一种与自然和谐共处的宁静与平和。\",\"type_for_model\":1}","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.delta
data:{"id":"7382158479043379234","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"这","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.delta
data:{"id":"7382158479043379234","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"是","content_type":"text","chat_id":"7382158397837344768"}

//省略模型回复的部分中间事件event:conversation.message.delta
......

event:conversation.message.delta
data:{"id":"7382158479043379234","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"树木","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.delta
data:{"id":"7382158479043379234","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"。","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.completed
data:{"id":"7382158479043379234","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"这是一幅非常漂亮的森林图片，里面有小溪、石头和青苔覆盖的树木。","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.message.completed
data:{"id":"7382158652519645218","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"verbose","content":"{\"msg_type\":\"generate_answer_finish\",\"data\":\"\",\"from_module\":null,\"from_unit\":null}","content_type":"text","chat_id":"7382158397837344768"}

event:conversation.chat.completed
data:{"id":"7382158397837344768","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792697,"last_error":{"code":0,"msg":""},"status":"completed","usage":{"token_count":2308,"output_count":111,"input_count":2197}}

event:done
data:"[DONE]"

3. 使用Coze开放平台API搭建应用的其他关键考虑因素

在使用Coze开放平台API搭建应用时，除了获取和测试API密钥外，还需考虑以下因素：

授权

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

Authorization: Bearer $Access_Token

其中，$Access_Token 分为以下三种：个人访问令牌、服务访问令牌、OAuth 访问令牌

常见错误码

如果成功调用扣子的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息。

code	msg	说明
4000	请求参数错误	原因：请求参数错误，主要原因包括参数格式错误、必选参数缺失等。解决方案：请参考 API 文档检查请求参数。
4001	Invalid chat（包括chat id错误，chat 找不到）	原因：指定对话不存在。主要原因包括 chat id 错误、当前账号无此 chat 的权限等。解决方案：请检查 chat id 后重试。
4003	meta data 超过限制	原因：meta_data 字段的传参超出字段限制。解决方案：请参考 API 文档检查请求参数。
4008	用户限流	原因：当日智能体使用次数超过限制。解决方案：请明日再试。
4300	上传文件时文件为空	原因：待上传的文件为空，主要原因为指定的文件名称或路径不存在、请求头 Content-Type 未指定为 multipart/form-data 等。解决方案：建议参考 API 文档检查相关设置。
5000	服务器内部错误	原因：服务端内部错误。解决方案：请稍后重试。若持续报错，请根据此错误码提交反馈，帮助我们快速定位问题。