接入地址与鉴权

所有调用都发往网关地址 https://api.lyrouter.com，用同一个 LYRouter API Key 鉴权。OpenAI SDK 的 Base URL 填 https://api.lyrouter.com/v1，Anthropic SDK 填根地址 https://api.lyrouter.com；密钥放在 Authorization: Bearer <API Key> 或 x-api-key 请求头中。请求体的 model 写系统模型 ID、@vmodel/<名称> 或 lyrouter/auto，省略时使用工作空间的默认模型。

地址

• SDK 只填 Base URL：OpenAI SDK 会在 /v1 后拼接 /chat/completions、/responses、/models 等路径，Anthropic SDK 会在根地址后拼接 /v1/messages。cURL 和自己发 HTTP 请求时写完整 URL，例如 https://api.lyrouter.com/v1/chat/completions。
• 不要重复 /v1：Anthropic SDK 的 Base URL 写成 https://api.lyrouter.com/v1 时，实际请求 /v1/v1/messages，返回 404。OpenAI SDK 的 Base URL 写到 /v1/chat/completions 也会拼出错误路径。
• 版本前缀：除 /v1 外，网关也接受不带版本前缀（如 /chat/completions）或其他版本号前缀（如部分智谱客户端使用的 /v4/chat/completions）的同名路径，按同一接口处理。新接入的应用请统一使用 /v1。
• 控制台地址不是网关地址：浏览器中打开的控制台页面（/ai_gateway/...）不能用作 Base URL。自部署时，把本页的 https://api.lyrouter.com 换成你的网关地址。

鉴权

在当前工作空间的 API 密钥 页面创建 API Key，见创建工作空间与 API Key。网关按 API Key 识别工作空间，并在调用上游时换成平台或 BYOK 的服务商凭证；你的 API Key 不会转发给上游。服务商的 API Key 和控制台登录会话都不能用来调用网关。

• 只读一个：同时带两个请求头时，网关只读 Authorization。Authorization 格式错误时直接返回 401，不会改读 x-api-key。
• 只放在请求头：不要把密钥写进 URL 查询参数或请求体。
• 生效时间：新建、停用或修改 Key 后几秒内同步到网关。

API Key 自身的限制

创建或编辑 Key 时可以设置以下限制，触发后网关在调用上游前拒绝请求：

此外，Key 还受工作空间的安全围栏策略约束（模型策略、配额、客户端访问控制），见安全围栏与语义审计。各报错的处理见401 / 403：鉴权与权限和429：限流与配额。

OpenAI SDK

Chat Completions、Responses、Models、Embeddings 等 OpenAI 兼容接口共用同一个客户端，Base URL 写到 /v1：

curl https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(completion.choices[0].message.content)

# 同一个客户端调用 Responses
response = client.responses.create(model="MODEL_ID", input="用一句话介绍你自己")
print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});

const completion = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(completion.choices[0].message.content);

// 同一个客户端调用 Responses
const response = await client.responses.create({ model: "MODEL_ID", input: "用一句话介绍你自己" });
console.log(response.output_text);

MODEL_ID 换成模型广场中复制的模型 ID，LYROUTER_API_KEY 环境变量的设置见完成第一次模型调用。Responses 要求模型和服务它的通道支持 Responses 接口，见Responses。Python 示例中的 client.responses 需要 openai Python SDK 1.66 或更高版本，旧版本会报 AttributeError: 'OpenAI' object has no attribute 'responses'。

Anthropic SDK

Anthropic SDK 的 Base URL 写根地址，不带 /v1。/v1/messages 不要求模型来自 Anthropic，任何对话模型都可以通过它调用：

curl https://api.lyrouter.com/v1/messages \
  -H "x-api-key: $LYROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com",
});

const message = await client.messages.create({
  model: "MODEL_ID",
  max_tokens: 1024,
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(message.content[0].text);

请求、响应和流式事件的细节见Anthropic Messages。

只改环境变量接入已有代码

两种 SDK 都会读取环境变量。已有代码没有显式传入地址和密钥时，设置下表中的变量即可改走网关：

代码中的模型名也要换成 LYRouter 的模型 ID。Claude Code、Codex 等编程工具的配置见工具兼容性与接入总览。

model 字段

• 模型 ID 区分大小写，必须与模型广场或 GET /v1/models 返回的 id 逐字一致，命名规则见模型命名与查询。
• 省略 model 且工作空间没有默认模型时，返回 400 you must provide a model parameter（error.code 为 missing_model）；model 不是字符串时返回 400 invalid type for 'model': expected a string（invalid_model）。
• 虚拟模型和 lyrouter/auto 用在图像、视频、语音接口上时，返回 403 Model is not available in the model plaza，这些接口请写具体的模型 ID。

全部端点

所有端点使用同一个 Base URL 和同一套鉴权：

全部接口按能力分组的说明见API 文档，网关自定义的请求头和响应头见网关扩展请求头与响应头。

地址与鉴权类错误

OpenAI 兼容接口的错误体为 {"error": {"message": "...", "type": "...", "code": "..."}}，code 只在部分错误上出现。/v1/messages 上的错误会转换为 Anthropic 格式 {"type": "error", "error": {"type": "authentication_error", "message": "..."}}，message 原文不变，没有 code。

响应中不包含请求 ID。提交问题时，记录调用时间、端点、模型、API Key 名称和报错原文；能在 日志分析 中找到这次请求时，再附上日志详情顶部的 Request ID。401 请求无法归属到 Key，不会出现在日志中。全部错误码见错误码与请求标识。

常见问题

OpenAI SDK 的 Base URL 少写了 /v1，为什么也能调通？

答： 网关同时接受不带版本前缀的路径，https://api.lyrouter.com/chat/completions 与 /v1/chat/completions 等效。其他工具和 SDK 未必这样拼接路径，请统一写成 https://api.lyrouter.com/v1。

同一个 API Key 能同时给 OpenAI 和 Anthropic 客户端使用吗？

答： 可以。Key 属于工作空间，与协议无关；两种客户端调用同一个模型 ID 时，费用、配额和日志都记在这个 Key 下。日志的「API 路径」列可以区分请求来自哪个接口。

请求被路由到了哪个服务商，从响应里能看出来吗？

答： 响应中没有服务商信息，model 字段也是上游返回的值。在 日志分析 中打开这次请求，「模型（实际）」和「服务商」显示最终命中的模型和通道，见查看实际路由。