OpenAI 兼容 API

/v1 endpoints、chat completions、请求标头、错误代码、streaming 和缓存标头。

Gateway 在 base URL /v1 下提供兼容 OpenAI 的 endpoints。OpenAI 客户端可连接 gateway，而不是直接连接模型提供方。

Endpoints#

方法和路径	用途
POST /v1/chat/completions	OpenAI 风格 chat completions，可原生处理或经 facade 转到 Anthropic backend。
POST /v1/responses	Responses API relay，适用于新 SDK；转换为 chat 并使用相同 pipeline。
POST /v1/embeddings	OpenAI 风格 embeddings，路由到配置的提供方。
GET /v1/models	列出已注册模型。

支持常见 OpenAI 兼容路由别名，现有 SDK 和工具通常无需修改。

Endpoint Gateway（图像、音频、文件、fine-tuning 和批处理）#

除 chat、messages 和 embeddings 外，还可开放其他兼容 OpenAI 的接口。它们默认关闭；关闭的 endpoint 返回 404 endpoint_disabled。在 Settings -> Endpoint Gateway 启用：

接口	开关	行为
/v1/images/generations、edits、variations	images	按 chat prompt 检查、屏蔽和压缩 JSON prompt；检查响应元数据，并使用受检查控制的缓存。
/v1/audio/speech	audio	将输入作为 chat prompt 检查后转发。
/v1/audio/transcriptions、translations	passthrough	受治理的 multipart 透传，注入 key 并审计。
/v1/files	files	解码并检查文本文件；阻止违规上传，二进制文件直接透传。
/v1/fine_tuning/jobs、/v1/batches	passthrough	受治理透传，注入 key 并审计。

不分析媒体像素或波形，只检查附带文本。每个请求在交易日志中记录 endpoint 类型。

请求标头

标头	用途
Authorization: Bearer [key]	按认证模式用于客户端认证和/或 upstream key。
X-Agent-ID	跟踪、路由、风险和缓存范围所用的 Agent 身份。
X-User-Id	用户身份；优先使用已认证 token 的 sub claim。
x-aifw-cache-refresh	跳过本次缓存查询，但仍允许写入。

标准请求

POST /v1/chat/completions
{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false
}

字段	说明
model	可选；省略时使用配置的默认模型。
messages	标准消息；tool_calls/tool 序列逐字节透传。
stream	true 使用当前有效的 buffered 或 live 模式。

错误代码

被阻止或拒绝的请求返回 HTTP 400 和结构化错误：

{
  "error": {
    "message": "The transaction was intercepted and blocked by corporate AI security policy.",
    "type": "guardrail_violation",
    "code": "prompt_injection_detected",
    "details": { "policy_id": "BUILTIN-JAILBREAK", "timestamp": "2025-01-15T10:00:00Z" }
  }
}

代码	含义
guardrail_violation	被内置或自定义规则阻止；详情含策略 ID。
prompt_injection_detected	命中 jailbreak 或提示注入规则。
semantic_rule_violation:rule	语义分数超过阻止阈值。
model_disabled	已注册模型处于禁用状态。
model_not_registered	严格模式开启，但模型未注册。
backend_not_configured	解析出的模型没有配置 backend URL。
default_policy_block	没有规则匹配，默认操作为 block。

被阻止的响应包含 X-Gateway-Security: Violated。认证失败返回 401；未知路由返回 404。

Streaming#

stream: true 使用类似 OpenAI 的 server-sent events，并以 data: [DONE] 结束。

buffered（默认）：先扫描完整响应；违规会在交付 token 前返回 400。
stream：实时传输 token；中途违规以 guardrail_violation 结束 SSE。已发送的 token 无法撤回。

缓存

配置缓存范围后，completion cache 可返回响应。命中会记录，缓存 body 重放时仍经过响应检查。

OpenAI 兼容 API

Endpoints#

Endpoint Gateway（图像、音频、文件、fine-tuning 和批处理）#

请求标头

标准请求

错误代码

Streaming#

缓存

后续阅读

后续阅读