跳到主要内容

调用与端点

/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/completionsOpenAI日常使用,统一接口,自动转换
/v1/messagesAnthropic需要 thinking 等特性
/v1/responsesOpenAI Responses需要 reasoning_content
/v1/gemini:generateContentGemini需要 Gemini 独有参数
/v1/gemini:streamGenerateContentGeminiGemini 流式生成
/v1/modelsOpenAI列出当前可用的逻辑路由与 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。