XiMind · API Reference (Planning)

XiMind API 规范（规划版）

REST + gRPC + WebSocket + MQTT · 四协议全覆盖

文档编号：D2-P8-TECH-002 · 版本：v1.0(规划) · 发布：2026-05-05

2029 Q2 GA · v1 API 稳定承诺

4

协议类型

v1

规划版本

2029Q2

GA 目标

XiMind API 规范（规划版）

规划版提示

本 API 规范是 XiMind v1.0 GA（2029 Q2 目标） 的规划草案，用于 2027 Q4 立项评审与后续开发启动。具体字段细节、错误码、速率限制将在 v1.0 正式版（立项后迭代）中细化。本文档优先确立API 骨架、协议选型与认证机制。

摘要

XiMind API 规划覆盖 REST API（主流调用）、gRPC API（内部高性能）、WebSocket / SSE（流式响应）、MQTT（车端下发与遥测）四大协议。认证采用 OAuth 2.0 + JWT；计费基于 Token 使用量；开放给 Tier1 / OEM / 独立工程师在订阅套餐内使用。

1. API 总览（规划）

1.1 协议矩阵

协议	主要场景	计划引入
REST	同步请求 / 管理类	v1.0
SSE	流式文本响应	v1.0
WebSocket	代码生成长连接	v1.0
gRPC	内部服务 / 高性能 SDK	v1.0
MQTT 5.0	车端下发 / 遥测	v1.0

1.2 Endpoint 规划清单

路径	方法	说明
`/api/v1/chat`	POST	对话接口（SSE 流式）
`/api/v1/codegen`	POST	代码生成（WS 流式）
`/api/v1/flow`	POST	算法链路编排
`/api/v1/tune`	POST	调音决策推荐
`/api/v1/test/generate`	POST	AI 生成测试用例
`/api/v1/vehicle/dispatch`	-	MQTT 车端下发
`/api/v1/sessions/{id}`	GET	会话历史查询
`/api/v1/auth/token`	POST	OAuth 2.0 令牌
`/api/v1/billing/usage`	GET	Token 使用查询
`/api/v1/billing/plans`	GET	套餐信息
`/api/v1/data/export`	POST	用户数据导出（GDPR）
`/api/v1/data/delete`	DELETE	用户数据删除

2. 认证与授权（规划）

2.1 OAuth 2.0 令牌获取

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_secret>
&scope=chat codegen tune

响应（规划）：

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "chat codegen tune"
}

2.2 请求头（规划）

Authorization: Bearer <access_token>
X-Ximind-Version: v1
X-Session-Id: sess-001   (可选 · 多轮对话场景)
Content-Type: application/json

2.3 权限范围（Scope）

Scope	含义
`chat`	基础对话能力
`codegen`	代码生成（驱动 XiForge）
`flow`	算法流图编排
`tune`	调音决策
`test`	测试用例生成
`vehicle:dispatch`	车端下发（敏感 · 需额外审批）
`admin`	管理 API

3. Chat API（规划）

3.1 请求

POST /api/v1/chat
Accept: text/event-stream

{
  "session_id": "sess-001",
  "messages": [
    { "role": "user", "content": "帮我做一个 8 通道环绕 DSP 方案" }
  ],
  "context": {
    "project_id": "proj-abc",
    "user_role": "algorithm_engineer",
    "vehicle_model": "Model-X 2028"
  },
  "stream": true,
  "max_tokens": 2000,
  "tools_enabled": ["xistudio.*", "xiforge.*"]
}

3.2 流式响应（SSE · 规划）

event: delta
data: {"content": "好的，我先从 XiAlgo 拼装基础链路"}

event: tool_call
data: {"name": "xistudio.create_flow", "args": {"name": "immersive-8ch"}}

event: tool_result
data: {"name": "xistudio.create_flow", "result": {"flow_id": "flow-001"}}

event: delta
data: {"content": "已创建流图 · 接下来生成低频增强算法..."}

event: complete
data: {"session_id": "sess-001", "tokens_used": 2345, "billing_units": 3}

4. CodeGen API（规划）

4.1 请求

