# 模型网关兼容 API

## 1. 边界

兼容网关提供模型推理协议，不是 Hunjing 角色或 Agent Runtime 的替代入口：

```text
https://gateway.<deployment-domain>/openai/v1
https://gateway.<deployment-domain>/anthropic/v1
```

- 它可以接受工具定义并返回 tool call，但不会自动执行客户端工具。
- 它不读写 Character、Memory、Conversation、Community、DeviceGrant、Order 或 PluginInstallation。
- 需要 Hunjing 自动工具循环、多 Agent、审批和持久化时，调用 Native `/v1/runs`。

## 2. OpenAI-compatible 子集

1.0 支持：

```text
GET  /openai/v1/models
POST /openai/v1/responses
POST /openai/v1/chat/completions
POST /openai/v1/embeddings
POST /openai/v1/images/generations
POST /openai/v1/audio/transcriptions
POST /openai/v1/audio/speech
```

认证：

```http
Authorization: Bearer hjk_...
```

流式响应遵循对应 OpenAI SSE 子集；响应返回 `x-request-id` 和 `Hunjing-Request-ID`。未支持的请求字段返回明确 `unsupported_parameter`，不静默忽略会改变语义的字段。

## 3. Anthropic Messages-compatible 子集

1.0 支持：

```text
GET  /anthropic/v1/models
POST /anthropic/v1/messages
POST /anthropic/v1/messages/count_tokens
```

认证和版本：

```http
x-api-key: hjk_...
anthropic-version: <supported-version>
```

OAuth 客户端也可用 `Authorization: Bearer`。网关返回 `request-id` 和 `Hunjing-Request-ID`。`anthropic-beta` 只允许 Adapter 明确支持的值；未知 beta 返回 400，不透传到任意上游。

Messages Tool Use 保留 `tool_use.id` / `tool_result.tool_use_id` 关联；Thinking、cache、usage、stop reason 和 SSE block 必须按所声明兼容版本转换，无法无损映射时拒绝而非伪造。

## 4. 模型名与路由

请求 `model` 优先解析 Hunjing 逻辑模型，例如：

```text
default-chat
fast-chat
reasoning-chat
vision-chat
embedding-default
image-default
speech-default
```

管理员可允许部分上游模型别名，但业务客户端不应依赖 Provider 密钥或 Endpoint。模型配置按固定顺序继承：平台硬边界 → 平台目录 → 用户偏好/BYOK → 角色覆写 → 会话临时选择；上层约束不可被下层覆盖，会话临时选择不持久化，切换模型不得改变角色身份。能力槽（chat、vision、ASR、TTS、image generation、embedding、rerank、safety 等）由逻辑模型声明。`GET models` 只返回当前调用主体获准、在其地区可用的模型和能力。

路由依次考虑：scope、地区、隐私级别、能力、上下文、工具/结构化输出支持、预算、健康、配额和优先级。

## 5. Header 策略

客户端 Header 默认不转发。Adapter 逐 Provider 声明 allowlist，例如：协议版本、项目/组织选择和特性开关。以下字段永不直接转发：

- Hunjing 用户 `Authorization`/Cookie；
- `Hunjing-Diagnostic-Token`；
- 客户端提交的上游 API key；
- 未登记 Provider beta；
- `baggage` 中未批准的键；
- Hop-by-hop Header。

上游凭据由 Secret Store 按 Endpoint 注入。常规日志只记录允许的 Header 名和不可逆摘要，不记录值。

## 6. 重试、故障转移和流提交

```mermaid
stateDiagram-v2
  [*] --> routing
  routing --> requesting
  requesting --> retrying : retryable before visible output
  retrying --> requesting
  requesting --> streaming : first visible event
  requesting --> completed : non-stream success
  streaming --> completed
  streaming --> failed : stream error
  requesting --> failed
```

- 只在首个用户可见事件前对安全的错误重试/故障转移。
- 首个可见事件后禁止切换 Provider 重新生成；当前流继续或明确失败。
- 每个 attempt 单独创建 ModelCall；SDK 自身重试也必须可观测。
- 429 遵循 `Retry-After`；上下文错误、认证、权限和内容拒绝不做同请求盲重试。

## 7. Usage 标准化

标准字段见 `run-observability.md`。关键差异：

- Anthropic `usage.input_tokens` 表示未缓存输入，缓存创建/读取单列；
- OpenAI `usage.input_tokens` 通常含 cached tokens，Adapter 计算未缓存差值；
- Provider 未返回字段存 `null`，`usage_source=unavailable`；
- 平台估算必须标记 `gateway_estimate`，不能冒充 Provider usage；
- 成本由 Hunjing 价格版本计算，不信任上游返回成本；
- 流式 usage 可能只在末尾出现，流异常时允许部分 usage 或 unavailable。

## 8. BYOK 与 Service Account

- 兼容 API 只接受 Hunjing 凭据，不接受用户把 Provider Key 当认证凭据。
- BYOK 通过 Native Secret/Endpoint 配置写入，常规读取只返回掩码和状态。
- Service Account scope 可限制模型、能力、日/月预算、RPM/TPM、IP/来源和有效期。
- 同一个 API key 不跨 PersonalDomain/Workspace 自动访问。

## 9. 错误转换

兼容入口按目标协议返回错误 envelope，同时附：

```http
Hunjing-Request-ID: request_01...
traceparent: 00-...
```

内部保留标准错误和 Provider 原错误类别。不得把 Provider 私密正文、Endpoint、密钥状态或其他租户信息暴露给兼容客户端。