API 参考

这是 Cordy Gateway 数据平面 API 的参考——即你客户端在 8002 端口调用的、兼容 OpenAI 的接口面。可运行示例见客户端集成。

Base URL 与版本

https://<host>:8002/v1

每个推理与账户接口都同时提供 /v1 前缀形式与非 /v1 别名（例如 /v1/chat/completions 与 /chat/completions 是同一处理器）。为兼容 OpenAI SDK，建议使用 /v1 形式。唯一例外是用量分析，它仅在 /v1/account/analytics 提供。

鉴权

以下两种请求头之一携带 wnx_ API 密钥：

Authorization: Bearer wnx_<key>

X-API-Key: wnx_<key>

密钥必须放在请求头中。URL 查询串中的密钥不被接受。网关只保存每个密钥的 SHA-256 哈希。

作用域

每个接口族都需要一个作用域。API 密钥携带一组已授予的作用域；对某接口的请求，若密钥不具备该接口所需作用域，则返回 403 scope_denied。

作用域	授予访问
chat	/v1/chat/completions
completions	/v1/completions
embeddings	/v1/embeddings
models	/v1/models、/v1/models/{id}
balance	/v1/balance、/v1/subscriptions、/v1/packages、/v1/account/analytics
admin	/metrics/*（运维指标）

空作用域列表被视为遗留的默认允许：密钥可访问其拥有者本可使用的任何接口。非空列表则是白名单。签发新密钥时应遵循其所需的最小权限——例如为聊天功能签发一个仅 chat 的密钥。

接口

推理

方法	路径	用途	作用域
POST	/v1/chat/completions	对话补全（流式与非流式）	chat
POST	/v1/completions	遗留文本补全（流式与非流式）	completions
POST	/v1/embeddings	创建嵌入	embeddings

模型

方法	路径	用途	作用域
GET	/v1/models	列出该密钥可用的公开模型	models
GET	/v1/models/{id}	按 slug 获取单个公开模型	models

账户

方法	路径	用途	作用域
GET	/v1/balance	令牌配额与预付信用余额	balance
GET	/v1/subscriptions	订阅等级、套餐与状态	balance
GET	/v1/packages	只读平台套餐目录	balance
GET	/v1/account/analytics?period_days=	自助用量/时延/成本汇总	balance

健康（公开，无需密钥）

方法	路径	用途
GET	/health	存活——进程在运行（200）
GET	/v1/health	同 /health
GET	/status	同 /health
GET	/health/live	Kubernetes 风格存活探针
GET	/health/ready	就绪——此刻能否服务对话/嵌入（200/503）
GET	/health/providers	各供应商健康明细（200/503）
GET	/health/detailed	能力、供应商与许可证诊断

指标（运维）

方法	路径	用途	访问
GET	/metrics/	服务聚合指标（JSON）	admin 作用域
GET	/metrics/providers	各供应商指标（JSON）	admin 作用域
GET	/metrics/providers/{provider}	单个供应商指标（JSON）	admin 作用域
GET	/metrics/cost	成本估算（JSON）	admin 作用域
GET	/metrics/prometheus	Prometheus 文本暴露	令牌与/或 CIDR 门禁

/metrics/prometheus 不属于 API 密钥接口面。在生产环境中，除非调用方出示 GATEWAY_METRICS_TOKEN bearer 令牌，或来自 GATEWAY_METRICS_ALLOWED_CIDRS 中的 CIDR，否则被拒绝。见部署。

请求与响应结构

推理接口遵循 OpenAI 的 schema。主要请求字段：

POST /v1/chat/completions

字段	类型	说明
model	string	必填。公开模型 slug。
messages	array	必填、非空。必须至少包含一条 user 消息。
stream	boolean	默认 false。true 返回 SSE。
temperature	number	0–2，默认 1。
max_tokens	integer	可选，> 0。
top_p	number	0–1，默认 1。
n	integer	≥ 1，默认 1。
stop	string 或 array	可选。
presence_penalty	number	-2–2，默认 0。
frequency_penalty	number	-2–2，默认 0。
tools	array	可选。函数/工具定义。
tool_choice	string 或 object	可选。需要非空的 tools。
response_format	object	可选。
seed、logit_bias、user	—	可选，OpenAI 标准。

非流式响应是标准的 chat.completion 对象，含 choices、usage 与可观测性请求头（X-Channel-Id、X-Provider、X-Failover-Count、X-Routing-Overhead-Ms）。流式响应是 text/event-stream 的 chat.completion.chunk 事件流，以 [DONE] 结束。

消息 content 必须为文本——一个字符串，或一个 {"type":"text","text":"..."} 分片数组。非文本分片会被拒绝。见客户端集成。

POST /v1/embeddings

字段	类型	说明
model	string	必填。公开模型 slug。
input	string 或 array	必填、非空。
encoding_format	string	可选：float 或 base64。
user	string	可选。

POST /v1/completions（遗留）

字段	类型	说明
model	string	必填。
prompt	string 或 array	单个字符串，或单元素数组。不支持多元素 prompt 数组。
以及采样字段	—	max_tokens、temperature、top_p、n、stream、stop、惩罚项、user。

错误格式

所有错误使用 OpenAI 风格的信封：

{
  "error": {
    "type": "authentication_error",
    "message": "API key has been revoked.",
    "code": "revoked_api_key",
    "request_id": "…"
  }
}

code 是可用于分支判断的稳定字符串；type 归类相关错误；request_id 与服务端日志关联。部分错误会附加字段（例如 scope_denied 上的 required_scope 与 granted_scopes，或校验错误上的 details）。

错误表

状态	type	code	何时发生
400	invalid_request_error	validation_error	请求体未通过 schema 校验（字段错误、messages 为空、无 user 轮次等）。
400	invalid_request_error	malformed_json	请求体不是有效 JSON。
400	invalid_request_error	invalid_function_call_payload	tools / tool_choice 格式错误。
401	authentication_error	missing_api_key	请求中无密钥。
401	authentication_error	invalid_api_key	密钥无法识别。
401	authentication_error	revoked_api_key	密钥已吊销——不要重试，不要重新鉴权。
401	authentication_error	inactive_api_key	密钥未激活——管理员可重新激活。
401	authentication_error	expired_api_key	密钥已过期。
401	authentication_error	account_not_active	所属账户未激活。
402	insufficient_credits	insufficient_credits	账户预付信用耗尽——充值，勿重试。
403	permission_error	scope_denied	密钥缺少该接口的作用域。
403	permission_error	metrics_forbidden	Prometheus 抓取缺少有效令牌 / 允许的 CIDR。
404	model_not_found	model_not_found	模型 slug 未知或对该密钥不可用。
413	invalid_request_error	payload_too_large	请求体超过 GATEWAY_MAX_BODY_BYTES（默认 10 MiB）。
429	rate_limit_error	quota_exceeded	月度令牌配额已耗尽。
429	rate_limit_error	rate_limit_exceeded	超出每密钥每分钟请求上限（含 Retry-After）。
500	api_error	internal_error	意外的服务端错误。
503	service_unavailable	auth_service_unavailable	瞬时的鉴权基础设施故障（含 Retry-After）——重试。

如何应对

• 可重试： 429（在 Retry-After 之后）、503。退避后重试。
• 原样不可重试： 400、401、402、403、404——先修正请求、密钥、信用、作用域或模型。
• 402 专门说明： 停止并充值信用；重试无济于事。

流式错误

在流式响应中，流已打开之后发生的上游失败，会作为带内的 SSE error 事件（带字符串 code）投递，随后是 [DONE]。流打开之前的失败（路由、预算、连接）会作为带相应状态码的普通 JSON 错误返回，且绝不打开 SSE 流。若上游在没有 finish reason 的情况下关闭，网关还会发出一个 stream_interrupted 事件。

后续步骤

• 客户端集成——SDK 用法与请求头。
• 配置——此处引用的环境变量。