Coze 使用方式与典型场景

使用方式与典型场景

示例一：用 cURL 调 Coze OpenAPI 的对话接口

先创建会话，拿到 chat_id 与 conversation_id：

curl -X POST 'https://api.coze.cn/v3/chat' \
  -H "Authorization: Bearer $COZE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "bot_id": "'"$COZE_BOT_ID"'",
    "user_id": "demo_user_001",
    "stream": false,
    "auto_save_history": true,
    "additional_messages": [
      {
        "role": "user",
        "content": "帮我查一下 Python 入门课的下一期开课时间",
        "content_type": "text"
      }
    ]
  }'

非流式返回时状态可能仍在进行中，需轮询查询，再拉消息列表（URL 查询参数的连接符写成 &）：

# 1) 轮询会话状态，直到 status 变成 completed
curl -s -X GET 'https://api.coze.cn/v3/chat/retrieve?conversation_id=7400000000000000002&chat_id=7400000000000000003' \
  -H "Authorization: Bearer $COZE_API_TOKEN"

# 2) 拉取该轮消息，取 role=assistant 且 type=answer 的那条
curl -s -X GET 'https://api.coze.cn/v3/chat/message/list?conversation_id=7400000000000000002&chat_id=7400000000000000003' \
  -H "Authorization: Bearer $COZE_API_TOKEN"

要做打字机效果，把 stream 改成 true，接口切换为 SSE 长连接：

curl -N -X POST 'https://api.coze.cn/v3/chat' \
  -H "Authorization: Bearer $COZE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "bot_id": "'"$COZE_BOT_ID"'",
    "user_id": "demo_user_001",
    "stream": true,
    "auto_save_history": true,
    "additional_messages": [
      {"role": "user", "content": "你好", "content_type": "text"}
    ]
  }'

流式响应里，增量文本位于 message.delta 一类事件中，只把 type 为 answer 的片段拼给用户；verbose、function_call 属中间过程，一般只记日志。收尾时会收到会话完成与结束事件，此时再落库保存完整回复。事件名与字段以官方文档的流式响应说明为准。

示例二：工作流的节点编排与调用

工作流的价值在于把不确定的对话变成确定的流程。下面是一个课程咨询工作流的结构示意：开始节点收用户提问，LLM 节点做意图分类，条件判断分流到知识库检索或插件查询，最后由结束节点输出。（不同平台版本的字段名与节点 id 生成规则有差异，实际以平台导出的 JSON 为准。）

{
  "nodes": [
    {
      "id": "100001",
      "type": "start",
      "data": {
        "nodeMeta": { "title": "开始" },
        "inputs": { "question": { "type": "string", "required": true } }
      }
    },
    {
      "id": "200001",
      "type": "llm",
      "data": {
        "nodeMeta": { "title": "意图分类" },
        "inputs": {
          "prompt": "判断用户问题属于 课程咨询 / 售后 / 其他，只输出其中一个词。问题：{{question}}",
          "temperature": 0.1
        },
        "outputs": { "intent": { "type": "string" } }
      }
    },
    {
      "id": "300001",
      "type": "condition",
      "data": {
        "nodeMeta": { "title": "按意图分流" },
        "branches": [
          { "name": "课程咨询", "condition": "intent == '课程咨询'" },
          { "name": "售后", "condition": "intent == '售后'" }
        ]
      }
    },
    {
      "id": "400001",
      "type": "knowledge",
      "data": {
        "nodeMeta": { "title": "检索课程知识库" },
        "inputs": {
          "datasetIds": ["7400000000000000004"],
          "query": "{{question}}",
          "topK": 3,
          "minScore": 0.5
        }
      }
    },
    {
      "id": "900001",
      "type": "end",
      "data": {
        "nodeMeta": { "title": "结束" },
        "inputs": { "answer": { "type": "string" } }
      }
    }
  ],
  "edges": [
    { "sourceNodeID": "100001", "targetNodeID": "200001" },
    { "sourceNodeID": "200001", "targetNodeID": "300001" },
    { "sourceNodeID": "300001", "targetNodeID": "400001" },
    { "sourceNodeID": "400001", "targetNodeID": "900001" }
  ]
}

工作流发布后，用它的 workflow_id 通过 OpenAPI 独立调用，不必经过 Bot 对话链路：

curl -X POST 'https://api.coze.cn/v1/workflow/run' \
  -H "Authorization: Bearer $COZE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_id": "'"$COZE_WORKFLOW_ID"'",
    "parameters": { "question": "Python 入门课下一期什么时候开课" }
  }'

返回体里的 data 是一段 JSON 字符串，需二次解析后再取业务字段。长耗时流程改用流式运行接口，能拿到中间节点进度，也避免同步等待超时。

适合与不适合