/coze-api

name: coze-api
description: 调用扣子(Coze)智能体 API 进行对话、工作流执行等操作。当用户需要集成 Coze 智能体、调用 Coze API、或开发 Coze 相关应用时使用。支持流式和非流式对话、工作流调用等功能。

Coze API 集成 Skill

扣子(Coze)是字节跳动推出的 AI 智能体开发平台,本 Skill 提供完整的 Coze API 调用指南。

核心功能

1. **对话 API (Chat API)** - 与智能体进行对话 2. **工作流 API (Workflow API)** - 执行工作流 3. **消息管理** - 查询对话状态和消息列表

快速开始

1. 准备工作

在使用 Coze API 前需要完成以下准备:

**获取访问令牌 (Personal Access Token)** 1. 登录 Coze 平台: https://www.coze.cn 2. 进入个人中心 → API 管理 3. 创建个人访问令牌(PAT) 4. 保存令牌(仅显示一次)

**获取 Bot ID** 1. 进入 Bot 编辑页面 2. 从 URL 中获取 Bot ID

• 例如: `https://www.coze.cn/space/123/bot/7348293334`
• Bot ID 为: `7348293334`

**发布 Bot 为 API 服务** 1. 在 Bot 页面点击"发布" 2. 选择"Bot as API" 3. 等待审核通过

2. API 基础信息

**API 基础 URL**

• 国内版: `https://api.coze.cn`
• API 版本: v3(推荐)

**认证方式**

Authorization: Bearer {YOUR_PAT_TOKEN}
Content-Type: application/json

**使用限制**

• 基础版: 每账号 100 次 API 调用(一次性)
• 专业版: 无限制,按 Token 消耗计费

对话 API (Chat API)

非流式对话

发起一次完整对话,等待完整结果后返回。

**API 端点**

POST https://api.coze.cn/v3/chat

**Python 示例代码**

import requests
import json

API_URL = "https://api.coze.cn/v3/chat"
RETRIEVE_URL = "https://api.coze.cn/v3/chat/retrieve"
MESSAGE_LIST_URL = "https://api.coze.cn/v3/chat/message/list"

# 配置参数
PAT_TOKEN = "YOUR_PAT_TOKEN"
BOT_ID = "YOUR_BOT_ID"
USER_ID = "unique_user_id"

def send_message(message):
    """发起对话"""
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "bot_id": BOT_ID,
        "user_id": USER_ID,
        "stream": False,
        "auto_save_history": True,
        "additional_messages": [
            {
                "role": "user",
                "content": message,
                "content_type": "text"
            }
        ]
    }
    
    response = requests.post(API_URL, headers=headers, json=data)
    return response.json()

def check_status(conversation_id, chat_id):
    """查询对话状态"""
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",
        "Content-Type": "application/json"
    }
    
    params = {
        "conversation_id": conversation_id,
        "chat_id": chat_id
    }
    
    response = requests.get(RETRIEVE_URL, headers=headers, params=params)
    return response.json()

def get_messages(conversation_id, chat_id):
    """获取对话消息"""
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",
        "Content-Type": "application/json"
    }
    
    params = {
        "conversation_id": conversation_id,
        "chat_id": chat_id
    }
    
    response = requests.get(MESSAGE_LIST_URL, headers=headers, params=params)
    return response.json()

# 使用示例
result = send_message("你好,请介绍一下自己")
print(json.dumps(result, ensure_ascii=False, indent=2))

流式对话

实时接收 AI 回复,类似打字机效果。

**Python 示例代码**

import requests
import json

def stream_chat(message):
    """流式对话"""
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "bot_id": BOT_ID,
        "user_id": USER_ID,
        "stream": True,
        "auto_save_history": False,  # 流式时必须为 False
        "additional_messages": [
            {
                "role": "user",
                "content": message,
                "content_type": "text"
            }
        ]
    }
    
    response = requests.post(API_URL, headers=headers, json=data, stream=True)
    
    # 处理流式响应
    for line in response.iter_lines():
        if line:
            line_str = line.decode('utf-8')
            
            # 跳过非 data 行
            if not line_str.startswith('data:'):
                continue
                
            # 提取 JSON 数据
            json_str = line_str.split('data:', 1)[1].strip()
            
            try:
                data = json.loads(json_str)
                
                # 处理消息事件
                if data.get('event') == 'conversation.message.delta':
                    content = data.get('data', {}).get('content', '')
                    print(content, end='', flush=True)
                    
                # 处理完成事件
                elif data.get('event') == 'conversation.message.completed':
                    print("\n[对话完成]")
                    
            except json.JSONDecodeError:
                continue

# 使用示例
stream_chat("写一首关于春天的诗")

重要参数说明

**请求参数**

• `bot_id` (必填): Bot 的唯一标识符
• `user_id` (必填): 用户标识符,用于区分不同用户
• `stream` (必填): 是否使用流式输出
• `true`: 流式输出,`auto_save_history` 必须为 `false`
• `false`: 非流式输出,`auto_save_history` 必须为 `true`
• `auto_save_history`: 是否自动保存历史记录
• `additional_messages`: 消息数组
• `role`: 角色,通常为 "user"
• `content`: 消息内容
• `content_type`: 内容类型,通常为 "text"
• `conversation_id` (可选): 对话 ID,用于继续之前的对话

**响应字段**

• `conversation_id`: 对话 ID
• `chat_id`: 本次对话的 ID
• `status`: 对话状态
• `in_progress`: 处理中
• `completed`: 已完成
• `failed`: 失败

工作流 API

执行已发布的工作流。

**API 端点**

POST https://api.coze.cn/v3/workflows/run

**Python 示例代码**

import requests
import json

WORKFLOW_RUN_URL = "https://api.coze.cn/v3/workflows/run"

def run_workflow(workflow_id, parameters):
    """执行工作流"""
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "workflow_id": workflow_id,
        "parameters": parameters
    }
    
    response = requests.post(WORKFLOW_RUN_URL, headers=headers, json=data)
    return response.json()

# 使用示例
workflow_id = "73xxx47"
params = {
    "input_text": "需要处理的文本",
    "option": "选项A"
}

result = run_workflow(workflow_id, params)
print(json.dumps(result, ensure_ascii=False, indent=2))

完整示例: 轮询获取对话结果

非流式对话需要轮询查询状态,直到对话完成。

import requests
import time
import json

def chat_with_polling(message, max_retries=30, interval=2):
    """
    发起对话并轮询获取结果
    
    Args:
        message: 用户消息
        max_retries: 最大重试次数
        interval: 轮询间隔(秒)
    """
    headers = {
        "Authorization": f"Bearer {PAT_TOKEN}",