API 参考: AI

AI 调用端点。对话、流式响应、工具调用、数据分析。

AI 对话（同步）

发送消息，AI 处理后返回完整响应。

POST /v1/ai/chat

请求体

字段	类型	必填	说明
message	string	是	用户消息内容
model	string	否	模型标识符。默认 claude-sonnet-4-20250514，可选 claude-opus-4-20250514、qwen:qwen3-235b-a22b 等
systemPrompt	string	否	系统提示词，定义 AI 角色。默认为通用中文助手
appContext	string	否	应用上下文 ID，限定 AI 使用的工具集
tools	array	否	额外的工具定义
conversationId	string	否	会话 ID，用于多轮对话

请求示例

curl -X POST https://api.invoratec.cn/v1/ai/chat \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析本月能耗数据",
    "model": "claude-sonnet-4-20250514",
    "systemPrompt": "你是专业的能源管理顾问"
  }'

响应

{
  "response": "根据系统数据，本月能耗总计 125,000 kWh...",
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "inputTokens": 50,
    "outputTokens": 200
  }
}

响应字段

字段	类型	说明
response	string	AI 回复文本
model	string	实际使用的模型
usage.inputTokens	integer	输入 Token 数
usage.outputTokens	integer	输出 Token 数

错误

状态码	说明
400	message 缺失，或未配置 AI 模型 API Key
401	API Key 无效
500	AI 调用失败

---

AI 对话（流式 SSE）

使用 Server-Sent Events 流式返回 AI 响应。适合需要实时显示的交互场景。

POST /v1/ai/chat/stream

请求体

字段	类型	必填	说明
message	string	是	用户消息内容
model	string	否	模型标识符
systemPrompt	string	否	系统提示词

请求示例

curl -X POST https://api.invoratec.cn/v1/ai/chat/stream \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "详细解释 RAG 技术原理"
  }'

响应

响应头：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

SSE 事件流：

data: {"type":"stream","text":"RAG"}

data: {"type":"stream","text":"（检索增强生成）"}

data: {"type":"stream","text":"是一种结合了检索"}

...

data: {"type":"done","usage":{"input_tokens":30,"output_tokens":500}}

SSE 事件类型

type	说明	额外字段
stream	文本片段	text: 文本内容
done	完成	usage: Token 用量
error	错误	message: 错误信息

错误

状态码	说明
400	message 缺失，或未配置 AI 模型 API Key
401	API Key 无效

---

直接调用工具

不经过 AI 推理，直接执行一个已注册的工具。

POST /v1/ai/tool-call

权限要求： write

请求体

字段	类型	必填	说明
tool	string	是	工具名称
input	object	否	传递给工具的输入参数

请求示例

curl -X POST https://api.invoratec.cn/v1/ai/tool-call \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "hr_get_dashboard",
    "input": {}
  }'

响应（成功）

{
  "status": "success",
  "result": {
    "employees": 150,
    "departments": 12,
    "avg_attendance_rate": 0.96
  }
}

响应（工具未找到）

{
  "error": {
    "message": "工具 'unknown_tool' 未找到或需要桌面代理执行"
  }
}

错误

状态码	说明
400	tool 缺失
403	缺少 write 权限
404	工具未找到或需要桌面代理
500	执行错误

---

数据分析

提交结构化数据和分析提示，AI 返回分析结果。使用 claude-sonnet-4-20250514 模型，最大输出 8192 Token。

POST /v1/ai/analyze

请求体

字段	类型	必填	说明
data	object/string	是	待分析的数据（对象或字符串）
prompt	string	是	分析提示/指令
outputFormat	string	否	输出格式：text（默认）、markdown、json

请求示例

curl -X POST https://api.invoratec.cn/v1/ai/analyze \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "sales": [100, 200, 150, 300],
      "months": ["1月", "2月", "3月", "4月"]
    },
    "prompt": "分析销售趋势，给出预测",
    "outputFormat": "markdown"
  }'

响应

{
  "analysis": "## 销售趋势分析\n\n| 月份 | 销售额 | 环比增长 |\n|------|--------|--------|\n| 1月 | 100 | - |\n| 2月 | 200 | +100% |\n| 3月 | 150 | -25% |\n| 4月 | 300 | +100% |\n\n### 趋势判断\n整体呈上升趋势...",
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "inputTokens": 120,
    "outputTokens": 500
  }
}

响应字段

字段	类型	说明
analysis	string	AI 分析结果文本
model	string	使用的模型
usage.inputTokens	integer	输入 Token 数
usage.outputTokens	integer	输出 Token 数

错误

状态码	说明
400	data 或 prompt 缺失，或未配置 AI 模型 API Key
500	AI 调用失败