认证与请求约定
Agent client 使用的 API Key、Base URL 和请求 Header。
API Key
Bearer 认证，每个请求携带：
key 的前缀内嵌区域（如 sk-row-...），请使用与 key 区域匹配的 API 主机。
在控制台 console.beatra.ai → Developer → API keys 创建。secret 仅创建时展示一次；轮换时新建 key → 切换部署 → 吊销旧 key（新旧可并行生效）。
Console 登录用于真人管理账户。API Key 用于 Agent、服务、MCP 适配器和后台任务。 不要把 Console session cookie 嵌入 Agent runtime。
Base URL
请求头
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <api_key> |
Content-Type | 是 | application/json（文件上传除外） |
Idempotency-Key | 强烈建议 | 创建类 POST 携带；重试用同一个 key。去重是持久的：同一 key 始终解析到同一个任务 |
X-Request-Id | 可选 | 响应原样回显；排障时的最快检索键 |
幂等规则
- 同一逻辑操作的重试 → 同一个
Idempotency-Key； - 用户意图变了 → 换新 key；
- 同 key 不同 body →
409 idempotency_conflict。
限流响应头与 429 处理见限流。