跳到主要内容

Session API

Xiaohe Agent 提供 REST Session API，用于以程序方式驱动 Agent 工作流。该 API 托管真实 CLI 后端（如 Claude / Kimi），不是另一套独立 Agent SDK。

用 OS 服务生命周期命令启动本机控制面：

xiaohe server install
xiaohe server start

本机默认地址通常为：http://127.0.0.1:8110。托管 Session Web：https://agent.xiaohe.team（见 下载）。

鉴权​

开启鉴权后，每个 /v1/* 请求（健康检查与公开 UI 路径除外）需要 Bearer token：

Authorization: Bearer <api-key|access-jwt>

在控制面主机上签发与管理密钥：

xiaohe server pair        # 一次性：签发密钥，打印 apiBase + workspace_path
xiaohe keys issue --tenant local --label mac
xiaohe keys list
xiaohe keys revoke <id|prefix>

EventSource / SSE 无法带 Bearer 头时，将密钥作为查询参数：

GET /v1/sessions/{id}/events?access_token=<key>&after=0&follow=true

核心接口​

方法路径作用
POST/v1/sessions创建托管会话
GET/v1/sessions/{id}会话状态
POST/v1/sessions/{id}/messages发送用户消息
GET/v1/sessions/{id}/eventsSSE 事件流
POST/v1/sessions/{id}/approvals批准 / 拒绝待确认动作
POST/v1/sessions/{id}/cancel取消生成中的回复
DELETE/v1/sessions/{id}结束会话
GET/v1/me调用方身份 / 工作区提示
GET/PUT/v1/provider列出 / 切换 Claude LLM provider
GET/PUT/v1/voice/provider列出 / 切换 TTS/STT provider

创建会话​

POST /v1/sessions

{
  "tenant_id": "demo",
  "backend": "claude",
  "skill_ids": ["demo.echo"],
  "message": "optional first turn",
  "workspace_path": "/absolute/path/to/project",
  "persistent": false
}
  • backends — claude（默认）| kimi | codex | cursor | fake（本地测试）。会话代理真实 CLI；claude 使用 Agent SDK 做 token 流式与跨回合 --resume。
  • workspace_path — 调用方项目的绝对路径作为工作目录。省略则使用沙箱工作区。
  • persistent — 为会话保持长生命周期主机进程（而非每回合起停）。
  • skill_ids — 限制会话可加载的产品 skills。

消息与事件​

用 POST /v1/sessions/{id}/messages 发送回合：

{"content": "Hello"}

进度经 SSE 到达——用 after=<last_event_seq> 重连以续传：

GET /v1/sessions/{id}/events?after=0&follow=true

附件​

上传文件上限 50 MiB：

  • POST /v1/sessions/{id}/attachments — multipart 字段 file → {id, name, mime, size, kind}
  • GET /v1/sessions/{id}/attachments — 列出元数据
  • GET /v1/sessions/{id}/attachments/{att_id} — 下载字节

入站附件以本机路径追加到提示（agent Read / 图片工具）。

转写​

GET /v1/sessions/{id}/messages 返回稳定聊天气泡（UI 重开的真相源）。可选分页（最新优先窗口）：limit（1–500）、before_created_at + before_msg_id keyset 游标；省略 limit 返回全文。

批准（人在回路）​

POST /v1/sessions/{id}/approvals

{"approval_id": "...", "approved": true, "note": ""}

当 Agent 需要决策时，会话进入 waiting_approval，并在 SSE 上发出 approval_required 事件。

工作区​

  • GET /v1/me — 调用方建议的 workspace_path
  • GET /v1/workspaces — 列出该密钥租户下已注册工作区
  • POST /v1/workspaces — 确保 / 注册工作区

模型网关​

Xiaohe 还提供统一模型网关——一把 API Key，经单一 Anthropic 兼容端点访问 DeepSeek、Kimi 与 Claude。客户端无需逐家开户或 SDK。

Base: https://api.xiaohe.team/v1   (Anthropic Messages API)
方法路径作用
POST/v1/messages聊天补全（Anthropic Messages API）
GET/v1/models列出路由模型

将网关密钥作为 x-api-key（或 Authorization: Bearer …），选择任一路由模型，网关转发到配置的 provider：

{
  "model": "deepseek-v4-pro",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello"}]
}

路由模型包含 DeepSeek（deepseek-v4-pro、deepseek-chat、deepseek-reasoner）、Kimi（kimi-k2.6、kimi-for-coding）与 Anthropic（claude-opus-5、claude-sonnet-5、claude-haiku-4-5、claude-fable-5）。按请求计量用量，按 token 计费——费用由内置模型价目表估算。

TTS / STT​

托管 Session API 提供语音：

  • POST /v1/tts — 文本 → 音频（audio/mpeg）。Body { "text", "voice", "tenant_id" }。音色：zh_male_m191_uranus_bigtts（经典男声）、zh_female_xiaohe_uranus_bigtts（经典女声）、ICL_uranus_zh_female_yuanqitianmei_tob（阳光甜妹）。最多 2000 字。
  • POST /v1/stt — multipart file → {"text": "..."}（豆包 flash ASR）。

相关​