请求与响应

请求格式

HTTP 方法

方法	用途
POST	发起对话 (/chat)
GET	查询资源（模型、工具等）

请求头

所有请求必须包含以下头部:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体示例

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "stream": false
}

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "systemPrompt": "你是一个专业的编程助手",
  "messages": [
    {
      "role": "user",
      "content": "解释一下异步编程"
    }
  ],
  "allowedTools": ["bash"],
  "context": {
    "configData": { ... }
  },
  "prune": true,
  "pruneOptions": {
    "maxOutputTokens": 100000,
    "targetTokens": 80000,
    "preserveRecentMessages": 3
  },
  "stream": true
}

响应格式

成功响应（非流式）

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_abc123",
        "role": "assistant",
        "parts": [
          {
            "type": "text",
            "text": "你好！我是一个AI助手..."
          }
        ]
      }
    ],
    "usage": {
      "inputTokens": 15,
      "outputTokens": 45,
      "totalTokens": 60
    },
    "tools": {
      "used": [],
      "skipped": []
    }
  }
}

成功响应（流式）

流式响应使用 Server-Sent Events (SSE) 格式,所有事件以 data: 开头:

data: {"type":"start"}

data: {"type":"start-step"}

data: {"type":"text-start","id":"0"}

data: {"type":"text-delta","id":"0","delta":"你好"}

data: {"type":"text-delta","id":"0","delta":"！"}

data: {"type":"text-end","id":"0"}

data: {"type":"finish-step"}

data: {"type":"finish"}

data: [DONE]

关键点：

所有事件都以 data: 开头,后跟 JSON 对象
事件类型在 JSON 的 type 字段中标识
[DONE] 是字面量文本,不是 JSON
详见流式输出文档

响应头

响应会包含以下有用的头部信息:

头部	说明
X-Correlation-Id	请求关联 ID（所有响应都包含，401 错误除外）
X-Message-Pruned	值为 `"true"`，仅在实际发生消息剪裁时存在
X-Tools-Skipped	跳过的工具名称列表（逗号分隔），仅在使用 `contextStrategy: "skip"` 且有工具被跳过时出现

correlationId 获取方式：

成功响应（200 OK）：只能从响应头 X-Correlation-Id 获取，响应体中不包含
错误响应（400, 403, 500等）：响应体和响应头中都包含
401 认证错误：响应体和响应头都不包含

速率限制未实现：当前 API 未实现速率限制功能，不会返回 X-RateLimit-* 响应头。

消息格式

简单格式（推荐）

最直接的消息格式:

{
  "messages": [
    {
      "role": "user",
      "content": "你好"
    },
    {
      "role": "assistant",
      "content": "你好！有什么我可以帮助你的吗？"
    },
    {
      "role": "user",
      "content": "介绍一下 Python"
    }
  ]
}

AI SDK 格式

兼容 Vercel AI SDK 的消息格式:

{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "你好"
        }
      ]
    },
    {
      "id": "msg_2",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "你好！"
        }
      ]
    }
  ]
}

工具调用消息

花卷智能体 API 使用服务端自动执行模式,工具调用和结果包含在同一个 dynamic-tool part 中:

{
  "messages": [
    {
      "role": "user",
      "content": "候选人问：你们公司地址在哪？"
    },
    {
      "id": "msg_001",
      "role": "assistant",
      "parts": [
        {
          "type": "dynamic-tool",
          "toolName": "zhipin_reply_generator",
          "toolCallId": "call_abc123",
          "state": "output-available",
          "input": {
            "candidate_message": "你们公司地址在哪？",
            "brand": "蜀地源冒菜"
          },
          "output": {
            "reply": "您好！我们蜀地源冒菜位于上海市浦东新区..."
          }
        }
      ]
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "已为您生成专业的回复",
          "state": "done"
        }
      ]
    }
  ]
}

重要：花卷智能体 API 在服务端自动执行工具,单次请求即可完成工具调用和结果处理。详见工具调用文档。

常用参数

model (必需)

AI 模型标识符,格式为 provider/model:

{
  "model": "anthropic/claude-3-7-sonnet-20250219"
}

systemPrompt (可选)

自定义系统提示词:

{
  "systemPrompt": "你是一个专业的 Python 开发导师"
}

stream (可选)

是否启用流式输出,默认 true:

{
  "stream": false  // 禁用流式输出,返回完整 JSON 响应
}

allowedTools (可选)

允许 AI 使用的工具列表:

{
  "allowedTools": ["bash", "zhipin_reply_generator"]
}

prune (可选)

是否启用消息剪裁,默认 false:

{
  "prune": true,
  "pruneOptions": {
    "maxOutputTokens": 100000,
    "targetTokens": 80000,
    "preserveRecentMessages": 3
  }
}

默认值：如果不指定 pruneOptions,系统使用默认配置（targetTokens: 80000, maxOutputTokens: 100000, preserveRecentMessages: 3）。只有在需要更激进的剪裁时才需要自定义这些参数。

context (可选)

为工具提供上下文数据:

{
  "context": {
    "configData": { ... },
    "replyPrompts": { ... }
  }
}

validateOnly (可选)

仅验证参数,不执行实际请求:

{
  "validateOnly": true
}

Token 使用统计

响应中的 usage 字段包含 Token 使用情况:

{
  "usage": {
    "inputTokens": 150,    // 输入 Token 数
    "outputTokens": 450,   // 输出 Token 数
    "totalTokens": 600     // 总 Token 数
  }
}

使用 prune: true 可以显著减少 inputTokens,降低 API 调用成本。

API 概览

Models

Chat

Tools

Configuration

请求格式

HTTP 方法

请求头

请求体示例

响应格式

成功响应（非流式）

成功响应（流式）

响应头

消息格式

简单格式（推荐）

AI SDK 格式

工具调用消息

常用参数

model (必需)

systemPrompt (可选)

stream (可选)

allowedTools (可选)

prune (可选)

context (可选)

validateOnly (可选)

Token 使用统计

下一步

错误码参考

Chat API

​请求格式

​HTTP 方法

​请求头

​请求体示例

​响应格式

​成功响应（非流式）

​成功响应（流式）

​响应头

​消息格式

​简单格式（推荐）

​AI SDK 格式

​工具调用消息

​常用参数

​model (必需)

​systemPrompt (可选)

​stream (可选)

​allowedTools (可选)

​prune (可选)

​context (可选)

​validateOnly (可选)

​Token 使用统计

​下一步

错误码参考

Chat API

请求格式

HTTP 方法

请求头

请求体示例

响应格式

成功响应（非流式）

成功响应（流式）

响应头

消息格式

简单格式（推荐）

AI SDK 格式

工具调用消息

常用参数

model (必需)

systemPrompt (可选)

stream (可选)

allowedTools (可选)

prune (可选)

context (可选)

validateOnly (可选)

Token 使用统计

下一步