LYRouter Docs

API documentation

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 format, /v1/messages is compatible with the Anthropic format, and video generation runs as asynchronous tasks.

Overview

The API documentation has two groups:

  • AI model APIs: grouped by capability, one page per endpoint. Each page gives the method and path, authentication, headers, request body, request examples, responses and common errors.
  • General: conventions shared by every endpoint, including base URLs and authentication, model identifiers, streaming, tool calls, asynchronous tasks, the request and response headers the gateway adds, error codes and protocol compatibility, and how to give these docs to AI tools.

AI model APIs

Category Endpoints Description
Chat Chat Completions format, Responses format, Anthropic format Three chat protocols, used by the OpenAI SDK, Codex, Claude Code and other tools
Embeddings Create embeddings Turn text into vectors
Rerank Rerank documents Order documents by relevance to a query
Images Create images, Edit images Images are returned synchronously
Models List models The models the current API key can call
Videos Seedance video generation, MiniMax H3 video generation Asynchronous tasks: submit, query, download

General

Document Contents
Base URLs and authentication Base URLs, the two ways to send an API key, SDK configuration
Model identifiers and discovery How to write and look up model IDs, virtual models and Auto
Streaming SSE formats and end markers of the three chat endpoints
Tool calls Defining functions, calling them and returning results, and how the protocols map
Asynchronous tasks Video task status, polling, downloads and billing
Gateway headers and extensions The request and response headers the gateway defines
Errors and request identifiers Every error message and how to handle it
Protocol compatibility and limits Which parameters are kept or dropped in cross-protocol conversion
Using these docs with AI tools The Markdown version of each page, llms.txt, the OpenAPI specs and the docs MCP server

Base URLs

Protocol Base URL Example path
OpenAI-compatible (SDK base_url) https://api.lyrouter.com/v1 /chat/completions
Anthropic (SDK base_url, ANTHROPIC_BASE_URL) https://api.lyrouter.com /v1/messages

Authentication is the same on every endpoint:

Authorization: Bearer <API Key>

You can use x-api-key: <API Key> instead; when both are present, only Authorization is read. See Base URLs and authentication.

All endpoints

Category Method Path Purpose Document
Chat POST /v1/chat/completions Chat completions Chat Completions format
Chat POST /v1/responses Chat in the Responses format, used by Codex and other tools Responses format
Chat POST /v1/messages Chat in the Anthropic format, used by Claude Code and other tools Anthropic format
Embeddings POST /v1/embeddings Text embeddings Create embeddings
Rerank POST /v1/rerank Document reranking; the provider's rerank format is forwarded as is Rerank documents
Images POST /v1/images/generations Image generation Create images
Images POST /v1/images/edits Image editing, multipart/form-data or JSON Edit images
Models GET /v1/models List the models the current API key can call List models
Videos POST /v1/videos Submit a video generation task Seedance, MiniMax H3
Videos GET /v1/videos/{id} Query a task's status Asynchronous tasks
Videos GET /v1/videos/{id}/content Download the artifact (302 redirect to the artifact URL) Asynchronous tasks
Videos DELETE /v1/videos/{id} Returns deleted: true for a finished task; a task in progress cannot be cancelled Asynchronous tasks
Videos POST /v1/videos/regenerations Video upscaling, MiniMax H3 only MiniMax H3 video generation
Videos POST /v1/videos/context Context enhancement that produces an enhanced prompt, MiniMax H3 only MiniMax H3 video generation
  • The path prefix can also use another version number or be left out: for example, /v4/chat/completions and /chat/completions are the same as /v1/chat/completions, which helps tools that require a fixed prefix.
  • OpenAI endpoints not in the table, such as /v1/completions, /v1/files, /v1/batches and /v1/moderations, are not exposed by the gateway, and requests to them return 404.
  • For base URLs and how to write the SDK Base URL, see Base URLs and authentication; for the request and response headers the gateway defines, see Gateway headers and extensions.
  • A machine-readable spec of the chat, embeddings, rerank and models endpoints in the table is lyrouter-openapi.yaml (OpenAPI 3.1); the image and video endpoints are in multimodal-openapi.yaml. See Using these docs with AI tools for how to use them.

Capability comparison

Endpoint Virtual model @vmodel/ Auto lyrouter/auto Streaming Execution Falls back to the default model after everything fails
/v1/chat/completions Supported Supported Supported Synchronous Yes
/v1/responses Supported Supported Supported Synchronous Yes
/v1/messages Supported Supported Supported Synchronous Yes
/v1/embeddings, /v1/rerank Supported; the model list must contain matching embedding or rerank models Do not use: the gateway currently does not reject it, but you get no usable result; see Create embeddings Not supported Synchronous Yes, but the default model is usually a chat model, so the result is usually an error
/v1/images/* Not supported (403) Not supported (403) Depends on the model Synchronous No
/v1/videos and its sub-endpoints Not supported (403) Not supported (403) Not supported Asynchronous task No
  • Virtual models and Auto: on endpoints that do not support them, the gateway returns 403 Model is not available in the model plaza; use a specific model ID instead. For details, see Virtual models and Auto routing.
  • Streaming: the three chat endpoints turn it on with stream: true; for formats and end markers, see Streaming.
  • Asynchronous tasks: the video endpoints return a task ID as soon as you submit, and you then query the status and download the artifact; for the full flow, see Asynchronous tasks. Image endpoints return synchronously, but a single call can take several minutes, so set client timeouts in minutes.
  • Fallback on failure: when a model has several channels, every endpoint tries the channels in turn; moving on to another model happens only on the chat, embeddings and rerank endpoints; see Retries and fallback.