调用与端点
/v1 调用使用虚拟密钥鉴权,在管理台「虚拟密钥」页面创建,说明见 虚拟密钥。调用前需要先在 配置中心 配好提供商和模型,再在 路由 挂上逻辑名。
OpenAI 兼容(推荐)
日常使用走 /v1/chat/completions,可路由到任意协议的模型:
curl http://127.0.0.1:17777/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer vk-xxxx" \
-d '{"model": "glm", "messages": [{"role": "user", "content": "Hi"}]}'
model 填管理台里配置的逻辑路由名。请求 glm,落地到路由背后任意真实模型。
流式请求加 "stream": true,网关按 SSE 透传。开启运行设置里的自动注入后,会补 stream_options.include_usage,方便记录精确 token。
端点一览
| 端点 | 协议 | 使用场景 |
|---|---|---|
/v1/chat/completions | OpenAI | 日常使用,统一接口,自动转换 |
/v1/messages | Anthropic | 需要 thinking 等特性 |
/v1/responses | OpenAI Responses | 需要 reasoning_content |
/v1/gemini:generateContent | Gemini | 需要 Gemini 独有参数 |
/v1/gemini:streamGenerateContent | Gemini | Gemini 流式生成 |
/v1/models | OpenAI | 列出当前可用的逻辑路由与 provider/model |
原生端点只路由到同协议的模型。跨协议转换时,Anthropic 的 thinking 会以 reasoning_content 透出。完整字段映射与限制见 协议转换。
原生协议直通
需要厂商独有参数时,用原生端点,零损耗、参数完整:
# Anthropic 原生,仅路由到 protocol=messages 的模型
curl http://127.0.0.1:17777/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer vk-xxxx" \
-d '{"model": "claude", "messages": [{"role": "user", "content": "Hi"}], "thinking": {"type": "enabled"}}'
# Gemini 原生,仅路由到 protocol=gemini 的模型
curl http://127.0.0.1:17777/v1/gemini:generateContent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer vk-xxxx" \
-d '{"model": "gemini", "contents": [{"role": "user", "parts": [{"text": "Hi"}]}]}'
provider/model 直达
逻辑路由未命中时,model 也支持 提供商名/模型名,跳过加权选择、锁定某个物理模型:
curl http://127.0.0.1:17777/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer vk-xxxx" \
-d '{"model": "openrouter/anthropic/claude-3.5-sonnet", "messages": [{"role": "user", "content": "Hi"}]}'
规则:
- 仅在逻辑路由未命中时生效;若存在与输入完全同名的路由,仍然走路由池
- 仅用第一个
/分割,模型名里可以再含/ /v1/models会把所有物理模型以provider/model形式一并列出- 配置了授权路由的受限虚拟密钥无法用该语法绕过白名单
查看可用模型
curl http://127.0.0.1:17777/v1/models \
-H "Authorization: Bearer vk-xxxx"
返回逻辑路由名,以及 provider/model 形式的物理模型。受限虚拟密钥只看到授权范围内的逻辑路由。
错误格式
网关自身的错误统一返回 OpenAI error envelope:
{
"error": {
"message": "monthly budget exceeded",
"type": "budget_exceeded",
"code": "budget_exceeded"
}
}
上游错误会尽量保留原始状态码与响应体;完整内容记录在请求日志的 error_body 字段(截断至 2KB)。
多模态与 MCP
Embedding、Rerank、生图、语音、视频和 MCP 工具网关的调用方式见 多模态与 MCP。