模型 API

OpenAI Chat Completions

通过 OpenAI Chat Completions API，用官方 OpenAI SDK 调用 GPT、Claude 和 Gemini 模型。内容涵盖带用量的流式输出、工具、推理模型以及不支持的功能。

Lovely Router 按照 OpenAI 的定义提供 POST /v1/chat/completions。把 OpenAI SDK 指向 https://lovelyrouter.com/v1，并使用你的 Lovely Router 密钥即可。请求体原样透传，因此每个参数都适用 OpenAI 的 API 参考。

配置 SDK#

Shell

curl https://lovelyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What does a load balancer do?"}
    ]
  }'

SDK 也会读取 OPENAI_BASE_URL 和 OPENAI_API_KEY，因此大多数兼容 OpenAI 的应用只需设置这两项。

可用模型#

GET /v1/models 中的每个文本模型目前都接受 Chat Completions，包括 Claude 和 Gemini 模型。图像模型（gpt-image-*）使用 Images API。因此，用这个 API 在不同厂商之间切换最为简单，一个客户端就够了。

系列	示例 ID	说明
GPT	`gpt-6.1-sol`、`gpt-6-astra`、`gpt-5.6-terra`、`gpt-5.6-luna`	原生 API。
Claude	`claude-sonnet-5.5`、`claude-opus-5.5`	如需 `cache_control` 和思考设置，请使用 Anthropic Messages。
Gemini	`gemini-3.1-pro`、`gemini-3-flash`	如需 `thinkingConfig` 及其他 Gemini 专有选项，请使用 Gemini API。

厂商特有的选项只有在模型的原生 API 中才能确保生效。请参阅各模型使用哪种 API。

带用量的流式输出#

设置 stream: true。网关总会加上 stream_options.include_usage: true，因此 data: [DONE] 之前的最后一个数据块，其 choices 数组为空，并带有本次调用的 usage。读取 delta 之前，请先检查 choices 是否非空。

Python

stream = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "Name five prime numbers."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\nTokens:", chunk.usage.prompt_tokens, "in,", chunk.usage.completion_tokens, "out")

传输格式以及流中途出现错误时的表现，请参阅流式输出。

调用函数#

在 tools 中描述函数。模型调用函数时，finish_reason 为 tool_calls；运行该函数，然后回复一条带有相同 tool_call_id 的 tool 消息。

Python

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by id.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]

response = client.chat.completions.create(model="gpt-6.1-sol", messages=messages, tools=tools)
msg = response.choices[0].message
if msg.tool_calls:
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = {"order_id": args["order_id"], "status": "shipped"}  # your code here
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    response = client.chat.completions.create(model="gpt-6.1-sol", messages=messages, tools=tools)
print(response.choices[0].message.content)

tool_choice、parallel_tool_calls 和 response_format 都会原样透传。

使用推理模型#

GPT-5 和 GPT-6 模型会先推理再作答。用 reasoning_effort 控制推理的多少，用 max_completion_tokens 限制总输出（包含推理 token）。可接受的 effort 取值因模型而异；请参阅 OpenAI 的推理指南。

Python

response = client.chat.completions.create(
    model="gpt-6.1-sol",
    reasoning_effort="high",
    max_completion_tokens=8000,
    messages=[{"role": "user", "content": "Find the bug: for i in range(len(a)): a.pop(i)"}],
)
usage = response.usage
print(response.choices[0].message.content)
print("reasoning tokens:", usage.completion_tokens_details.reasoning_tokens)

Chat Completions 不返回推理内容本身。推理 token 计入 usage.completion_tokens，按输出价格计费。

使用 Responses API#

GPT 模型也通过 OpenAI Responses API 在 POST /v1/responses 上提供，Codex CLI 和 Agents SDK 使用的就是这个 API。使用相同的 base URL 和密钥即可；SDK 的 client.responses.create() 无需改动就能使用。

Shell

curl https://lovelyrouter.com/v1/responses \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "instructions": "Answer in one sentence.",
    "input": "What is a router?"
  }'

设置 stream: true 后，你会收到该 API 的类型化事件（response.created、response.output_text.delta、…、response.completed）；用量在 response.completed 中返回，计费方式与其他调用相同。需要注意以下几点：

发送完整的对话。 Lovely Router 不会替你存储响应：对 /v1/responses/{id} 的 GET、DELETE 和取消操作都返回 404，而 previous_response_id 只在对话保持在同一个渠道上时才有效。请像 Codex 那样，在 input 中发送完整的历史记录，并设置 "store": false。
仅限 GPT 模型。 其他模型返回 404，消息为 not served in responses format；请用 Chat Completions 或它们自己的 API 调用这些模型。
响应中的 instructions 显示你发送的内容；如果你没有发送，则为 null。
prompt_cache_key 会把一个对话固定在同一个渠道上，与 Chat Completions 完全相同。

提示缓存#

OpenAI 模型会自动缓存较长的提示词前缀。缓存的 token 显示在 usage.prompt_tokens_details.cached_tokens 中，按更便宜的缓存读取价格计费。设置 prompt_cache_key 可以提高命中率，同时也告诉网关哪些请求属于同一个对话。请参阅提示缓存。

不支持的功能#

OpenAI 格式下提供 Chat Completions、Responses API 和 Images API。以下端点返回 404：

已存储的响应（对 /v1/responses/{id} 的 GET、DELETE 或取消操作）。
Embeddings（/v1/embeddings）。
Audio（/v1/audio/*）和图像变体（/v1/images/variations）。
旧版 Completions、Assistants、files、batches、fine-tuning 和 moderation。

GET /v1/models 可配合 OpenAI SDK 的 client.models.list() 使用，但不支持按 ID 获取单个模型。

请求头#

请求头	说明
`Authorization: Bearer`	你的 Lovely Router 密钥。必填。
`openai-beta`	按原样转发。
`x-lovely-group`	可选。当你的密钥未绑定渠道分组时，把请求锁定到指定的渠道分组。
`x-session-id`	可选。把多个请求归为同一个对话，用于缓存感知路由。请求体中的 `prompt_cache_key` 或 `user` 作用相同。

错误采用 OpenAI 的格式 {"error": {"message": "...", "type": "...", "code": "..."}}；请参阅错误。