# 认证与请求约定
> 给程序调用用的 API Key、接口地址和请求头。

## API Key

Bearer 认证，每个请求携带：

```text
Authorization: Bearer sk-<region>-...
```

钥匙的前缀里写着地区，例如 `sk-row-...`。`row` 是这把钥匙所属的地区，它决定请求发往哪一台接口。`row` 对应 `https://api.beatra.ai/v1`。地区对不上时，请求会被拒绝。
在控制台 [console.beatra.ai](https://console.beatra.ai) 打开 **开发 → API Key** 创建。密钥只在创建时显示一次。更换时：新建一把 → 把程序改成用新的 → 再作废旧的（新旧可以同时有效）。

在控制台登录，是给人管理账户用的。API Key 给程序、服务和后台任务用。不要把控制台的登录状态放进自动运行的程序里。

## Base URL

```text
https://api.beatra.ai/v1
```

## 请求头

| 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 处理见[限流](https://docs.beatra.ai/zh/docs/mechanisms/rate-limits)。