入口与关键约定
- Base URL:
https://apemind.ai/v1(私有化部署替换为https://<APEMIND_HOST>/v1)。 - 认证头:
Authorization: Bearer <API_KEY>(组织服务账号 API Key 或成员 API Key)。 - 必填定位参数:在查询参数中显式传入
bot_id=<AGENT_ID>(历史参数名仍为bot_id,填入目标 Agent ID),可选chat_id(延续已有会话)和language(默认zh-CN)。 model字段:传"apemind"即可,实际推理模型由目标 Agent 的声明式配置决定。
Python OpenAI SDK 示例
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APEMIND_API_KEY"],
base_url=f"{os.environ['APEMIND_BASE_URL']}/v1",
)
# 流式调用(同步调用改为 stream=False 并读取 response.choices[0].message.content)
stream = client.chat.completions.create(
model="apemind",
messages=[{"role": "user", "content": "请说明合同解除条件。"}],
stream=True,
extra_query={
"bot_id": os.environ["APEMIND_AGENT_ID"],
"language": "zh-CN",
},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
TypeScript / Node OpenAI SDK 示例
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.APEMIND_API_KEY,
baseURL: `${process.env.APEMIND_BASE_URL}/v1`,
});
const stream = await client.chat.completions.create(
{
model: "apemind",
messages: [{ role: "user", content: "请说明合同解除条件。" }],
stream: true,
},
{
query: {
bot_id: process.env.APEMIND_AGENT_ID!,
language: "zh-CN",
},
},
);
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}
多轮连续对话
省略 chat_id 时,服务端为每次请求创建临时会话。需要复用 ApeMind 持久化多轮上下文时,先调用 POST /api/v2/bots/{agent_id}/chats 获取 chat_id,再把同一个 chat_id 放到后续调用的查询参数里:
curl --fail-with-body \
-X POST "${APEMIND_BASE_URL}/v1/chat/completions?bot_id=${APEMIND_AGENT_ID}&chat_id=${CHAT_ID}&language=zh-CN" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "apemind",
"messages": [{"role": "user", "content": "继续说明违约责任。"}],
"stream": false
}'
同一条业务链路不要混用临时会话和显式 chat_id 持久会话。
错误处理与能力边界
- 同时检查 HTTP 状态码与
error字段:除401/422外,部分兼容路径会在200响应中返回{"error": {"message", "type", "code"}},客户端应显式校验。记录x-request-id响应头以便排障。 - 输出范围:只提供标准 Chat Completions 最终
assistant文本、finish_reason和usage,不包含工具轨迹、结构化句级引用或交互确认钩子(consent/elicit/ask_user)。 - 何时切换其他入口:
- 需要完整
parts[]证据引用、附件沙箱、工具确认或 PDF 导出时,使用对话与异步 Turn 集成(其中 API Key 走快照轮询,浏览器会话与 Desktop OAuth 可直接订阅原生 SSE 事件流); - 需要让自有智能体直接检索 ApeMind 知识库时,接入MCP Server。
- 需要完整