请求格式
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
}
响应格式
成功响应（非流式）
{
"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": ["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 (可选)
仅验证参数,不执行实际请求:
Token 使用统计
响应中的 usage 字段包含 Token 使用情况:
{
"usage": {
"inputTokens": 150, // 输入 Token 数
"outputTokens": 450, // 输出 Token 数
"totalTokens": 600 // 总 Token 数
}
}
使用 prune: true 可以显著减少 inputTokens,降低 API 调用成本。
下一步
