Base URL 与区域
Bird API 由区域主机提供服务。每个请求直接发送到存储您组织数据的区域。API 不提供全局数据平面 URL。
| Base URL | 服务范围 |
|---|---|
| https://us1.platform.bird.com | us1 中组织的所有 /v1 数据平面端点 |
| https://eu1.platform.bird.com | eu1 中组织的所有 /v1 数据平面端点 |
| https://platform.bird.com | 仅限与区域无关的接口：/v1/auth 和 /v1/admin |
区域代码由两个小写字母（表示地理位置）加一个实例数字组成（^[a-z]{2}[0-9]+$）。us1 和 eu1 已上线；该命名方案可在无需客户端更改的情况下容纳未来的区域，例如 us2 和 ap1。
组织绑定到一个区域
每个组织在注册时被分配一个区域。区域根据您的位置自动检测，可在确认前更改，在 v1 中不可变。工作区、API 密钥、消息、收件人数据和事件日志都保留在该区域内，绝不会跨区域复制。这种隔离支持数据驻留承诺，例如 EU 组织的数据存储和处理均在 EU 内完成。
只有身份验证和账户管理（/v1/auth、/v1/admin）使用全局复制的数据，因此它们由非区域主机 platform.bird.com 提供服务。
路由：密钥决定主机
发送到错误区域的请求会被拒绝并返回 421 Misdirected Request，而不是被转发。错误消息中会指明正确的主机：
代码示例
{
"type": "misdirected_error",
"code": "E01010",
"name": "MisdirectedRequest",
"message": "Organization belongs to region eu1 but this request reached us1. Send the request to eu1.platform.bird.com.",
"request_id": "..."
}每个 API 响应还带有一个 X-Bird-Region 请求头，指明服务该请求的区域，可用于确认请求实际到达了哪个区域。
SDK 和 CLI 自动路由
官方 SDK 和 CLI 会从密钥前缀解析区域并选择主机。使用 bk_eu1_... 密钥时，所有调用无需配置即可发送到 eu1.platform.bird.com。您可以为测试环境覆盖推断的主机：在 TypeScript SDK 中使用 baseUrl，在 Go SDK 中使用 option.WithBaseURL，或在 CLI 上使用 --base-url（或 BIRD_API_URL）。