POST /api/v1/codegen

{
  "template": "xialgo.fx.eq",
  "description": "低频增强算法 · 60Hz +3dB · Q=1",
  "constraints": {
    "target_dsp": "XiDSP-D2",
    "max_mips": 30,
    "language": "C"
  },
  "reference_project": "proj-abc",
  "stream": true
}

4.2 WebSocket 流式响应（规划）

连接：wss://api.ximind.xisound.com/api/v1/codegen?token=<jwt>

// 服务端推送
{ "type": "thinking", "content": "分析约束：D2 + 30 MIPS..." }
{ "type": "code_chunk", "path": "src/bass_boost.c", "delta": "// Butterworth shelving..." }
{ "type": "code_chunk", "path": "src/bass_boost.c", "delta": "void bass_boost(...){" }
{ "type": "test", "path": "tests/bass_boost.test.yaml", "content": "..." }
{ "type": "complete", "files_generated": 3, "confidence": 0.85, "tokens_used": 5200 }

5. Flow / Tune / Test API（规划）

5.1 流图编排

POST /api/v1/flow

{
  "description": "7.1 环绕 + 低频增强 + 人声清晰",
  "target_dsp": "XiDSP-D2",
  "constraints": { "max_latency_ms": 10 }
}

响应：

{
  "flow_id": "flow-xyz",
  "flow_json": { /* XiStudio 可直接导入的结构 */ },
  "explanation": "选择 EQ × 7 + 低频 Shelving + 人声 Boost...",
  "alternatives": [/* 备选方案 */]
}

5.2 调音决策

POST /api/v1/tune

{
  "measurement_data_url": "s3://xical/measurements/m-123.mat",
  "vehicle_model": "Model-X 2028",
  "customer_preference": "balanced",
  "return_variants": 3
}

响应：返回保守 / 平衡 / 激进三档参数方案 + 每个参数的推理说明。

5.3 测试用例生成

POST /api/v1/test/generate

{
  "module": "xialgo.fx.eq",
  "bug_history_period": "90d",
  "target_case_count": 20,
  "categories": ["boundary", "stress"]
}

6. 车端 MQTT 规范（规划）

6.1 下发 Topic

xisound/vehicle/{vin}/params/apply

6.2 下发 Payload

{
  "version": "1.0",
  "scene": "highway_vocal",
  "xialgo_params": {
    "fx.eq.vocal_boost": { "enabled": true, "gain": 3 }
  },
  "expire_at": "2029-07-01T00:00:00Z",
  "signature": "base64-of-HMAC-SHA256"
}

6.3 遥测 Topic（车端 → 云）

xisound/vehicle/{vin}/telemetry

频率：5 分钟 · 事件触发补报

字段（匿名）：

使用场景统计
用户手动调整频率
匿名声学特征（非音频原始）

6.4 QoS 策略

下发：QoS 1（至少一次）
遥测：QoS 0（可丢）· 关键事件用 QoS 1
保留消息：仅用于车辆上线后获取最近策略

7. 计费 API（规划）

7.1 用量查询

GET /api/v1/billing/usage?period=2029-06

响应（规划）：

{
  "user_id": "u-001",
  "period": "2029-06",
  "plan": "enterprise",
  "tokens_used": 32450000,
  "tokens_included": 50000000,
  "overage_tokens": 0,
  "breakdown": {
    "chat": 12000000,
    "codegen": 15000000,
    "flow": 2000000,
    "tune": 3000000,
    "vehicle_dispatch": 450000
  },
  "estimated_cost_cny": null
}

金额字段

estimated_cost_cny 在规划版不填具体数值 · v1.0 GA 时按 CFO 定稿的费率填充。

7.2 套餐信息

GET /api/v1/billing/plans

返回当前可订阅套餐概要（仅规划框架 · 具体金额以商务报价为准）。

8. 数据合规 API（规划）

POST /api/v1/data/export

行为：24h 内生成用户全部数据的加密 zip 包 · 邮件提醒下载。

8.2 数据删除

DELETE /api/v1/data/delete

行为：

