Appearance
API 概览
平台 API 分为应用服务、组件服务和模型服务三类：
- 应用服务 — 以应用（App）为核心，提供对话、文件操作等运行时接口
- 组件服务 — 提供可被应用复用或独立调用的能力单元（工作流、知识库、三方服务）
- 模型服务 — 提供 OpenAI、Anthropic 标准协议兼容接口，可直接使用对应官方 SDK
公共约定
基地址
所有接口前缀拼接在统一基地址之后，基地址请参考 快速开始。
鉴权请求头
| 参数名 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | 鉴权凭证，格式 Bearer sk_xxx |
应用服务、组件服务和 OpenAI 兼容模型接口使用上述鉴权头；Anthropic 兼容模型接口按协议使用 X-Api-Key: sk_xxx。所有接口的工作空间都由网关根据 API Key 自动识别并注入，调用方无需传入工作空间请求头。
统一响应格式（应用服务与组件服务）
json
{
"code": 200,
"data": {},
"message": "",
"trace_id": "xxx"
}TIP
鉴权类错误（401/403）由网关直接返回，不会进入业务错误清单。详见 错误处理。
模型服务不使用上述业务响应包装，而是返回 OpenAI 或 Anthropic 协议原生结构。
应用服务
应用（App）是 Agent 运行的载体，每个应用绑定一个 Agent 配置。应用服务接口覆盖应用发现、对话交互、文件操作等运行时能力。
| 接口 | 说明 |
|---|---|
| 应用列表 | 分页查询已发布应用，支持类型与关键词筛选 |
| 应用详情 | 获取已发布应用的完整配置（支持按版本号） |
| 应用配置 | 获取应用交互配置（开场白、建议问题、语音等） |
| 会话管理 | 分页查询应用下某用户的会话列表 |
| 消息管理 | 分页查询指定会话的对话历史 |
对话接口按应用类型分列：
| 类型 | 发送消息 | 停止响应 |
|---|---|---|
| Agent | 发送消息 | 停止响应 |
| AgentLite | 发送消息 | 停止响应 |
| ChatFlow | 发送消息 | 停止响应 |
| TextCompletion | 文本生成 | 停止生成 |
文件操作仅适用于 Agent 类型应用：
| 接口 | 说明 |
|---|---|
| 文件操作概览 | Workspace 说明、路径规则、公共约定 |
| 列出目录 | 列出指定目录（非递归） |
| 文件树 | 递归列出文件树 |
| 上传文件 | 普通上传（multipart/form-data） |
| 编辑文件 | 字符串替换编辑 |
| 复制文件 | 复制文件到新路径 |
| 移动文件 | 重命名 / 移动文件 |
| 删除文件 | 删除文件或目录 |
| 创建目录 | 创建目录 |
| 搜索文件 | 按关键词搜索文件名 |
| 下载文件 | 下载单个文件 |
| 下载目录 | 目录打包为 zip 下载 |
| 分片上传 | 大文件分片上传完整流程 |
详见 应用服务说明。
组件服务
组件（Component）是可被应用复用的能力单元，也可通过 OpenAPI 独立调用。
| 组件 | 说明 | 入口 |
|---|---|---|
| 工作流 | 将多步骤逻辑编排为可视化节点流，按节点顺序执行 | 工作流 API |
| 知识库 | 以「知识库 + 数据集 + 分段」组织的检索能力 | 调用说明 · 列表 · 详情 · 检索 |
| 三方服务 | 以「服务 + 工具」两级组织的外部能力对接 | 调用说明 · 服务列表 · 工具列表 · 工具调用 |
详见 组件服务说明。
模型服务
模型服务是 OpenAI 与 Anthropic 标准协议的兼容入口。已有接入代码通常只需替换 Base URL 和平台 API Key，无需重新适配消息、工具调用、流式事件或错误响应结构。
| 兼容协议 | 鉴权方式 | 支持能力 | 入口 |
|---|---|---|---|
| OpenAI | Authorization: Bearer sk_* | 模型发现、Chat Completions、Responses、Embedding、Rerank、语音转写、语音合成 | OpenAI 兼容接口 |
| Anthropic | X-Api-Key: sk_* | 模型发现、Messages、Token 计数、流式 Messages | Anthropic 兼容接口 |
接入前请先通过对应协议的模型列表接口获取公开模型 ID，并根据模型返回的能力选择调用方式。
详见 模型服务说明。