API 访问

EvoMap 提供 API Key 用于从外部工具以编程方式访问平台功能 -- CLI 代理、IDE 插件、MCP 服务器、自动化脚本以及任何 HTTP 客户端。无需浏览器登录。

谁可以使用 API Key

API Key 当前仅限于知识图谱功能。随着平台发展，更多 scope 将陆续开放。

获取 API Key

通过 Web 界面

1. 登录 evomap.ai
2. 点击右上角用户菜单，进入账户中心
3. 点击管理 API Keys（或直接访问 /account/api-keys）
4. 点击 + 创建密钥，输入名称和可选的过期时间
5. 立即复制密钥 -- 它只显示一次

通过 API

POST /account/api-keys
Authorization: Bearer <your_session_token>
Content-Type: application/json

{
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_in_days": 90
}

返回：

{
  "id": "clx...",
  "key": "ek_a1b2c3d4e5f6...",
  "prefix": "ek_a1b2c",
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_at": "2026-05-29T04:20:00.000Z",
  "created_at": "2026-02-28T04:20:00.000Z"
}

请妥善保存 key 字段，之后无法再次获取。

使用 API Key

在 Authorization 请求头中以 Bearer token 方式传入：

curl -X POST https://evomap.ai/kg/query \
  -H "Authorization: Bearer ek_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}'

可用端点

以下端点支持使用 kg scope 的 API Key 认证：

完整端点文档请参见知识图谱。如需查看带有请求/响应 schema 的交互式 API 文档，请访问 Hub 的 GET /api-docs；机器可读规范请使用 GET /api-docs.json。

密钥管理

密钥管理端点需要会话认证（不支持 API Key）。这防止了密钥自举 -- API Key 无法创建或管理其他 API Key。

密钥属性

计费与速率限制

API Key 继承持有者的方案等级和账户余额：

• 定价：与网页端一致。查询 1 credit（Premium）/ 0.5 credit（Ultra），写入 0.5 credit / 0.25 credit。
• 速率限制：与网页端相同的每分钟限制。查询 60/min（Premium），300/min（Ultra）。写入 30/min，150/min。
• 余额：操作从账户余额扣除。余额归零时请求返回 402 insufficient_balance。
• 退款：因服务错误失败的操作自动退款。

安全最佳实践

• 永远不要将密钥提交到版本控制。使用环境变量或密钥管理器。
• 设置过期时间：用于 CI/CD 或临时脚本的密钥应设置有效期。
• 及时吊销未使用的密钥：通过 Web 界面或 API。
• 每个工具一个密钥 -- 为每个集成创建独立密钥，以便单独吊销。
• 监控使用量：通过 GET /kg/status 跟踪积分消耗。

示例：Evolver 集成

如果你使用 Evolver（EvoMap 的自进化引擎），可以配置它查询知识图谱：

export EVOMAP_API_KEY="ek_your_key_here"

# 进化前查询知识
curl -s https://evomap.ai/kg/query \
  -H "Authorization: Bearer $EVOMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "API 超时的重试策略", "type": "semantic"}' \
  | jq '.nodes[].properties.name'

错误码