# LYRouter 文档

> LYRouter 是可信模型服务与 Token 治理平台。

以下按 llms.txt 约定（https://llmstxt.org）列出 LYRouter 文档每一页的 Markdown 版本，中文在前、英文在后。全部中文文档合在一份里见 https://platform.lyrouter.com/llms-full.txt。

## 快速开始

- [认识 LYRouter](https://platform.lyrouter.com/ai_gateway/docs/overview.md): LYRouter 是可信模型服务与 Token 治理平台。
- [完成第一次模型调用](https://platform.lyrouter.com/ai_gateway/docs/quickstart.md): 使用 LYRouter 的 OpenAI 兼容接口完成一次模型调用，再在控制台确认请求结果和用量。
- [创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys.md): API Key 是应用调用 LYRouter 网关的凭证。创建前先选择正确的账号与工作空间，确保密钥、模型来源和费用归属一致。
- [核心概念](https://platform.lyrouter.com/ai_gateway/docs/concepts.md): 使用 LYRouter 先要分清三层关系：账号和工作空间决定资源归谁，API Key 决定谁在调用，模型和服务来源决定请求最终发往哪个上游。本页介绍贯穿整套文档的概念，以及一次请求在网关里经过的处理步骤。
- [工具兼容性与接入总览](https://platform.lyrouter.com/ai_gateway/docs/tools.md): 工具接入 LYRouter 的关键是协议、接入地址、网关 API Key 和模型标识。各工具页面都从安装前提和安装步骤开始，已安装用户可以直接跳到配置部分。
- [Claude Code](https://platform.lyrouter.com/ai_gateway/docs/claude-code.md): Claude Code 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。
- [Codex](https://platform.lyrouter.com/ai_gateway/docs/codex.md): Codex CLI 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。
- [ChatGPT](https://platform.lyrouter.com/ai_gateway/docs/chatgpt.md): 本页介绍官方 ChatGPT 桌面应用的本地工作模式（Codex）如何配置 LYRouter 模型服务，参见官方网关配置指南。网页版聊天不读取本机的 config.toml，以下配置适用于桌面应用的本地工作。
- [OpenCode](https://platform.lyrouter.com/ai_gateway/docs/opencode.md): OpenCode 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。
- [TRAE](https://platform.lyrouter.com/ai_gateway/docs/trae.md): TRAE 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。
- [WorkBuddy](https://platform.lyrouter.com/ai_gateway/docs/workbuddy.md): WorkBuddy 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。
- [CC Switch](https://platform.lyrouter.com/ai_gateway/docs/ccswitch.md): CC Switch 是管理 Claude Code、Codex 等工具服务商配置的桌面应用，本身不调用模型。把 LYRouter 添加为它管理的服务商并启用后，目标工具就会通过 LYRouter 调用模型。本文从安装前提开始，说明如何配置并完成第一次调用。
- [其他 OpenAI 兼容客户端](https://platform.lyrouter.com/ai_gateway/docs/openai-clients.md): Cherry Studio、Chatbox、LobeChat、NextChat、Cline、Continue 等支持「自定义 OpenAI 接口」的客户端，接入 LYRouter 的方法都一样：添加一个 OpenAI 类型的自定义服务商，地址填 https://api.lyrouter.com/v1，密钥填 LYRouter API Key，再添加要用的模型 ID。本页说明通用的填写方法和常见问题。

## 用户指南

- [如何选择模型](https://platform.lyrouter.com/ai_gateway/docs/choose.md): 在工作空间的 模型广场 选择模型：先用左侧筛选缩小范围，再打开模型详情比较各服务商的状态、价格和计费单位，确认后复制模型 ID 填进请求的 model。只有「专属可用模型」中的模型可以用本工作空间的 API Key 调用；需要的模型不在其中时，由当前账号管理员或工作空间管理员开通，普通成员可以在详情页点击 申请开通。
- [模型能力与兼容性](https://platform.lyrouter.com/ai_gateway/docs/capabilities.md): LYRouter 用同一个地址提供 Chat Completions、Anthropic Messages 和 Responses 三种对话接口，以及图像、视频、语音等接口；一次调用能否成功、参数是否生效，取决于所选模型和实际服务它的通道。网关会在 Chat Completions 与 Anthropic Messages 之间自动转换，Responses 请求则原样转发到通道的 Responses 接口。模型不支持请求的接口或输入时，
- [多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal.md): 除文本对话与向量外，网关还支持视觉理解（图片输入）、图像生成与编辑、视频生成。文本类接口（chat/completions、embeddings）见 调用网关。
- [模型版本与下线](https://platform.lyrouter.com/ai_gateway/docs/versions.md): 请求中的 model 写的是模型 ID（如 deepseek/deepseek-v4-pro），不是模型广场上显示的名称。更换模型版本就是改用另一个模型 ID：先用真实任务验证，再更新应用配置。把模型名集中写在虚拟模型里，切换时只需改一处。模型在工作空间被停用或被平台下线后，调用会返回 403 Model is not available in the model plaza；工作空间设置了默认模型时，则可能改由默认模型回答。
- [通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing.md): 每个工作空间有一份智能路由设置，决定网关为一次调用选择哪个通道。同一个模型通常由多个通道提供，平台通道和你的 BYOK 通道都算在内。「多渠道选路策略」决定这些通道的尝试顺序；「默认模型」在请求没写 model，或请求的模型全部失败时接手。设置对工作空间内所有 API Key 生效，保存后几秒内同步到网关。
- [虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets.md): 虚拟模型把主模型、备用模型、Channel 排序策略、推理参数和系统提示词打包成一个名称。客户端把请求的 model 写成 @vmodel/<名称>，网关先调用主模型，失败时按顺序改用备用模型，并把参数和系统提示词合并进发给上游的请求。之后更换模型或调整参数，只需修改虚拟模型，客户端代码不用改。
- [Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto.md): 把请求的 model 写成 lyrouter/auto，网关会按这次请求的任务难度，在工作空间已开通的模型中挑选实际调用的模型。它适合允许模型变化的对话和编程助手等场景；对输出结构或模型行为要求严格的应用，请直接写模型 ID，或使用虚拟模型固定模型。
- [失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback.md): 一次调用失败时，网关会在开始向客户端输出内容之前，自动改用下一个凭证、通道或模型，直到成功或候选用完。客户端只收到最终结果，所以一次请求成功，不代表过程中没有发生上游失败；每次实际尝试都记录在请求日志中。
- [查看实际路由](https://platform.lyrouter.com/ai_gateway/docs/route-log.md): 一次调用最终由哪个模型、哪个服务商回答，中途是否换过通道、为什么换，都记录在日志详情的「路由追踪」中。当前账号管理员和工作空间管理员在 日志分析 中打开一条日志即可查看。调整智能路由、虚拟模型或 BYOK 后，用它确认设置是否按预期生效。
- [平台模型与 BYOK 如何选择](https://platform.lyrouter.com/ai_gateway/docs/byok-choice.md): LYRouter 的模型有两种来源：平台来源使用 LYRouter 提供的服务商通道和凭证，按用量从 Credits 余额扣费；BYOK（Bring Your Own Key，自带密钥）使用你在服务商处的 API Key，上游费用由服务商向你收取，LYRouter 对每次成功的 BYOK 调用收取一笔固定服务费。两种来源用同一个 LYRouter API Key、同一个模型 ID 调用，可以同时存在，由网关按路由规则选择。
- [接入供应商与测试连接](https://platform.lyrouter.com/ai_gateway/docs/byok.md): 当前账号管理员在工作空间的 自带密钥（BYOK） 页面，把自己在服务商处的 API Key 接入为一个 BYOK 通道。编辑器分「服务商与计费方式」「接入凭证」「模型与费用」「使用配置」四步，保存前用 测试连接 确认每个凭证都能访问服务商。保存后几秒内同步到网关，工作空间内所有 API Key 都可以通过它调用所选模型。
- [模型映射与来源配置](https://platform.lyrouter.com/ai_gateway/docs/mapping.md): 客户端始终用系统模型 ID（例如 deepseek/deepseek-v4-pro）调用，模型映射决定网关把它换成哪个上游模型名发给服务商。内置服务商的映射由平台维护，在 BYOK 的「模型与费用」步骤中勾选模型即可；自定义服务商需要先读取上游模型列表，再把每个上游模型对应到一个系统模型。保存后，这些模型在模型广场获得 BYOK 来源。
- [API 按量服务与 Coding Plan](https://platform.lyrouter.com/ai_gateway/docs/coding-plan.md): 很多服务商同时提供两种 API 接入：按 Token 用量付费的 API 服务，和按月订阅的 Coding Plan（编程套餐）。两者的地址、API Key、可用模型和额度规则通常不同，接入前先确认手里的是哪一种。在 BYOK 中，按量服务选「API 按量计费」，Coding Plan 选「订阅计费」；两种都用同一个 LYRouter API Key 调用，平台对每次成功调用收取相同的服务费。
- [BYOK 费用与凭证管理](https://platform.lyrouter.com/ai_gateway/docs/byok-cost.md): 使用 BYOK 有两笔费用：服务商按你的账户收取上游费用，LYRouter 对每次成功的 BYOK 调用从 Credits 余额扣一笔固定服务费，实际扣除额见「消费明细」。BYOK 列表按凭证统计服务商成本估算和 Token 用量；凭证的替换、启停、排序和限额都在 BYOK 编辑器的「接入凭证」步骤中管理。
- [计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing.md): LYRouter 用 Credits（信用点）计费：一个组织只有一个 Credits 余额，组织下所有工作空间和 API Key 共用。调用平台模型按实际用量扣 Credits，BYOK 调用按次收取平台服务费；余额降到 0 及以下时，调用返回 402。团队版和企业版另按席位订阅，到期后有 7 天宽限期，之后控制台只能查看、调用返回 402 subscription expired; renew to continue。
- [调用费用与缓存计费](https://platform.lyrouter.com/ai_gateway/docs/estimate.md): 一次文本调用的费用由四类 Token 分别计价后相加：「输入（缓存未命中）」按价格表的「输入」单价，「输入（缓存命中）」「输出」「显式缓存创建」按价格表中同名一项的单价。单价以工作空间 模型广场 中模型详情的「平台价」为准，长上下文分档、分时计价、服务档位等条件会改变适用的单价。只有成功的调用扣费，估算结果可以用请求日志的「费用」和 订阅充值 的「消费明细」核对。
- [预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota.md): LYRouter 有两种用量上限：API Key 的「预算限额」只约束这一把 Key，由 Key 创建者或当前账号管理员在 Key 设置中填写；安全围栏的「配额管理」策略由当前账号管理员按工作空间、部门、组织成员或 API Key 设置，可以按信用点或百万 Token 计量、按月或按天清零，并给个别成员设例外。任一上限用完，之后的请求返回 429，到 reset_at 之后恢复。配额只限制用量，与组织的信用点余额是两回事。
- [用量归因与分析](https://platform.lyrouter.com/ai_gateway/docs/analytics.md): 用量分析按工作空间汇总一段时间内的请求数、Token、缓存命中率和费用，并按 API Key、部门、用户、模型和意图拆分，用来回答「谁在用、用在哪些模型上、花了多少」。用量按 API Key 归到 Key 的创建人及其部门；普通成员只能看到自己创建的 Key。费用以人民币显示：平台请求按实际扣费金额计算，BYOK 按服务商成本计算。核对单次请求请看日志，核对 Credits 扣费请看消费明细。
- [购买、账单与发票](https://platform.lyrouter.com/ai_gateway/docs/orders.md): 订阅套餐、购买资源包、续费、增购席位、核销兑换码和申请发票，都由当前账号管理员在 订阅充值 页面完成。下单后用微信或支付宝扫码付款，团队版和企业版组织还可以对公转账；没付完的订单可以从「订单记录」继续支付，不必重新下单。实际付款的人民币订单完成后，可以在「订单记录」中申请发票。
- [组织、成员与角色](https://platform.lyrouter.com/ai_gateway/docs/organization.md): 团队版和企业版的组织由当前账号管理员负责管理：在 组织管理 页搭建部门、用邮箱邀请或邀请链接招募成员，并决定每位成员能进入哪些工作空间、以什么角色使用。组织层面只有账号管理员和普通成员两种角色；每个工作空间里另有查看者、编辑者、管理员三种角色，决定成员在该空间内能做什么。成员人数受订阅席位数限制，账号管理员身份暂不支持转让。
- [模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization.md): 一把 API Key 能调用哪些模型由两层设置决定：Key 所属工作空间在 模型广场 中开通的模型是基线；安全围栏的「模型访问控制」策略再按部门、组织成员或 API Key 收窄，只能减少、不能增加。模型没有在工作空间开通时，调用返回 403 model_not_available；被模型策略拦下时返回 403 guardrail_model。
- [安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails.md): 安全围栏是工作空间级的调用策略：网关按策略检查每次调用的配额、模型、客户端和请求内容，命中后告警、掩码、剥离、阻断或封禁，并在 安全事件 页留下记录。配额管理、模型访问控制、客户端访问控制从团队版起可用；敏感信息检测、提示词注入检测、意图安全检测需要企业版。策略和事件都由当前账号管理员在工作空间的 安全围栏、安全事件 页管理，普通成员看不到这两个页面。
- [日志内容与数据处理](https://platform.lyrouter.com/ai_gateway/docs/privacy.md): 模型调用的内容经过 LYRouter 网关转发给选中的上游服务商。日志默认只记录元数据，例如模型、服务商、状态码、Token、费用和耗时；只有工作空间开启「保存请求响应全文」后，才会保存经过平台脱敏的提示词、回答和报文正文。本章说明日志保存哪些内容、如何开关全文日志、上游服务商会收到什么，以及谁能查看正文和导出日志。
- [数据保留、导出与删除](https://platform.lyrouter.com/ai_gateway/docs/retention.md): 日志正文（对话、原始报文、路由候选与尝试记录）可以查看多少天，由账户的订阅决定；超过留存期后，日志只保留元数据。日志记录本身最多保存 180 天，之后自动删除。需要长期留存时，由当前账号管理员或工作空间管理员在留存期内按时间范围加密导出，导出文件保留 24 小时。
- [通过日志定位调用问题](https://platform.lyrouter.com/ai_gateway/docs/logs.md): 每次经过 LYRouter 网关的模型调用，都会在工作空间的 日志分析 页留下一条日志。按时间、API Key、模型和状态码找到这次请求，打开详情就能看到实际调用的模型和服务商、失败来自网关还是上游、各阶段耗时、Token 和费用。日志在调用结束后几秒内可以查到；联系支持时，请附上日志详情顶部的 Request ID。
- [401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors.md): 401 表示网关没有认出请求中的 API Key；403 表示 Key 有效，但这次请求被拒绝。先读响应体中的 error.message 和 error.code，再按下表找到对应原因。通过 /v1/messages 调用时，错误会转换为 Anthropic 格式，不再带 error.code，请以 message 为准。
- [429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors.md): 429 有三种来源，按 error.message 区分：配额或预算已用完、API Key 因错误率过高被临时熔断、模型的所有上游凭证都已达到限额。三者的处理方式不同，单靠重试解决不了配额用完的问题。
- [模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable.md): 模型名写错、模型没有开通、没有可用的通道或凭证、余额不足，以及计费或配置暂时不可用，都会表现为模型调不通。请按响应中的报错原文在下表找到原因。工作空间在智能路由中设置了默认模型时，很多对话请求会改由默认模型回答，而不会收到这些错误；可以在日志的「模型（实际）」中确认。
- [超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors.md): 网关等待上游时有 6 分钟的空闲超时。连接上游失败或等待超时，网关会先换下一个通道，全部失败后返回 500 或 504，响应体是 HTML 页面而不是 JSON。流式请求一旦开始输出就不再换通道，中途出错时网关在流末尾补发一个错误事件后结束连接。客户端应把没有收到结束标记的流当作失败处理，并自行决定重试和去重。
- [费用异常与缓存未命中](https://platform.lyrouter.com/ai_gateway/docs/cache-errors.md): 费用与预估不符，最常见的原因是把缓存命中的输入按输入单价重复计算、长上下文请求落入了更贵的档位、思考过程产生了大量输出，或者提示词缓存没有命中。排查时先在请求日志详情的「Token 消耗」中看清四项 Token，再对照下面的问题逐项检查。估算方法见调用费用与缓存计费，提高命中率的做法见降低成本与优化缓存。
- [研发团队工具管理](https://platform.lyrouter.com/ai_gateway/docs/dev-team.md): 为研发团队接入 Claude Code、Codex 等编程工具时，推荐的做法是：按项目或环境划分工作空间，每位成员或每个应用使用自己创建的 API Key，工具里统一填写虚拟模型名。这样预算、权限、日志和用量都能按人、按应用分开统计，更换模型时也不必逐台修改工具配置。
- [应用接入多个供应商](https://platform.lyrouter.com/ai_gateway/docs/multi-provider.md): 应用只需写一个模型 ID，网关就会在提供该模型的多个通道之间选择和回退，平台提供的服务商通道和你通过 BYOK 接入的通道都算在内。需要在一个模型失败后改用另一个模型时，使用虚拟模型的备用模型或工作空间默认模型。不同通道可能使用不同的上游协议，对同一请求的处理也会不同，所以上线前要逐个通道验证。
- [降低成本与优化缓存](https://platform.lyrouter.com/ai_gateway/docs/cost-practice.md): Agent、编程助手这类应用每一轮都会重新发送系统提示词、工具定义和全部历史，输入 Token 往往占费用的大头，所以提示词缓存命中率基本决定了 Token 费用。降低成本的主要做法是让请求前缀保持稳定、让同一会话留在同一个通道上，再减少不必要的输出和上下文。每项调整后，用日志和用量分析中的缓存命中率与费用验证效果。
- [预算归因与调用审计](https://platform.lyrouter.com/ai_gateway/docs/audit-practice.md): LYRouter 以 API Key 为归属单位：每次调用都记在 Key 所属的工作空间、Key 的创建人和创建人的主部门名下。要让费用落到具体的人或应用，就让每位成员、每个应用使用自己创建的 Key。对账时，用日志分析、用量分析和消费明细三处数据交叉核对；审计材料按角色控制正文的查看和导出，对外提供前先脱敏。
- [服务状态](https://platform.lyrouter.com/ai_gateway/docs/status.md): 服务状态页公开展示网关对各模型上游线路的主动探测结果，包括每条线路的状态、首字延迟、吞吐、成功率和最近 24 小时的逐小时记录。点击顶栏 服务状态 即可打开，无需登录。它反映的是平台线路本身是否可用；某个 API Key 的权限、余额、配额，以及你的 BYOK 凭证都不在探测范围内。线路正常但请求失败时，请按响应中的报错原文排查。

## API 文档

- [API 文档](https://platform.lyrouter.com/ai_gateway/docs/api-overview.md): LYRouter 网关的完整接口参考。所有接口都在 https://api.lyrouter.com 上开放，用同一个 API Key 鉴权：对话、向量、图像接口兼容 OpenAI 格式，/v1/messages 兼容 Anthropic 格式，视频生成是异步任务。
- [Chat Completions 格式](https://platform.lyrouter.com/ai_gateway/docs/chat-completions.md): 根据对话历史生成模型回答，支持流式和非流式响应、图片输入和工具调用。兼容 OpenAI Chat Completions API：OpenAI 官方 SDK 和大多数兼容 OpenAI 的应用把 Base URL 改成 https://api.lyrouter.com/v1 即可使用。同一个模型可能由 OpenAI 兼容或 Anthropic 协议的通道服务，网关会自动转换请求和响应，本页同时说明转换时哪些参数会变化。
- [Responses 格式](https://platform.lyrouter.com/ai_gateway/docs/responses-api.md): 创建一个模型响应：用 input 传入文本或一组输入项，返回带 id 的响应对象，输出放在 output 数组里，按项区分消息、函数调用和推理内容，支持流式。兼容 OpenAI Responses API：OpenAI SDK 的 client.responses 和使用 Responses 协议的客户端（例如 Codex CLI）把 Base URL 设为 https://api.lyrouter.com/v1 即可使用，与 Chat
- [Anthropic 格式](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages.md): 根据对话历史生成模型回答，支持流式、图片输入和工具调用。兼容 Anthropic Messages API：系统提示词放在 system，对话放在由内容块组成的 messages，响应的 content 也是内容块数组；Anthropic 官方 SDK 和 Claude Code 等 Anthropic 协议客户端，把 Base URL 设为网关根地址 https://api.lyrouter.com 即可接入。网关会在 Message
- [创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings.md): 把一段或多段文本转换成向量，适合检索增强（RAG）、语义搜索和去重；需要按与查询的相关度给文档排序时，用文档重排。接口采用 OpenAI Embeddings API 的格式，OpenAI SDK 的 client.embeddings.create() 把 Base URL 设为 https://api.lyrouter.com/v1 即可使用；请求和响应都是 JSON，不支持流式。网关只把 model 换成服务商的真实模型名，其余字
- [文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank.md): 按与查询的相关度给一组文档打分并排序，适合在检索增强（RAG）、语义搜索中对召回结果做精排；把文本转换成向量用创建向量。OpenAI 没有重排接口，LYRouter 把请求体原样发到通道的 /rerank 地址，只替换 model，所以字段名、取值和响应格式以模型所属服务商的 rerank 文档为准。请求和响应都是 JSON，不支持流式；OpenAI SDK 没有重排方法，请直接发 HTTP 请求。
- [图像生成](https://platform.lyrouter.com/ai_gateway/docs/images-generations.md): 根据文本提示词生成图片，也可以附带参考图做图生图。兼容 OpenAI Images API 的 images.generate：OpenAI 官方 SDK 把 Base URL 改成 https://api.lyrouter.com/v1 即可调用，图片在同一个响应里返回，不需要轮询。目前可用 Seedream 5.0、GPT-Image、Gemini Image 三个系列，参数写法和返回形式因系列而异，见下文各模型小节。
- [图像编辑](https://platform.lyrouter.com/ai_gateway/docs/images-edits.md): 按提示词修改输入的图片，或以一张、多张图片为参考生成新图。兼容 OpenAI Images API 的 images.edit，请求体有两种写法：multipart/form-data 上传图片文件（OpenAI 官方 SDK 的写法），或 JSON 把图片以 Base64 放在请求体里（LYRouter 的扩展）。支持编辑的是 GPT-Image 和 Gemini Image 两个系列，两种写法都可用；Seedream 不支持本接口，
- [列出模型](https://platform.lyrouter.com/ai_gateway/docs/models.md): 返回当前 API Key 可以写进 model 的全部名称：Key 所属工作空间已开通、且安全围栏模型策略允许这个 Key 调用的模型，外加已启用的虚拟模型（@vmodel/<名称>）和 lyrouter/auto。响应是 OpenAI 的模型列表格式，适合客户端填充模型选择器，或在启动时检查配置的模型是否可用。这个接口由网关直接应答，不调用上游、不计费，也不写入日志列表。
- [Seedance 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-seedance.md): 用火山方舟的 Seedance 系列模型生成视频，支持文生视频、首帧 / 首尾帧生视频、参考图或参考视频生视频，以及视频编辑与延长。视频生成以异步任务的方式提供：提交后立即拿到任务 ID，轮询到完成后再下载视频。接口形状参照 OpenAI 的 Videos API，网关把统一的参数转换成火山方舟的格式；OpenAI 官方 SDK 的 videos.create() 可以直接提交任务，查询和下载建议用 HTTP 直接调用。任务生命周期的通
- [MiniMax H3 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-minimax.md): 用 MiniMax H3 系列模型生成视频，支持文生视频、首尾帧图生视频，以及用参考图、参考视频、参考音频做多模态参考生视频。除了普通的视频生成，minimax/minimax-h3 还提供两个只有它支持的接口：视频升清（POST /v1/videos/regenerations，把 768P 视频重新生成为 2K）和上下文增强（POST /v1/videos/context，产物是增强后的提示词文本）。三种任务都以异步任务的方式提供，
- [接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway.md): 所有调用都发往网关地址 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 请求头中。请求体的 mod
- [模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names.md): 请求中的 model 写模型 ID，格式为 厂商/模型（例如 deepseek/deepseek-v4-flash），区分大小写，必须与模型广场或 GET /v1/models 返回的值逐字一致。另有两类特殊名称：@vmodel/<名称> 调用虚拟模型，lyrouter/auto 调用 Auto 智能路由。客户端始终写模型 ID，服务商那边的真实模型名（包括 BYOK 的接入点编号）由网关替换，不要写进请求。
- [流式响应](https://platform.lyrouter.com/ai_gateway/docs/streaming.md): 请求中设置 "stream": true 后，Chat Completions、Responses 和 Anthropic Messages 三种对话接口都以 SSE（Server-Sent Events）逐段返回内容。三种协议的事件格式、结束标记和 usage 的位置各不相同，客户端要按所用协议解析，并以协议的结束标记判断输出是否完整。本章讲协议格式与客户端实现；流式中断、超时的排查见超时与流式中断。
- [工具调用](https://platform.lyrouter.com/ai_gateway/docs/tool-call.md): 工具调用（Function Calling）让模型以结构化参数请求调用你定义的函数：应用在请求中声明工具，模型返回要调用的函数名和参数，应用自己执行函数，再把结果发回给模型，由模型给出最终回答。LYRouter 只负责转发和协议转换，不会执行你的任何业务操作。Chat Completions、Responses、Anthropic Messages 三种接口的工具结构不同，网关会在 Chat Completions 与 Anthropi
- [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async.md): 视频生成通常需要几分钟，LYRouter 以异步任务的方式提供：POST /v1/videos 提交后立即返回一个以 aigwt_ 开头的任务 ID，之后用 GET /v1/videos/{id} 查询状态，完成后用 GET /v1/videos/{id}/content 下载视频。网关会替你向服务商轮询任务进度，你的查询只读取网关记录的状态；费用在任务完成时结算，失败或超时的任务不收费。各模型的参数、尺寸和计费单位见多模态能力，本页只
- [网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers.md): 除了 OpenAI、Anthropic 的标准字段，LYRouter 还约定了几个请求头、响应头和特殊模型名：用请求头控制参数校验、声明会话、要求原生直通，从响应头读取被丢弃的参数和配额余量，用特殊模型名调用虚拟模型、Auto 智能路由或默认模型。这些约定都是可选的，不使用时按标准协议正常调用。HTTP 头名不区分大小写。
- [错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors.md): LYRouter 拒绝一次调用时返回 4xx 或 5xx 状态码。OpenAI 兼容接口的错误体是 {"error": {"message", "type", "code"}}，/v1/messages 上转换为 Anthropic 格式，另有少数响应是 HTML 页面或一行纯文本。按状态码和 error.message 原文在本页速查表中找到条目，就能判断问题出在请求本身、账户与配置，还是平台或上游服务商，以及该怎么处理。网关不在响应
- [协议兼容性与限制](https://platform.lyrouter.com/ai_gateway/docs/compatibility.md): LYRouter 提供 Chat Completions、Anthropic Messages、Responses 三种对话接口，而每个服务商通道只使用一种上游协议：OpenAI 兼容或 Anthropic。客户端接口与通道协议不同时，网关自动转换请求、响应、流式事件和错误格式；转换只保留双方都有对应含义的字段，其余字段会被去掉或改写，且不会写进响应头。Responses 请求不做协议转换，只能由提供 Responses 接口的通道服务
- [在 AI 工具中使用本文档](https://platform.lyrouter.com/ai_gateway/docs/ai-tools.md): 本文档的每一页都有给 AI 读的 Markdown 版本，另有整站目录、全文合集、OpenAPI 规格和一个 MCP 服务。让 DeepSeek、ChatGPT、Claude、Cursor、Claude Code 等工具按 LYRouter 的接口写代码时，把下面任一份交给它，比让它凭记忆猜更准确。

## English: Quick start

- [About LYRouter](https://platform.lyrouter.com/ai_gateway/docs/overview/en.md): LYRouter is a trusted model service and token governance platform.
- [Your first model call](https://platform.lyrouter.com/ai_gateway/docs/quickstart/en.md): Call LYRouter using an OpenAI-compatible client, then check the response and request log.
- [Workspaces and API keys](https://platform.lyrouter.com/ai_gateway/docs/api-keys/en.md): Create an API Key in the correct Account and workspace so that model access and usage attribution share the same scope.
- [Core concepts](https://platform.lyrouter.com/ai_gateway/docs/concepts/en.md): To use LYRouter, first keep three layers apart: the account and workspace decide who owns resources, the API key decides who is calling, and the model and its service source decide which upstream the request finally goes
- [Tools and compatibility](https://platform.lyrouter.com/ai_gateway/docs/tools/en.md): Connecting a tool to LYRouter comes down to the protocol, the base URL, the gateway API key and the model identifier. Each tool page starts with installation prerequisites and installation steps; if you have already inst
- [Claude Code](https://platform.lyrouter.com/ai_gateway/docs/claude-code/en.md): Claude Code can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
- [Codex](https://platform.lyrouter.com/ai_gateway/docs/codex/en.md): Codex CLI can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
- [ChatGPT](https://platform.lyrouter.com/ai_gateway/docs/chatgpt/en.md): This page shows how to configure a LYRouter model service for local work (Codex) in the official ChatGPT desktop app; see also the official gateway configuration guide. ChatGPT on the web does not read your local config.
- [OpenCode](https://platform.lyrouter.com/ai_gateway/docs/opencode/en.md): OpenCode can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
- [TRAE](https://platform.lyrouter.com/ai_gateway/docs/trae/en.md): TRAE can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
- [WorkBuddy](https://platform.lyrouter.com/ai_gateway/docs/workbuddy/en.md): WorkBuddy can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
- [CC Switch](https://platform.lyrouter.com/ai_gateway/docs/ccswitch/en.md): CC Switch is a desktop app that manages provider settings for tools such as Claude Code and Codex; it does not call models itself. Once you add LYRouter as a provider in CC Switch and enable it, the target tool calls mod
- [Other OpenAI-compatible clients](https://platform.lyrouter.com/ai_gateway/docs/openai-clients/en.md): Cherry Studio, Chatbox, LobeChat, NextChat, Cline, Continue and other clients that support a custom OpenAI API all connect to LYRouter the same way: add a custom provider of the OpenAI type, set the address to https://ap

## English: User guide

- [Choosing a model](https://platform.lyrouter.com/ai_gateway/docs/choose/en.md): Choose models in the workspace's Model marketplace: narrow the range with the filters on the left, open the model details to compare each provider's status, price and billing unit, then copy the model ID into the request
- [Capabilities and compatibility](https://platform.lyrouter.com/ai_gateway/docs/capabilities/en.md): LYRouter serves three chat endpoints, Chat Completions, Anthropic Messages and Responses, plus image, video, audio and other endpoints, from a single address. Whether a call succeeds and whether its params take effect de
- [Multimodal capabilities](https://platform.lyrouter.com/ai_gateway/docs/multimodal/en.md): Besides text chat and embeddings, the gateway supports vision (image input), image generation and editing and video generation. For the text endpoints (chat/completions, embeddings) see Calling the gateway.
- [Model versions and retirement](https://platform.lyrouter.com/ai_gateway/docs/versions/en.md): The model in a request is a model ID (such as deepseek/deepseek-v4-pro), not the name shown in the model marketplace. Changing a model version means switching to another model ID: validate it with real tasks first, then 
- [Channels and routing](https://platform.lyrouter.com/ai_gateway/docs/routing/en.md): Each workspace has one set of Smart routing settings that decides which channel the gateway uses for a call. A model is usually served by several channels, counting both platform channels and your BYOK channels. The mult
- [Virtual models](https://platform.lyrouter.com/ai_gateway/docs/presets/en.md): A virtual model bundles a primary model, fallback models, a Channel sort strategy, inference params and a system prompt under one name. The client sets the request's model to @vmodel/<name>; the gateway calls the primary
- [Auto routing](https://platform.lyrouter.com/ai_gateway/docs/auto/en.md): Set the request's model to lyrouter/auto, and the gateway picks the model to call from the models enabled in the workspace, based on how difficult the request's task is. It suits scenarios that tolerate a changing model,
- [Retries and fallback](https://platform.lyrouter.com/ai_gateway/docs/fallback/en.md): When a call fails, the gateway automatically moves to the next credential, channel or model before it starts sending output to the client, until a call succeeds or the candidates run out. The client receives only the fin
- [Inspecting request routing](https://platform.lyrouter.com/ai_gateway/docs/route-log/en.md): Which model and which provider finally answered a call, whether the gateway switched channels along the way and why, are all recorded in the route trace of the log detail. The current Account Owner and workspace Admins s
- [Platform models or BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok-choice/en.md): LYRouter models come from two kinds of source. A platform source uses provider channels and credentials supplied by LYRouter and is charged to your Credits balance by usage. BYOK (Bring Your Own Key) uses your own API ke
- [Connect a provider](https://platform.lyrouter.com/ai_gateway/docs/byok/en.md): The current Account Owner connects their own provider API keys as a BYOK channel on the workspace's BYOK page. The editor has four steps, Provider & billing, Credentials, Models & cost and Usage, and Test connection chec
- [Model mappings and sources](https://platform.lyrouter.com/ai_gateway/docs/mapping/en.md): Clients always call with a system model ID (for example deepseek/deepseek-v4-pro), and the model mapping decides which upstream model name the gateway sends to the provider in its place. For built-in providers the platfo
- [API services and Coding Plans](https://platform.lyrouter.com/ai_gateway/docs/coding-plan/en.md): Many providers offer two kinds of API access: a pay-as-you-go API service billed by token usage, and a Coding Plan, a subscription billed monthly. The two usually differ in address, API key, available models and quota ru
- [BYOK fees and credentials](https://platform.lyrouter.com/ai_gateway/docs/byok-cost/en.md): BYOK involves two charges: the provider bills your account for upstream usage, and LYRouter deducts a fixed service fee from your Credits balance for each successful BYOK call; the amount actually deducted appears in Con
- [Billing and Credits](https://platform.lyrouter.com/ai_gateway/docs/billing/en.md): LYRouter bills in Credits: an organization has a single Credits balance, shared by every workspace and API key in it. Calls to platform models are charged in Credits by actual usage, and BYOK calls are charged a platform
- [Estimating costs and cache pricing](https://platform.lyrouter.com/ai_gateway/docs/estimate/en.md): The cost of a text call is the sum of four Token types, each priced separately: Input (cache miss) at the price table's Input price, Input (cache hit) and Output at the prices of the same name, and Explicit cache write a
- [Budgets, quotas and rate limits](https://platform.lyrouter.com/ai_gateway/docs/quota/en.md): LYRouter has two kinds of usage limits. The Budget limits of an API key constrain only that key and are filled in by the key's creator or the current Account Owner in the key settings. Quota policies in guardrails are se
- [Usage attribution and analytics](https://platform.lyrouter.com/ai_gateway/docs/analytics/en.md): Usage analytics summarizes a workspace's requests, Tokens, cache hit rate and spend over a time range, and breaks them down by API key, department, user, model and intent, so you can see who is using what and how much it
- [Purchases, bills and invoices](https://platform.lyrouter.com/ai_gateway/docs/orders/en.md): Subscribing to plans, buying resource packs, renewing, adding seats, redeeming codes and requesting invoices are all done by the current Account Owner on the Subscription & Credits page. After placing an order you pay by
- [Teams, members and roles](https://platform.lyrouter.com/ai_gateway/docs/organization/en.md): Team and Enterprise organizations are managed by the current Account Owner, who uses the Organization management page to build departments, recruit members by email invitation or invitation link, and decide which workspa
- [Model access](https://platform.lyrouter.com/ai_gateway/docs/authorization/en.md): Two layers of settings decide which models an API key can call. The models enabled in the Model marketplace of the key's workspace are the baseline; Model access policies in guardrails then narrow it by department, organ
- [Guardrails and semantic auditing](https://platform.lyrouter.com/ai_gateway/docs/guardrails/en.md): Guardrails are workspace-level call policies: the gateway checks the quota, model, client and request content of every call against them and, on a match, alerts, masks, strips, blocks or bans, leaving a record on the Sec
- [Logs and data processing](https://platform.lyrouter.com/ai_gateway/docs/privacy/en.md): The content of a model call passes through the LYRouter gateway to the selected upstream provider. By default, logs record only metadata, such as the model, provider, status code, Tokens, cost and latency; prompts, answe
- [Retention, exports and deletion](https://platform.lyrouter.com/ai_gateway/docs/retention/en.md): How many days log content (conversations, raw packets, routing candidates and attempt records) can be viewed is set by the account's subscription; after the retention period, logs keep only metadata. Log records themselv
- [Troubleshooting with logs](https://platform.lyrouter.com/ai_gateway/docs/logs/en.md): Every model call that passes through the LYRouter gateway leaves one entry on the workspace's Log analysis page. Find the request by time, API key, model and status code, then open its detail to see which model and provi
- [401 / 403: authentication and access](https://platform.lyrouter.com/ai_gateway/docs/auth-errors/en.md): A 401 means the gateway did not recognize the API key in the request; a 403 means the key is valid but this request was refused. Read error.message and error.code in the response body first, then find the cause in the ta
- [429: rate limits and quotas](https://platform.lyrouter.com/ai_gateway/docs/rate-errors/en.md): A 429 has three sources, told apart by error.message: a quota or budget is used up, the API key was temporarily circuit-broken for a high error rate, or every upstream credential for the model has reached its limit. Each
- [Unavailable models](https://platform.lyrouter.com/ai_gateway/docs/unavailable/en.md): A misspelled model name, a model that is not enabled, no usable channel or credential, an insufficient balance, and temporarily unavailable billing or configuration all show up as a model you cannot call. Find the cause 
- [Timeouts and interrupted streams](https://platform.lyrouter.com/ai_gateway/docs/stream-errors/en.md): The gateway waits for the upstream with a 6-minute idle timeout. When connecting to the upstream fails or the wait times out, the gateway first moves on to the next channel; when every channel fails, it returns 500 or 50
- [Unexpected costs and cache misses](https://platform.lyrouter.com/ai_gateway/docs/cache-errors/en.md): When a cost does not match your estimate, the most common reasons are that cache-hit input was counted again at the input price, a long-context request fell into a more expensive tier, thinking produced a lot of output, 
- [Managing coding tools for a team](https://platform.lyrouter.com/ai_gateway/docs/dev-team/en.md): When you connect coding tools such as Claude Code and Codex for an engineering team, the recommended approach is: split workspaces by project or environment, give each member or application an API key it created itself, 
- [Connecting multiple providers](https://platform.lyrouter.com/ai_gateway/docs/multi-provider/en.md): Your application only needs one model ID: the gateway chooses among, and falls back across, the channels that serve that model, counting both the provider channels the platform supplies and the channels you connect throu
- [Reducing costs and improving cache reuse](https://platform.lyrouter.com/ai_gateway/docs/cost-practice/en.md): Agents and coding assistants resend the system prompt, tool definitions and the whole history on every turn, so input Tokens are often most of the cost, and the prompt cache hit rate largely decides what you pay for Toke
- [Budget attribution and auditing](https://platform.lyrouter.com/ai_gateway/docs/audit-practice/en.md): LYRouter attributes usage by API key: every call is recorded under the key's workspace, the key's creator and the creator's primary department. To make costs land on a specific person or application, have each member and
- [Service status](https://platform.lyrouter.com/ai_gateway/docs/status/en.md): The Service Status page publicly shows the results of the gateway's active probes against the upstream lines of each model: each line's status, TTFT (time to first token), throughput, success rate and an hourly record of

## English: API documentation

- [API documentation](https://platform.lyrouter.com/ai_gateway/docs/api-overview/en.md): The complete reference for the LYRouter gateway API. Every endpoint is served at https://api.lyrouter.com and authenticates with the same API key: the chat, embeddings and image endpoints are compatible with the OpenAI f
- [Chat Completions format](https://platform.lyrouter.com/ai_gateway/docs/chat-completions/en.md): Generates a model reply from the conversation history, with streaming and non-streaming responses, image input and tool calls. It is compatible with the OpenAI Chat Completions API: the official OpenAI SDKs and most Open
- [Responses format](https://platform.lyrouter.com/ai_gateway/docs/responses-api/en.md): Creates a model response: you pass text or a list of input items in input, and it returns a response object with an id, with the output in the output array, where each item is a message, a function call or reasoning cont
- [Anthropic format](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages/en.md): Generates a model reply from the conversation history, with streaming, image input and tool calls. It is compatible with the Anthropic Messages API: the system prompt goes in system, the conversation goes in messages mad
- [Create embeddings](https://platform.lyrouter.com/ai_gateway/docs/embeddings/en.md): Converts one or more pieces of text into vectors, for retrieval-augmented generation (RAG), semantic search and deduplication; to sort documents by relevance to a query, use Rerank documents. The endpoint uses the OpenAI
- [Rerank documents](https://platform.lyrouter.com/ai_gateway/docs/rerank/en.md): Scores a set of documents by relevance to a query and sorts them, for refining retrieved results in retrieval-augmented generation (RAG) and semantic search; to convert text into vectors, use Create embeddings. OpenAI ha
- [Create images](https://platform.lyrouter.com/ai_gateway/docs/images-generations/en.md): Generates images from a text prompt, optionally with reference images for image-to-image. It is compatible with images.generate in the OpenAI Images API: the official OpenAI SDKs work once you set the Base URL to https:/
- [Edit images](https://platform.lyrouter.com/ai_gateway/docs/images-edits/en.md): Modifies input images according to a prompt, or generates a new image using one or more images as references. It is compatible with images.edit in the OpenAI Images API, and the request body can be written in two ways: m
- [List models](https://platform.lyrouter.com/ai_gateway/docs/models/en.md): Returns every name the current API key can put in model: the models enabled in the key's workspace that the guardrail model policies allow this key to call, plus the enabled virtual models (@vmodel/<name>) and lyrouter/a
- [Seedance video generation](https://platform.lyrouter.com/ai_gateway/docs/video-seedance/en.md): Generate videos with Volcengine Ark's Seedance models: text to video, first-frame and first-and-last-frame video, video from reference images or a reference video, plus video editing and extension. Video generation runs 
- [MiniMax H3 video generation](https://platform.lyrouter.com/ai_gateway/docs/video-minimax/en.md): Generate videos with the MiniMax H3 models: text to video, first-and-last-frame image to video, and omni-reference video from reference images, reference videos and reference audio. Besides regular video generation, mini
- [Base URLs and authentication](https://platform.lyrouter.com/ai_gateway/docs/call-gateway/en.md): All calls go to the gateway address https://api.lyrouter.com and authenticate with the same LYRouter API key. Set the OpenAI SDK's Base URL to https://api.lyrouter.com/v1 and the Anthropic SDK's to the root address https
- [Model identifiers and discovery](https://platform.lyrouter.com/ai_gateway/docs/model-names/en.md): Set the request's model to a model ID in the form vendor/model (for example deepseek/deepseek-v4-flash). It is case-sensitive and must match the value shown in the model marketplace or returned by GET /v1/models characte
- [Streaming](https://platform.lyrouter.com/ai_gateway/docs/streaming/en.md): With "stream": true in the request, all three chat endpoints (Chat Completions, Responses and Anthropic Messages) return content piece by piece over SSE (Server-Sent Events). The three protocols differ in event format, e
- [Tool calls](https://platform.lyrouter.com/ai_gateway/docs/tool-call/en.md): Tool calling (function calling) lets the model request a call to a function you define, with structured arguments: your application declares tools in the request, the model returns the function name and arguments to call
- [Asynchronous tasks](https://platform.lyrouter.com/ai_gateway/docs/async/en.md): Video generation usually takes several minutes, so LYRouter provides it as asynchronous tasks: POST /v1/videos returns a task ID starting with aigwt_ right after you submit, you then query the status with GET /v1/videos/
- [Gateway headers and extensions](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers/en.md): Besides the standard OpenAI and Anthropic fields, LYRouter defines a few request headers, response headers and special model names: request headers control parameter validation, declare a session and require native passt
- [Errors and request identifiers](https://platform.lyrouter.com/ai_gateway/docs/errors/en.md): When LYRouter rejects a call, it returns a 4xx or 5xx status code. On OpenAI-compatible endpoints the error body is {"error": {"message", "type", "code"}}; on /v1/messages it is converted to the Anthropic format; a few r
- [Protocol compatibility and limits](https://platform.lyrouter.com/ai_gateway/docs/compatibility/en.md): LYRouter offers three chat endpoints, Chat Completions, Anthropic Messages and Responses, while each provider channel uses a single upstream protocol: OpenAI-compatible or Anthropic. When the client endpoint and the chan
- [Using these docs with AI tools](https://platform.lyrouter.com/ai_gateway/docs/ai-tools/en.md): Every page of these docs has a Markdown version written for AI, and there is also a site index, a full-text bundle, OpenAPI specs and an MCP server. When you ask DeepSeek, ChatGPT, Claude, Cursor, Claude Code or a simila

## 接口规格与 MCP 服务

- [OpenAPI 规格：对话、向量、重排、模型列表](https://platform.lyrouter.com/ai_gateway/api-spec/lyrouter-openapi.yaml): Chat Completions、Responses、Anthropic Messages、Embeddings、Rerank、Models，OpenAPI 3.1
- [OpenAPI 规格：多模态](https://platform.lyrouter.com/ai_gateway/api-spec/multimodal-openapi.yaml): 图像生成与编辑、视频任务等，OpenAPI 3.1
- [文档 MCP 服务](https://platform.lyrouter.com/api/v1/docs/mcp): Streamable HTTP，无需 API Key；工具 search_docs 搜索文档、get_doc 读取单页 Markdown