API 参考

Lumoswitch Gateway 当前公开 OpenAI-compatible HTTP API。以下示例中的 Base URL 已包含 /v1。

鉴权与通用请求头

Authorization: Bearer YOUR_LUMOSWITCH_ACCESS_KEY
Content-Type: application/json

完整 Access Key 只在创建时显示一次。不要在浏览器前端、公开日志或代码仓库中使用它。

端点

方法	路径	Streaming	用途
GET	`/v1/models`	否	获取当前 Key 可见的对外模型
POST	`/v1/chat/completions`	是	Chat Completions-compatible 请求
POST	`/v1/responses`	是	Responses-compatible 请求
POST	`/v1/embeddings`	否	向量嵌入请求

获取模型

curl "$LUMOSWITCH_BASE_URL/models" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY"

返回的 id 是配置 API 暴露且当前 Key 允许使用的对外模型名称，不一定等于上游真实模型 ID。

Chat Completions

最小请求：

curl "$LUMOSWITCH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-public-model-name",
    "messages": [
      {"role": "system", "content": "You are concise."},
      {"role": "user", "content": "Say hello."}
    ],
    "stream": false
  }'

常用字段包括 model、messages、stream、temperature、max_tokens 和 tools。厂商专有字段可能被拒绝、忽略或无法透传，接入前应单独验证。

Streaming

将 stream 设为 true 后，响应使用 Server-Sent Events。客户端应：

持续读取 data: 事件。
允许一个 Unicode 字符跨多个网络分块。
处理空增量和工具调用增量。
读取到结束事件后关闭流。

反向代理缓冲会让流式响应看起来一次性返回，应在客户端链路中关闭 SSE 缓冲。

Tool Call

Tool Call 是否可用取决于候选模型和上游。请求中的工具定义应保持 OpenAI-compatible 结构；收到工具调用后，将工具结果作为后续消息发送。故障转移候选应支持兼容的工具格式，否则回退后可能失败。

Responses

curl "$LUMOSWITCH_BASE_URL/responses" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-public-model-name",
    "input": "Summarize this in one sentence."
  }'

当 Responses 请求进入仅支持 Chat Completions 的上游时，Lumoswitch 可以执行兼容转换。previous_response_id、Reasoning 和工具续接属于高级兼容行为，应在目标上游和客户端组合上验证，不要假定与 OpenAI 原生状态完全一致。

Embeddings

curl "$LUMOSWITCH_BASE_URL/embeddings" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-embedding-model",
    "input": ["first text", "second text"]
  }'

配置中的候选资源必须实际支持 Embeddings。不要将仅支持聊天的模型用于此端点。

错误响应

错误尽量保持 OpenAI-compatible 结构：

{
  "error": {
    "message": "A readable error message",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

HTTP 状态	常见含义
400	请求结构、协议或参数无效
401	Access Key 缺失、错误或已停用
403	模型范围或上游权限不足
404	对外模型名称或路径错误
429	Key RPM 或上游限流
5xx	上游失败、无可用候选或 Gateway 异常

常见错误码包括 invalid_request、rate_limit_exceeded 和 upstream_timeout。上游错误可能在安全处理后保留对应 HTTP 状态和摘要。

兼容性原则

先验证最小非流式文本请求，再逐步加入 Streaming、Tools、Vision、Reasoning 和厂商专有参数。详见协议与兼容性。

本地模型接入 Provisioning API（高级）