用户对话：立即删除
匿名遥测：脱敏保留（合规必需）
日志：按保留期自然过期
导出物：30 天内清理

9. gRPC（内部 · 规划）

9.1 Proto 规划骨架

syntax = "proto3";
package xisound.ximind.v1;

service XiMind {
  rpc Chat(stream ChatRequest) returns (stream ChatResponse);
  rpc CodeGen(CodeGenRequest) returns (stream CodeChunk);
  rpc Flow(FlowRequest) returns (FlowResponse);
  rpc Tune(TuneRequest) returns (TuneResponse);
  rpc GenerateCases(GenerateCasesRequest) returns (GenerateCasesResponse);
}

message ChatRequest {
  string session_id = 1;
  repeated Message messages = 2;
  Context context = 3;
  bool stream = 4;
  int32 max_tokens = 5;
}

message ChatResponse {
  oneof payload {
    string delta = 1;
    ToolCall tool_call = 2;
    ToolResult tool_result = 3;
    Complete complete = 4;
  }
}

9.2 gRPC 可用性

仅内部服务 + 高级企业客户（性能需求）
Xisound SDK 可选 gRPC 通道（减少 JSON 序列化开销）

10. 错误码（规划）

HTTP	业务码	含义
400	40001	请求参数错误
400	40010	模型不可用（维护中）
401	40100	Token 无效 / 过期
403	40301	Scope 不足
403	40310	配额耗尽（需升级套餐）
404	40400	资源不存在
408	40800	生成超时
429	42900	速率限制
500	50000	内部错误
502	50200	下游工具调用失败
503	50301	服务维护中

11. 速率限制（规划参考）

套餐	QPS	并发会话	长连接
Free	1	1	0
基础	5	3	1
标准	20	10	5
企业	100+	50+	20+

超过速率返回 429 + Header Retry-After。

12. SDK 规划

语言	包名（规划）	维护
Python	`ximind-sdk`	官方（v1.0 GA）
TypeScript	`@xisound/ximind`	官方
Go	`github.com/xisound/ximind-go`	官方
Java	`com.xisound:ximind-java`	社区
C/C++	`libximind`	仅车端使用

13. 变更与兼容性承诺（规划）

v1 稳定至 2031 Q2（v1.0 GA 后至少 2 年）
破坏性变更提前 6 个月预告 · 并提供 v2 并行过渡
新增字段始终向后兼容
弃用字段保留至少 12 个月且带响应头警告

14. 附录

14.1 关联文档

14.2 参考标准

OAuth 2.0 RFC 6749 / JWT RFC 7519
Server-Sent Events（W3C）
MQTT 5.0（ISO/IEC 20922）
Model Context Protocol（MCP）
OpenAI Function Calling 风格

14.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版（规划版）· REST/gRPC/WS/MQTT 四协议骨架

api.md · D2-P8-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 云端与算法团队

XiMind API 规范（规划版）

XiMind API 规范（规划版）

1. API 总览（规划）

1.1 协议矩阵

1.2 Endpoint 规划清单

2. 认证与授权（规划）

2.1 OAuth 2.0 令牌获取

2.2 请求头（规划）

2.3 权限范围（Scope）

3. Chat API（规划）

3.1 请求

3.2 流式响应（SSE · 规划）

4. CodeGen API（规划）

4.1 请求

4.2 WebSocket 流式响应（规划）

5. Flow / Tune / Test API（规划）

5.1 流图编排

5.2 调音决策

5.3 测试用例生成

6. 车端 MQTT 规范（规划）

6.1 下发 Topic

6.2 下发 Payload

6.3 遥测 Topic（车端 → 云）

6.4 QoS 策略

7. 计费 API（规划）

7.1 用量查询

7.2 套餐信息

8. 数据合规 API（规划）

8.1 数据导出（GDPR / 个保法）

8.2 数据删除

9. gRPC（内部 · 规划）

9.1 Proto 规划骨架

9.2 gRPC 可用性

10. 错误码（规划）

11. 速率限制（规划参考）

12. SDK 规划

13. 变更与兼容性承诺（规划）

14. 附录

14.1 关联文档

14.2 参考标准

14.3 版本历史