# API 文档

来源: https://platform.lyrouter.com/ai_gateway/docs/api-overview
更新日期: 2026-10-19

LYRouter 网关的完整接口参考。所有接口都在 `https://api.lyrouter.com` 上开放，用同一个 API Key 鉴权：对话、向量、图像接口兼容 OpenAI 格式，`/v1/messages` 兼容 Anthropic 格式，视频生成是异步任务。

## 概述

API 文档分为两组：

- **AI 模型接口**：按能力分类，每个接口一页，依次给出请求方法与路径、鉴权、请求头、请求体、请求示例、响应和常见错误。
- **通用说明**：所有接口共用的约定，包括接入地址与鉴权、模型命名、流式响应、工具调用、异步任务、网关扩展的请求头与响应头、错误码和协议兼容性，以及如何把本文档交给 AI 工具。

## AI 模型接口

| 分类 | 接口 | 说明 |
| --- | --- | --- |
| 聊天（Chat） | [Chat Completions 格式](https://platform.lyrouter.com/ai_gateway/docs/chat-completions)、[Responses 格式](https://platform.lyrouter.com/ai_gateway/docs/responses-api)、[Anthropic 格式](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages) | 三种对话协议，OpenAI SDK、Codex、Claude Code 等工具分别使用 |
| 嵌入（Embeddings） | [创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings) | 把文本转换为向量 |
| 重排（Rerank） | [文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank) | 按与查询的相关性给文档排序 |
| 图像（Images） | [图像生成](https://platform.lyrouter.com/ai_gateway/docs/images-generations)、[图像编辑](https://platform.lyrouter.com/ai_gateway/docs/images-edits) | 同步返回图片 |
| 模型（Models） | [列出模型](https://platform.lyrouter.com/ai_gateway/docs/models) | 当前 API Key 可调用的模型 |
| 视频（Videos） | [Seedance 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-seedance)、[MiniMax H3 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-minimax) | 异步任务：提交、查询、下载 |

## 通用说明

| 文档 | 内容 |
| --- | --- |
| [接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway) | Base URL、API Key 的两种写法、SDK 配置 |
| [模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names) | 模型 ID、虚拟模型、Auto 的写法与查询 |
| [流式响应](https://platform.lyrouter.com/ai_gateway/docs/streaming) | 三种对话接口的 SSE 格式与结束标记 |
| [工具调用](https://platform.lyrouter.com/ai_gateway/docs/tool-call) | 函数定义、调用与结果回传，各协议的对应关系 |
| [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) | 视频任务的状态、轮询、下载与计费 |
| [网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers) | 网关约定的请求头、响应头 |
| [错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors) | 全部报错原文与处理方法 |
| [协议兼容性与限制](https://platform.lyrouter.com/ai_gateway/docs/compatibility) | 跨协议转换时参数的保留与丢弃 |
| [在 AI 工具中使用本文档](https://platform.lyrouter.com/ai_gateway/docs/ai-tools) | 每页的 Markdown 版本、llms.txt、OpenAPI 规格与文档 MCP 服务 |

## 接入地址

| 协议 | Base URL | 示例路径 |
| --- | --- | --- |
| OpenAI 兼容（SDK 的 `base_url`） | `https://api.lyrouter.com/v1` | `/chat/completions` |
| Anthropic（SDK 的 `base_url`、`ANTHROPIC_BASE_URL`） | `https://api.lyrouter.com` | `/v1/messages` |

鉴权方式在所有接口上相同：

```text
Authorization: Bearer <API Key>
```

也可以改用 `x-api-key: <API Key>`，两者同时存在时只读 `Authorization`。详见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)。

## 全部接口

| 分类 | 方法 | 路径 | 用途 | 文档 |
| --- | --- | --- | --- | --- |
| 聊天 | POST | `/v1/chat/completions` | 对话补全 | [Chat Completions 格式](https://platform.lyrouter.com/ai_gateway/docs/chat-completions) |
| 聊天 | POST | `/v1/responses` | 对话（Responses 格式），Codex 等工具使用 | [Responses 格式](https://platform.lyrouter.com/ai_gateway/docs/responses-api) |
| 聊天 | POST | `/v1/messages` | 对话（Anthropic 格式），Claude Code 等工具使用 | [Anthropic 格式](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages) |
| 嵌入 | POST | `/v1/embeddings` | 文本向量 | [创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings) |
| 重排 | POST | `/v1/rerank` | 文档重排，服务商的 rerank 格式原样转发 | [文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank) |
| 图像 | POST | `/v1/images/generations` | 图像生成 | [图像生成](https://platform.lyrouter.com/ai_gateway/docs/images-generations) |
| 图像 | POST | `/v1/images/edits` | 图像编辑，`multipart/form-data` 或 JSON | [图像编辑](https://platform.lyrouter.com/ai_gateway/docs/images-edits) |
| 模型 | GET | `/v1/models` | 列出当前 API Key 可调用的模型 | [列出模型](https://platform.lyrouter.com/ai_gateway/docs/models) |
| 视频 | POST | `/v1/videos` | 提交视频生成任务 | [Seedance](https://platform.lyrouter.com/ai_gateway/docs/video-seedance)、[MiniMax H3](https://platform.lyrouter.com/ai_gateway/docs/video-minimax) |
| 视频 | GET | `/v1/videos/{id}` | 查询任务状态 | [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) |
| 视频 | GET | `/v1/videos/{id}/content` | 下载产物（302 跳转到产物地址） | [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) |
| 视频 | DELETE | `/v1/videos/{id}` | 对已结束的任务返回 `deleted: true`；进行中的任务不能取消 | [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) |
| 视频 | POST | `/v1/videos/regenerations` | 视频升清，仅 MiniMax H3 支持 | [MiniMax H3 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-minimax) |
| 视频 | POST | `/v1/videos/context` | 上下文增强，产出增强后的提示词，仅 MiniMax H3 支持 | [MiniMax H3 视频生成](https://platform.lyrouter.com/ai_gateway/docs/video-minimax) |

- 路径前缀也可以写成其他版本号或省略，例如 `/v4/chat/completions`、`/chat/completions` 与 `/v1/chat/completions` 相同，方便要求固定前缀的工具接入。
- 表外的 OpenAI 接口，例如 `/v1/completions`、`/v1/files`、`/v1/batches`、`/v1/moderations`，网关没有开放，请求返回 404。
- 接入地址、SDK 的 Base URL 写法见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)，网关约定的请求头、响应头见[网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers)。
- 表中对话、向量、重排、模型接口的机器可读规格见 [lyrouter-openapi.yaml](https://platform.lyrouter.com/ai_gateway/api-spec/lyrouter-openapi.yaml)（OpenAPI 3.1），图像、视频接口见 [multimodal-openapi.yaml](https://platform.lyrouter.com/ai_gateway/api-spec/multimodal-openapi.yaml)，用法见[在 AI 工具中使用本文档](https://platform.lyrouter.com/ai_gateway/docs/ai-tools#openapi-规格)。

## 能力对照

| 接口 | 虚拟模型 `@vmodel/` | Auto `lyrouter/auto` | 流式 | 执行方式 | 全部失败后改用默认模型 |
| --- | --- | --- | --- | --- | --- |
| `/v1/chat/completions` | 支持 | 支持 | 支持 | 同步 | 是 |
| `/v1/responses` | 支持 | 支持 | 支持 | 同步 | 是 |
| `/v1/messages` | 支持 | 支持 | 支持 | 同步 | 是 |
| `/v1/embeddings`、`/v1/rerank` | 支持，模型列表须为对应的向量或重排模型 | 不要使用：目前网关不拒绝，但拿不到可用结果，见[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings#网关行为) | 不支持 | 同步 | 是，但默认模型通常是对话模型，结果多为报错 |
| `/v1/images/*` | 不支持（403） | 不支持（403） | 取决于模型 | 同步 | 否 |
| `/v1/videos` 及其子接口 | 不支持（403） | 不支持（403） | 不支持 | 异步任务 | 否 |

- **虚拟模型与 Auto**：在不支持的接口上返回 403 `Model is not available in the model plaza`，请改写具体的模型 ID。详见[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)和[Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto)。
- **流式**：对话三个接口用 `stream: true` 开启，格式与结束标记见[流式响应](https://platform.lyrouter.com/ai_gateway/docs/streaming)。
- **异步任务**：视频接口提交后立即返回任务 ID，之后查询状态、下载产物，完整流程见[异步任务](https://platform.lyrouter.com/ai_gateway/docs/async)。图像接口是同步返回，但单次可能需要几分钟，客户端超时请按分钟设置。
- **失败回退**：同一模型有多个通道时，所有接口都会在通道之间依次尝试；改用其他模型只发生在对话、向量和重排接口上，见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。