BYOK API 参考
BYOK Key CRUD 操作的 REST API 参考。
完整的端点参考（含 schema、请求/响应示例及可交互调试面板）请访问英文版：
操作列表
| Method | Path | 所需 Scope | 说明 |
|---|---|---|---|
GET | /api/v1/projects/{project_id}/byok-keys | read:byok | 列出项目所有 Key（掩码） |
PUT | /api/v1/projects/{project_id}/byok-keys/{provider} | write:byok | 设置或轮换 Key（保存前先探针；坏 Key 返回 400 invalid_api_key） |
PATCH | /api/v1/projects/{project_id}/byok-keys/{provider} | write:byok | 不换 Key，只切 is_active |
DELETE | /api/v1/projects/{project_id}/byok-keys/{provider} | write:byok | 硬删除该 Key |
POST | /api/v1/projects/{project_id}/byok-keys/{provider}/test | write:byok | 用已存 Key 对上游再探一次 |
provider 有效值: openai | gemini | xai | openrouter
BYOKKey 对象
| 字段 | 类型 | 说明 |
|---|---|---|
provider | string | 提供商 ID |
api_key_prefix | string | Key 前几个字符（用于识别；原 Key 不会回传） |
is_active | bool | Key 是否启用 |
health_status | string | healthy / unhealthy / unknown |
last_health_error | string | null | 最近一次健康检查的错误信息 |
last_health_check_at | string | null | 最近一次健康检查时间（ISO 8601） |
last_used_at | string | null | 最近使用时间（ISO 8601） |
updated_at | string | 最后更新时间（ISO 8601） |
响应格式
GET 成功响应:
{
"keys": [BYOKKey, ...]
}完整规范（OpenAPI schema、在线调试面板）请参阅英文版参考。