# Lazu Docs
# Lazu
One API key, every major model, transparent per-lane pricing. Drop-in
OpenAI-compatible — and native Anthropic / Gemini work as-is.
- [Quickstart](/quickstart): First call in under 60 seconds.
- [Pricing & lanes](/models/pricing): Pick direct or cheap per vendor. Three-line transparent pricing on every model.
- [Files API](/endpoints/files): Upload PDFs and images, reference via file_id from Responses. 30-day retention.
- [Chat completions](/endpoints/chat): Inline endpoint reference: params, examples, streaming, tools and usage fields.
> [info]
Self-hosted Lazu uses the same paths and OpenAI-compatible client config. Just
point `base_url` at your own API domain.
## Why Lazu
- **One key, every provider.** OpenAI, Anthropic, Google, DeepSeek, Moonshot, xAI, Cloudflare Workers AI, and more.
- **Choose your lane.** `direct` (first-party / Azure / AWS / GCP) or `cheap` (lower-cost path). Pricing is transparent per lane.
- **OpenAI SDK works as-is.** Same `base_url` swap any existing project uses.
- **Native APIs too.** Anthropic `/v1/messages`, Gemini `/v1beta/...` — no proxy mismatch.
## Endpoints
| Endpoint | Use for | Docs |
| ------------------------------------------- | --------------------------------------- | ---------------------------------------- |
| `/v1/chat/completions` | OpenAI-compatible chat | [Chat](/endpoints/chat) |
| `/v1/responses` | Reasoning models + `file_id` references | [Responses](/endpoints/responses) |
| `/v1/embeddings` | Text embeddings | [Embeddings](/endpoints/embeddings) |
| `/v1/files` | Upload / list / download / delete files | [Files](/endpoints/files) |
| `/v1/audio/speech`, `/audio/transcriptions` | TTS, Whisper STT | [Explorer](/api-reference#tag/audio) |
| `/v1/images/generations`, `/images/edits` | Image generation / edit | [Explorer](/api-reference#tag/images) |
| `/v1/videos` | Async video generation jobs | [Catalog](/models/catalog) |
| `/v1/messages` | Anthropic native | [Explorer](/api-reference#tag/anthropic) |
| `/v1beta/models/{model}:generateContent` | Gemini native | [Explorer](/api-reference#tag/gemini) |
| `/v1/models`, `/api/models/catalog` | Model discovery | [Catalog](/models/catalog) |
## Base URL
```
https://api.lazu.ai
```
## Get started
1. Get an API key in the [console](https://lazu.ai/console/token).
2. (Optional) Pick a lane per vendor under the key's advanced settings.
3. Send a request — see [Quickstart](/quickstart).
# Lazu 文档
# Lazu 文档
Lazu 是统一 AI 模型网关。你可以用一个 API Key 接入主流模型 provider，同时保留 OpenAI 兼容调用、原生 provider endpoint、模型发现、额度控制和用量日志。
- Base URL: 托管版使用 https://api.lazu.ai；自部署时替换成你自己的 API 域名。
- 模型目录: GET /api/models/catalog 返回当前 API Key 真正可用的模型和能力。
- [代码示例](/zh/examples): 聊天、流式响应、多模态、错误处理和客户端封装。
- [Chat completions](/zh/endpoints/chat): 同页包含参数、示例、stream、tools 和 usage/cache 字段。
> [info]
自部署版本可以保持相同的 API path 和 OpenAI 兼容客户端配置，只需要把 base URL
换成你自己的 API 域名。
## 核心流程
1. 在 Lazu 控制台创建 API Key。
2. 调用 `GET /api/models/catalog`。
3. 根据 `modality`、`supported_endpoint_types`、`supported_endpoints`、`pricing`、`parameters` 和 `default_endpoint_type` 选择模型。
4. 按模型推荐的 endpoint 发起请求。
## 认证
最通用的鉴权方式：
```txt
Authorization: Bearer YOUR_API_KEY
```
| 接口类型 | 推荐鉴权方式 |
| ------------------ | ----------------------------------------------------- |
| OpenAI 兼容接口 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic 原生接口 | `x-api-key: YOUR_API_KEY` + `anthropic-version` |
| Gemini 原生接口 | `?key=YOUR_API_KEY` 或 `x-goog-api-key: YOUR_API_KEY` |
Token 可以限制可访问模型、额度、过期时间和 IP 白名单。给 Agent、脚本或 CI 使用时，建议单独创建受限 Token。
## 快速开始
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello from Lazu"}],
)
print(response.choices[0].message.content)
```
## 选模型
`GET /api/models/catalog` 是当前 token 的事实来源。Agent 和脚本应该优先读取 catalog，而不是猜模型名。
# Lazu 文件
# Lazu 文件
Lazu 是統一 AI 模型閘道。你可以用一把 API Key 接入主流模型 provider，同時保留
OpenAI 相容呼叫、原生 provider endpoint、模型發現、額度控管與用量記錄。
- Base URL: 託管版使用 https://api.lazu.ai；自部署時替換成你自己的 API 網域。
- 模型目錄: GET /api/models/catalog 會返回目前 API Key 實際可用的模型與能力。
- [程式碼範例](/zh-TW/examples): 聊天、串流、多模態、錯誤處理與用戶端封裝。
- [Chat completions](/zh-TW/endpoints/chat): 同頁閱讀對話請求、stream、tools、usage 與 cache 欄位。
> [info]
自部署版本可以保持相同的 API path 和 OpenAI 相容用戶端設定，只需要把 base URL
換成你自己的 API 網域。
## 核心流程
1. 在 Lazu 控制台建立 API Key。
2. 呼叫 `GET /api/models/catalog`。
3. 根據 `modality`、`supported_endpoint_types`、`supported_endpoints`、`pricing`、`parameters` 和 `default_endpoint_type` 選擇模型。
4. 依模型建議的 endpoint 發起請求。
## 認證
最通用的認證方式：
```txt
Authorization: Bearer YOUR_API_KEY
```
| 介面類型 | 建議認證方式 |
| ------------------ | ----------------------------------------------------- |
| OpenAI 相容介面 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic 原生介面 | `x-api-key: YOUR_API_KEY` + `anthropic-version` |
| Gemini 原生介面 | `?key=YOUR_API_KEY` 或 `x-goog-api-key: YOUR_API_KEY` |
## 快速開始
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello from Lazu"}],
)
print(response.choices[0].message.content)
```
## 選模型
`GET /api/models/catalog` 是目前 token 的事實來源。Agent 和腳本應優先讀取
catalog，而不是猜模型名稱。
# Lazu ドキュメント
# Lazu ドキュメント
Lazu は統合 AI モデルゲートウェイです。1 つの API Key で主要なモデル provider
に接続しつつ、OpenAI 互換呼び出し、provider ネイティブ endpoint、モデル検出、
クォータ管理、利用ログを利用できます。
- Base URL: Hosted 版は https://api.lazu.ai を使います。自社運用では自分の API ドメインに置き換えてください。
- モデルカタログ: GET /api/models/catalog は、現在の API Key で実際に利用できるモデルと機能を返します。
- [コードサンプル](/ja/examples): チャット、ストリーミング、マルチモーダル、エラー処理、クライアント実装。
- [Chat completions](/ja/endpoints/chat): リクエスト、stream、tools、usage/cache fields を 1 ページで確認できます。
> [info]
Self-hosted 版でも API path と OpenAI 互換クライアント設定は同じです。base URL
だけ自分の API ドメインに差し替えてください。
## 基本フロー
1. Lazu コンソールで API Key を作成します。
2. `GET /api/models/catalog` を呼び出します。
3. `modality`、`supported_endpoint_types`、`supported_endpoints`、`pricing`、`parameters`、`default_endpoint_type` を見てモデルを選びます。
4. モデルが推奨する endpoint にリクエストを送ります。
## 認証
最も一般的な認証方式：
```txt
Authorization: Bearer YOUR_API_KEY
```
| API スタイル | 推奨認証方式 |
| -------------------- | --------------------------------------------------------- |
| OpenAI 互換 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic ネイティブ | `x-api-key: YOUR_API_KEY` + `anthropic-version` |
| Gemini ネイティブ | `?key=YOUR_API_KEY` または `x-goog-api-key: YOUR_API_KEY` |
## クイックスタート
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello from Lazu"}],
)
print(response.choices[0].message.content)
```
## モデルを選ぶ
`GET /api/models/catalog` が現在の token の事実上の source of truth です。
Agent やスクリプトはモデル名を推測せず、catalog を先に読んでください。
# Code Examples
# Code Examples
These examples use the hosted Lazu base URL. For self-hosted deployments, replace it with your own API origin.
## OpenAI-compatible chat
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain model routing in one paragraph."},
],
)
print(response.choices[0].message.content)
```
### JavaScript
```javascript
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello from Lazu" }],
});
console.log(response.choices[0].message.content);
```
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_LAZU_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Reply with: Lazu test successful"}
]
}'
```
## Streaming
```python
stream = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "Write a short deployment checklist."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
```
## Model discovery
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_LAZU_KEY"
```
> [tip]
Use the catalog response to choose endpoint, modality and parameters. Do not
hard-code a global model list in agents or SDK wrappers.
## Troubleshooting
Every response should include `x-request-id`. Use it in the console to trace model, upstream channel, status and token accounting.
# 代码示例
# 代码示例
以下示例使用 Lazu 托管版 Base URL。自部署时，请替换成你自己的 API 域名。
## OpenAI 兼容对话
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "你是一个有帮助的助手。"},
{"role": "user", "content": "用一段话解释模型路由。"},
],
)
print(response.choices[0].message.content)
```
### JavaScript
```javascript
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello from Lazu" }],
});
console.log(response.choices[0].message.content);
```
## 流式响应
```python
stream = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "写一份简短部署 checklist。"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
```
## 模型发现
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_LAZU_KEY"
```
> [tip]
用 catalog 响应决定 endpoint、模态和参数。不要在 Agent 或 SDK wrapper
里硬编码全局模型列表。
# 程式碼範例
# 程式碼範例
以下範例使用 Lazu 託管版 Base URL。自部署時，請替換成你自己的 API 網域。
## OpenAI 相容對話
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "你是一個有幫助的助手。"},
{"role": "user", "content": "用一段話解釋模型路由。"},
],
)
print(response.choices[0].message.content)
```
### JavaScript
```javascript
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello from Lazu" }],
});
console.log(response.choices[0].message.content);
```
## 串流回應
```python
stream = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "寫一份簡短部署 checklist。"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
```
## 模型發現
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_LAZU_KEY"
```
> [tip]
用 catalog 回應決定 endpoint、模態和參數。不要在 Agent 或 SDK wrapper
裡硬編碼全域模型列表。
# コードサンプル
# コードサンプル
These examples use the hosted Lazu base URL. For self-hosted deployments, replace it with your own API domain.
## OpenAI 互換チャット
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain model routing in one paragraph."},
],
)
print(response.choices[0].message.content)
```
### JavaScript
```javascript
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello from Lazu" }],
});
console.log(response.choices[0].message.content);
```
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_LAZU_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Reply with: Lazu test successful"}
]
}'
```
## ストリーミング
```python
stream = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "Write a short deployment checklist."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
```
## モデル検索
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer YOUR_LAZU_KEY"
```
> [tip]
catalog レスポンスを使って、endpoint、モダリティ、パラメータを選んでください。
Agent や SDK wrapper
の中にグローバルなモデル一覧をハードコードしないでください。
## トラブルシューティング
すべてのレスポンスには `x-request-id` が含まれている必要があります。コンソールでこの ID を使うと、モデル、upstream channel、ステータス、トークン計上を追跡できます。
# API Explorer
# API Explorer
Pick an operation, paste your Lazu API key, and send a **real request** against
the live API. Requests go straight from your browser to `api.lazu.ai` — your
key stays in this tab (and is only persisted if you tick _Remember_).
The embedded explorer below covers the most common JSON operations. For the
complete contract, including binary upload/download APIs and provider-native
paths, use the generated `openapi.json` or `openapi.yaml` assets shipped with
the docs build.
## Compatibility matrix
"OpenAI-compatible" describes the supported request and response shapes; it
does not mean every OpenAI product endpoint exists. Unsupported routes return
HTTP `501` with an OpenAI-style error envelope.
| Capability | Status | Routes |
| ------------------------------ | ------------------ | ------------------------------------------------------------------------- |
| Chat and legacy completions | Supported | `POST /v1/chat/completions`, `POST /v1/completions` |
| Responses | Supported | `POST /v1/responses` |
| Embeddings and rerank | Supported | `POST /v1/embeddings`, `POST /v1/rerank` |
| Images | Partial | Generations and edits are supported; variations are not |
| Audio | Supported | Speech, transcription, and translation |
| Files and models | Supported | File lifecycle and model list/retrieve |
| Realtime, Anthropic, Gemini | Provider-dependent | WebSocket and native provider routes require a capable configured channel |
| Fine-tuning and model deletion | Not implemented | Fine-tune routes and `DELETE /v1/models/:model` return `501` |
Long-running interactive inference should use streaming. Work that can remain
silent for many minutes should use an asynchronous job endpoint and polling
instead of relying on an indefinitely idle HTTP connection.
Audio
OpenAI-compatible audio endpoints:
| Endpoint | Use for |
| ------------------------------- | --------------------------------- |
| `POST /v1/audio/speech` | Text-to-speech audio bytes |
| `POST /v1/audio/transcriptions` | Whisper-compatible speech-to-text |
| `POST /v1/audio/translations` | Translate audio to English |
Images
Image generation and edit endpoints:
| Endpoint | Use for |
| ----------------------------- | ------------------------- |
| `POST /v1/images/generations` | Generate images from text |
| `POST /v1/images/edits` | Edit an input image |
Videos
Async video generation job endpoints:
| Endpoint | Use for |
| -------------------- | ----------------------------- |
| `POST /v1/videos` | Create a video generation job |
| `GET /v1/videos` | List video jobs |
| `GET /v1/videos/:id` | Retrieve a video job |
Anthropic
Anthropic-native requests use `POST /v1/messages` with `x-api-key` and
`anthropic-version` headers. Model availability is still scoped by the active
Lazu API key; check [Model catalog](/models/catalog) before calling native
provider paths.
Gemini
Gemini-native requests use
`POST /v1beta/models/{model}:generateContent`. API keys can be supplied through
the OpenAI-compatible bearer header, `?key=...`, or `x-goog-api-key`.
# API Explorer
# API Explorer
选择一个操作、粘贴你的 Lazu API 密钥，直接对线上 API 发起**真实请求**。请求从浏览器直连
`api.lazu.ai`，密钥只保留在当前标签页（勾选 _Remember_ 才会持久化）。
## 兼容能力矩阵
“OpenAI-compatible”表示已支持接口遵循兼容的请求与响应格式，不代表所有 OpenAI 产品接口均已实现。未实现的路由会返回 HTTP `501` 和 OpenAI 风格错误结构。
| 能力 | 状态 | 路由 |
| --------------------------- | --------------- | --------------------------------------------------- |
| Chat 与旧版 Completions | 已支持 | `POST /v1/chat/completions`、`POST /v1/completions` |
| Responses | 已支持 | `POST /v1/responses` |
| Embeddings 与 Rerank | 已支持 | `POST /v1/embeddings`、`POST /v1/rerank` |
| Images | 部分支持 | 支持生成与编辑，不支持 variations |
| Audio | 已支持 | 语音、转录与翻译 |
| Files 与 Models | 已支持 | 文件生命周期、模型列表与查询 |
| Realtime、Anthropic、Gemini | 取决于 Provider | 需要配置具备对应能力的渠道 |
| Fine-tuning 与模型删除 | 未实现 | 返回 `501` |
长时间交互推理应使用流式响应；可能连续数分钟无输出的任务应采用异步提交与轮询，不应依赖无限空闲的 HTTP 连接。
# API Explorer
# API Explorer
選擇一個操作、貼上你的 Lazu API 金鑰，直接對線上 API 發出**真實請求**。請求從瀏覽器直連
`api.lazu.ai`，金鑰只保留在目前分頁（勾選 _Remember_ 才會保存）。
## 相容能力矩陣
「OpenAI-compatible」表示已支援介面遵循相容的請求與回應格式，不代表所有 OpenAI 產品介面均已實作。未實作的路由會回傳 HTTP `501` 與 OpenAI 風格錯誤結構。
| 能力 | 狀態 | 路由 |
| --------------------------- | --------------- | --------------------------------------------------- |
| Chat 與舊版 Completions | 已支援 | `POST /v1/chat/completions`、`POST /v1/completions` |
| Responses | 已支援 | `POST /v1/responses` |
| Embeddings 與 Rerank | 已支援 | `POST /v1/embeddings`、`POST /v1/rerank` |
| Images | 部分支援 | 支援生成與編輯，不支援 variations |
| Audio | 已支援 | 語音、轉錄與翻譯 |
| Files 與 Models | 已支援 | 檔案生命週期、模型列表與查詢 |
| Realtime、Anthropic、Gemini | 取決於 Provider | 需要設定具備對應能力的通道 |
| Fine-tuning 與模型刪除 | 未實作 | 回傳 `501` |
長時間互動推理應使用串流回應；可能連續數分鐘無輸出的任務應採用非同步提交與輪詢，不應依賴無限閒置的 HTTP 連線。
# API Explorer
# API Explorer
操作を選び、Lazu API キーを貼り付けて、ライブ API に**本物のリクエスト**を送信できます。
リクエストはブラウザから直接 `api.lazu.ai` へ送られ、キーはこのタブ内にのみ保持されます
（_Remember_ をチェックした場合のみ保存）。
## 互換性マトリクス
「OpenAI-compatible」は、対応する API のリクエストとレスポンス形式が互換であることを示します。OpenAI の全製品 API が実装済みという意味ではありません。未実装ルートは OpenAI 形式のエラーと HTTP `501` を返します。
| 機能 | 状態 | ルート |
| ----------------------------- | ------------- | --------------------------------------------------- |
| Chat / legacy Completions | 対応 | `POST /v1/chat/completions`、`POST /v1/completions` |
| Responses | 対応 | `POST /v1/responses` |
| Embeddings / Rerank | 対応 | `POST /v1/embeddings`、`POST /v1/rerank` |
| Images | 一部対応 | 生成と編集に対応、variations は未対応 |
| Audio | 対応 | 音声生成、文字起こし、翻訳 |
| Files / Models | 対応 | ファイル操作、モデル一覧と取得 |
| Realtime / Anthropic / Gemini | Provider 依存 | 対応能力を持つチャネル設定が必要 |
| Fine-tuning / モデル削除 | 未実装 | `501` を返す |
長時間の対話推論ではストリーミングを使用してください。数分間出力がない可能性のある処理は、無期限の HTTP 接続ではなく非同期ジョブとポーリングを使用します。
# Changelog
# Changelog
## 2026-05-28 — Usage metadata and cache fields
- Added normalized cache usage fields for OpenAI-compatible responses:
`cached_tokens`, `cache_write_tokens`, `cache_write_5m_tokens`,
`cache_write_1h_tokens`, and `cache_miss_tokens`.
- Added `usage_capabilities` to the model catalog so clients can discover
reported and billable dimensions before sending a request.
- Added `GET /api/usage/requests/{request_id}` for request-level usage,
billing line items, provider raw cache fields, and routing metadata.
- Documented Qwen/DashScope, DeepSeek, Anthropic, Gemini, OpenAI, and
OpenRouter cache reporting differences.
## 2026-05-12 — Static docs return to the VPS
- Restore Vocs as the active documentation app for `docs.lazu.ai`.
- Serve docs as a standalone static nginx container.
- Keep the product brand and API examples consistent across the website and docs.
## 2026-05-09 — OpenAPI reference cleanup
- Keep `packages/contracts/openapi/lazu-api-reference.v1.yaml` as the source of truth.
- Sync OpenAPI JSON/YAML into the docs public assets during build.
- Keep the interactive reference available for request and response field checks.
# 更新日志
# 更新日志
## 2026-05-28 — Usage 元数据与缓存字段
- OpenAI-compatible 响应新增标准化缓存字段：`cached_tokens`、
`cache_write_tokens`、`cache_write_5m_tokens`、`cache_write_1h_tokens`
和 `cache_miss_tokens`。
- 模型目录新增 `usage_capabilities`，调用前即可发现模型可能上报的
usage 维度和可计费维度。
- 新增 `GET /api/usage/requests/{request_id}`，用于查询单次请求的
usage 维度、账单行项目、provider 原始缓存字段和路由信息。
- 补充 Qwen/DashScope、DeepSeek、Anthropic、Gemini、OpenAI 和
OpenRouter 的缓存上报差异。
## 2026-05-12 — 静态文档回到 VPS
- 恢复 Vocs 作为 `docs.lazu.ai` 的活跃文档站。
- 通过独立 nginx 静态容器服务文档。
- 统一官网和文档里的产品品牌与 API 示例。
## 2026-05-09 — OpenAPI Reference 整理
- `packages/contracts/openapi/lazu-api-reference.v1.yaml` 继续作为事实来源。
- 构建时同步 OpenAPI JSON/YAML 到 docs public assets。
- 保留交互式 reference，用于查请求和响应字段。
# 更新日誌
# 更新日誌
## 2026-05-28 — Usage 中繼資料與快取欄位
- OpenAI-compatible 回應新增標準化快取欄位：`cached_tokens`、
`cache_write_tokens`、`cache_write_5m_tokens`、`cache_write_1h_tokens`
和 `cache_miss_tokens`。
- 模型目錄新增 `usage_capabilities`，呼叫前即可查詢模型可能回報的
usage 維度與可計費維度。
- 新增 `GET /api/usage/requests/{request_id}`，可查詢單次請求的
usage 維度、帳單明細、provider 原始快取欄位和路由資訊。
- 補充 Qwen/DashScope、DeepSeek、Anthropic、Gemini、OpenAI 和
OpenRouter 的快取回報差異。
## 2026-05-12 — 靜態文件回到 VPS
- 恢復 Vocs 作為 `docs.lazu.ai` 的活躍文件站。
- 透過獨立 nginx 靜態容器服務文件。
- 統一官網和文件裡的產品品牌與 API 範例。
## 2026-05-09 — OpenAPI Reference 整理
- `packages/contracts/openapi/lazu-api-reference.v1.yaml` 繼續作為事實來源。
- 構建時同步 OpenAPI JSON/YAML 到 docs public assets。
- 保留互動式 reference，用於查請求和回應欄位。
# 更新履歴
# 更新履歴
## 2026-05-28 — Usage メタデータとキャッシュフィールド
- OpenAI-compatible レスポンスに標準化されたキャッシュフィールド
`cached_tokens`、`cache_write_tokens`、`cache_write_5m_tokens`、
`cache_write_1h_tokens`、`cache_miss_tokens` を追加。
- モデルカタログに `usage_capabilities` を追加し、リクエスト前に
報告可能な usage ディメンションと課金対象ディメンションを確認可能に。
- `GET /api/usage/requests/{request_id}` を追加し、リクエスト単位の
usage、課金明細、provider raw cache fields、routing metadata を確認可能に。
- Qwen/DashScope、DeepSeek、Anthropic、Gemini、OpenAI、OpenRouter
のキャッシュ報告差異をドキュメント化。
## 2026-05-12 — 静的ドキュメントを VPS に戻す
- `docs.lazu.ai` のアクティブなドキュメントアプリとして Vocs を復元。
- ドキュメントを独立した静的 nginx コンテナとして配信。
- Web サイトとドキュメントのプロダクトブランドと API 例を統一。
## 2026-05-09 — OpenAPI リファレンスの整理
- `packages/contracts/openapi/lazu-api-reference.v1.yaml` を信頼できる唯一のソースとして維持。
- build 時に OpenAPI JSON/YAML を docs の public assets に同期。
- リクエストとレスポンスのフィールド確認に使えるインタラクティブリファレンスを維持。
# Authentication
# Authentication
Every Lazu request needs an API key. Create one in the
[console](https://lazu.ai/console/token). Keys look like `sk-lazu-…`.
## Headers by API style
| API style | Header |
| ----------------- | ----------------------------------------------------------- |
| OpenAI-compatible | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic native | `x-api-key: YOUR_API_KEY` + `anthropic-version: 2023-06-01` |
| Gemini native | `x-goog-api-key: YOUR_API_KEY` or query `?key=…` |
All three are accepted by Lazu — pick whichever your client SDK already speaks.
## Recommended setup
- **Use a dedicated key per app / environment**. A key compromised in CI
should not also let attackers into prod.
- **Restrict the key.** Each key can scope to specific models, quota cap,
expiration time, IP allowlist and a per-vendor lane preference. See
[API keys settings](https://lazu.ai/console/token).
- **Never commit keys to git**. Use environment variables, secret managers
or vendor-specific secret stores.
## Storing the key
Shell:
```bash
export LAZU_API_KEY=sk-lazu-...
```
`.env` file (gitignored):
```
LAZU_API_KEY=sk-lazu-...
```
Python / Node SDK code: read from env, do not hardcode.
```python
api_key = os.environ["LAZU_API_KEY"]
```
```ts
const apiKey = process.env.LAZU_API_KEY!;
```
## Verifying
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
A 200 response with a JSON model list means the key is live. A 401 with
`invalid_api_key` means it's been disabled, expired or never existed —
check the console.
## Rotation
If a key leaks: open the console, **delete** the compromised key, create a
fresh one, and update your deployments. There is no "rotate in place" — old
key is dead the moment you delete it.
# 鉴权
# 鉴权
所有 Lazu 请求都需要 API Key。你可以在
[控制台](https://lazu.ai/console/token) 创建 key，key 通常以
`sk-lazu-` 开头。
## 不同 API 风格的鉴权方式
| API 风格 | Header 或参数 |
| ------------------ | ----------------------------------------------------------- |
| OpenAI 兼容接口 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic 原生接口 | `x-api-key: YOUR_API_KEY` + `anthropic-version: 2023-06-01` |
| Gemini 原生接口 | `x-goog-api-key: YOUR_API_KEY` 或 query `?key=...` |
三种方式都由 Lazu 接收。实际使用时，选择你当前 SDK 已经支持的格式即可。
## 推荐设置
- **每个应用和环境单独创建 key**。CI、测试环境和生产环境不要共用同一个 key。
- **限制 key 的权限**。Token 可以配置可访问模型、额度、过期时间、IP 白名单和 vendor lane 偏好。
- **不要把 key 提交到 git**。使用环境变量、secret manager 或部署平台的密钥存储。
## 存储 key
Shell:
```bash
export LAZU_API_KEY=sk-lazu-...
```
`.env` 文件（确保已被 gitignore）:
```txt
LAZU_API_KEY=sk-lazu-...
```
SDK 代码中从环境变量读取，不要硬编码：
```python
api_key = os.environ["LAZU_API_KEY"]
```
```ts
const apiKey = process.env.LAZU_API_KEY!;
```
## 验证 key
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
如果返回 200 和 JSON 模型列表，说明 key 可用。若返回 401
`invalid_api_key`，通常表示 key 被禁用、过期、格式错误或不存在。
## 更换泄露的 key
如果 key 泄露，进入控制台删除旧 key，创建新 key，再更新部署环境。删除后旧 key
立即失效；当前版本不提供原地 rotate。
# 認證
# 認證
所有 Lazu 請求都需要 API Key。你可以在
[控制台](https://lazu.ai/console/token) 建立 key，key 通常以 `sk-lazu-` 開頭。
## 不同 API 風格的認證方式
| API 風格 | Header 或參數 |
| ------------------ | ----------------------------------------------------------- |
| OpenAI 相容介面 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic 原生介面 | `x-api-key: YOUR_API_KEY` + `anthropic-version: 2023-06-01` |
| Gemini 原生介面 | `x-goog-api-key: YOUR_API_KEY` 或 query `?key=...` |
三種方式都由 Lazu 接收。實際使用時，選擇目前 SDK 已支援的格式即可。
## 建議設定
- **每個應用和環境單獨建立 key**。CI、測試環境和生產環境不要共用同一把 key。
- **限制 key 的權限**。Token 可以設定可存取模型、額度、過期時間、IP 白名單和 vendor lane 偏好。
- **不要把 key 提交到 git**。使用環境變數、secret manager 或部署平台的密鑰存儲。
## 儲存 key
Shell:
```bash
export LAZU_API_KEY=sk-lazu-...
```
`.env` 檔案（確保已被 gitignore）:
```txt
LAZU_API_KEY=sk-lazu-...
```
SDK 程式碼中從環境變數讀取，不要硬編碼。
## 驗證 key
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
如果返回 200 和 JSON 模型列表，表示 key 可用。若返回 401
`invalid_api_key`，通常表示 key 被停用、過期、格式錯誤或不存在。
## 更換外洩的 key
如果 key 外洩，進入控制台刪除舊 key，建立新 key，再更新部署環境。刪除後舊 key
立即失效；目前版本不提供原地 rotate。
# 認証
# 認証
すべての Lazu リクエストには API Key が必要です。
[コンソール](https://lazu.ai/console/token)で作成できます。key は通常
`sk-lazu-` で始まります。
## API スタイルごとの認証
| API スタイル | Header またはパラメータ |
| -------------------- | ----------------------------------------------------------- |
| OpenAI 互換 | `Authorization: Bearer YOUR_API_KEY` |
| Anthropic ネイティブ | `x-api-key: YOUR_API_KEY` + `anthropic-version: 2023-06-01` |
| Gemini ネイティブ | `x-goog-api-key: YOUR_API_KEY` または query `?key=...` |
Lazu は 3 つの形式を受け付けます。利用中の SDK が既に扱える形式を選んでください。
## 推奨設定
- **アプリと環境ごとに key を分ける**。CI、staging、本番で同じ key を共有しないでください。
- **key を制限する**。モデル、quota、期限、IP allowlist、vendor lane preference を設定できます。
- **git に key をコミットしない**。環境変数や secret manager を使ってください。
## key の保存
```bash
export LAZU_API_KEY=sk-lazu-...
```
`.env` ファイルを使う場合は必ず gitignore してください。
## key の確認
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
200 と JSON のモデル一覧が返れば key は有効です。401 `invalid_api_key` は、key が
無効、期限切れ、形式不正、または存在しないことを意味します。
## 漏洩時の対応
key が漏洩した場合は、コンソールで古い key を削除し、新しい key を作成してデプロイ先を更新してください。
削除後、古い key は即座に無効になります。
# How pricing works
# How pricing works
Lazu's billing is **prepaid** and **per-token** (or per-call for certain
image/audio models). You top up balance, every API call deducts at the
model's lane price, and your dashboard shows usage in real time.
## The basic formula
```
final_charge_microUSD =
(input_tokens × input_price_per_mtok)
+ (output_tokens × output_price_per_mtok)
+ (cache_read_tokens × cache_read_price_per_mtok)
+ (cache_write_5m_tokens × cache_write_5m_price_per_mtok)
+ (cache_write_1h_tokens × cache_write_1h_price_per_mtok)
+ (audio_tokens × audio_price_per_mtok)
+ (image_input_tokens × image_input_price_per_mtok)
+ (per_call_charge if any)
```
All amounts internally are **microUSD** (1 USD = 1,000,000 microUSD) so we
can be precise even on cents-fractional tokens. Your dashboard displays USD.
Prices come from `model_sell_prices[model_name, channel_group]` — see
[Pricing & lanes](/models/pricing) for the per-lane breakdown.
## Refund rules
| Upstream outcome | What you pay |
| ---------------------------------------------------- | ------------------------------------------------------------- |
| `2xx` success | Full price by upstream-reported usage |
| Streamed, then disconnect, **with** usage in trailer | Pay for the tokens actually streamed |
| Streamed, then disconnect, **no** usage trailer | **Refund** — you pay 0 |
| `5xx` / timeout / network error | **Refund** — you pay 0 |
| `4xx` (content policy / bad request) | **Refund** — you pay 0 even if upstream charged us internally |
| Per-call image / audio model error | Charged at full per-call rate (see "Known edge case" below) |
In practice this means: if Lazu returned `200` to you, you pay; if Lazu
returned `4xx`, `5xx` or a timeout, you don't.
## Usage and cache fields
OpenAI-compatible inference responses keep the standard `usage` shape and add
optional cache fields when the upstream reports them:
```json
{
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 300,
"total_tokens": 1500,
"prompt_tokens_details": {
"cached_tokens": 300,
"cache_write_tokens": 100,
"cache_write_5m_tokens": 100,
"cache_miss_tokens": 800
}
}
}
```
`cached_tokens` means cache reads. `cache_write_tokens`,
`cache_write_5m_tokens`, and `cache_write_1h_tokens` mean cache creation/write
tokens. `cache_miss_tokens` is analytical and appears only when the provider
reports misses separately.
For a complete reconciliation record, call:
```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```
The request detail response includes normalized `usage.dimensions`,
`billing.line_items`, compact `provider_usage.raw_fields`, and routing
metadata for the same API key that made the request.
> [warning]
**Known edge case**: a small number of image-generation and audio models
charge per-call (not per-token). If upstream fails mid-generation, you may
still be charged the full per-call amount. We're working on this; for now,
treat per-call models as best-effort billed.
## Search billing
`POST /v1/search` records a `web_search` line item from the selected search
backend. The charge amount is based on the backend's configured
`search_price`, or provider-cost passthrough when an operator enables it. The
hosted Tavily, Serper and Jina search backends currently do not have an explicit
`search_price`, so their search line item is $0 while usage is still recorded.
Search responses include two usage fields:
```json
{
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
}
}
```
- `web_search_requests` is the Lazu request count, usually `1`.
- `web_search_billable_units` is the provider billing quantity used for the
charge.
- Tavily `basic` search is 1 unit; Tavily `advanced` search is 2 units.
- Serper is normally 1 unit per successful query.
- Jina is normally 1 unit per successful query.
See [Search](/endpoints/search) for request fields and routing details.
## Top-up
Top up with a card via Stripe in the
[console](https://lazu.ai/console/topup). Funds appear instantly in your
balance.
- Minimum top-up: $5
- No expiration on credits
- Refunds: open a ticket within 7 days for failed-but-charged calls
Funded accounts are **verified** and immediately move from `Unverified`
(5 RPM cap) to the tier matching their lifetime top-up total. See
[Rate limits](/limits).
## Free credits
New accounts get a small free trial credit ($X, see console for current
amount). This is enough to test 100-ish basic chat calls. Free credit:
- Counts as balance — you can use it on any model in any lane
- Does **not** verify the account — to escape the 5 RPM cap, complete a
real top-up
- Does not expire, but if you cap out without topping up, the account stays
rate-limited
## Where to see usage
- **Console → Usage**: per-day, per-model, per-key breakdown
- **Console → Billing**: invoices, top-up history, current balance
- **API**: `GET /api/usage/requests/{request_id}` (see [Request details](/endpoints/usage-requests))
## What's NOT layered on top
Lazu's bill is **just** input × price + output × price (etc., per the
formula above). There is no:
- "Premium tier discount" stacking on top of lane price
- "Loyalty multiplier" that reduces price over time
- Hidden margin per cache read or per audio token beyond the listed
per-mtok rate
- Surcharge on weekends, regions, or model size
If you see a charge that doesn't match `tokens × listed_price`, that's a
bug — open a ticket.
## Streaming partial usage
When you call with `stream: true`:
- Tokens flush to your balance in real time as they're generated.
- If the client disconnects mid-stream, Lazu still bills for what was
delivered (provided upstream reported it in a final `usage` trailer).
- If upstream errors before any tokens reach you, you're refunded.
This means an aborted stream of 1,000 tokens after the user clicked
"Cancel" still costs roughly 1,000 × output_price. The model already did
the work; the client just stopped reading.
## Enterprise / volume contracts
For workloads sustained above $1,000/month, contact sales via
[lazu.ai](https://lazu.ai/) — volume terms negotiated case by case.
## See also
- [Pricing & lanes](/models/pricing)
- [Rate limits](/limits)
- [Errors](/errors)
# 计费规则
# 计费规则
Lazu 采用**预付费**和**按 token 计费**。部分图片、音频或搜索能力按调用或
provider billing unit 计费。你先充值余额，每次 API 调用按模型和 lane 的价格扣费，
控制台实时展示用量。
## 基本公式
```txt
final_charge_microUSD =
input_tokens * input_price_per_mtok
+ output_tokens * output_price_per_mtok
+ cache_read_tokens * cache_read_price_per_mtok
+ cache_write_5m_tokens * cache_write_5m_price_per_mtok
+ cache_write_1h_tokens * cache_write_1h_price_per_mtok
+ audio_tokens * audio_price_per_mtok
+ image_input_tokens * image_input_price_per_mtok
+ per_call_charge
```
内部金额使用 **microUSD**（1 USD = 1,000,000 microUSD），避免小数精度问题。
控制台展示为 USD。
## 退款规则
| 上游结果 | 你支付什么 |
| ------------------------------------------ | ----------------------------- |
| `2xx` 成功 | 按上游返回的 usage 计费 |
| stream 中断，但最终 trailer 有 usage | 按已经生成并上报的 token 计费 |
| stream 中断且没有 usage trailer | 退款，支付 0 |
| `5xx`、timeout、网络错误 | 退款，支付 0 |
| `4xx`、内容策略、bad request | 退款，支付 0 |
| 少数按调用计费的图片或音频模型上游中途失败 | 可能按完整 per-call 计费 |
如果 Lazu 返回 `200`，通常需要支付；如果 Lazu 返回 `4xx`、`5xx` 或 timeout，
通常不会扣费。
## Usage 和 cache 字段
OpenAI 兼容响应会保留标准 `usage`，并在 provider 上报时附加 cache 字段：
```json
{
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 300,
"total_tokens": 1500,
"prompt_tokens_details": {
"cached_tokens": 300,
"cache_write_tokens": 100,
"cache_write_5m_tokens": 100,
"cache_miss_tokens": 800
}
}
}
```
`cached_tokens` 表示 cache read；`cache_write_tokens`、`cache_write_5m_tokens`
和 `cache_write_1h_tokens` 表示 cache creation/write。完整对账请调用：
```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```
请求详情会返回标准化的 `usage.dimensions`、`billing.line_items`、
`provider_usage.raw_fields` 和 routing metadata。
> [warning]
少数图片生成和音频模型按调用计费。如果上游已经开始生成后失败，可能仍会产生完整
per-call 费用。生产环境使用这类模型时，请把它们当作 best-effort billed 能力。
## Search 计费
`POST /v1/search` 会记录选中 search backend 对应的 `web_search` line item。
实际费用取决于 backend 配置的 `search_price`，或管理员启用的 provider-cost
passthrough。当前托管版 Tavily、Serper 和 Jina 没有显式配置 `search_price`，
所以 search line item 为 $0，但 usage 仍会记录。响应会包含：
```json
{
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
}
}
```
- `web_search_requests` 是 Lazu 请求次数，通常为 `1`。
- `web_search_billable_units` 是 provider 实际计费用量。
- Tavily `basic` = 1 unit，`advanced` = 2 units。
- Serper 通常每次成功 query = 1 unit。
- Jina 通常每次成功 query = 1 unit。
## 充值和免费额度
通过 [控制台](https://lazu.ai/console/topup) 使用 Stripe 充值。充值成功后余额立即可用。
- 最低充值：$5
- 余额不过期
- 新账号可能有试用额度，但试用额度不等于完成验证
- 要解除未验证账号的低频率限制，需要完成一次真实充值
## 查看用量
- **Console -> Usage**：按天、模型、API Key 查看用量。
- **Console -> Billing**：发票、充值历史和当前余额。
- **API**：`GET /api/usage/requests/{request_id}`。
## 不会额外叠加的东西
Lazu 不会在 lane 价格上再叠加隐藏费用：
- 不额外收取 premium tier surcharge
- 不按周末、地区或模型大小加价
- 不对 cache read 或 audio token 额外加隐藏 markup
如果实际扣费和 `tokens * listed_price` 对不上，请带 `request_id` 联系支持。
## 相关页面
- [定价与渠道](/zh/models/pricing)
- [请求频率限制](/zh/limits)
- [错误码](/zh/errors)
# 計費規則
# 計費規則
Lazu 採用**預付費**和**按 token 計費**。部分圖片、音訊或搜尋能力按呼叫或
provider billing unit 計費。你先儲值餘額，每次 API 呼叫按模型和 lane 的價格扣費，
控制台即時展示用量。
## 基本公式
```txt
final_charge_microUSD =
input_tokens * input_price_per_mtok
+ output_tokens * output_price_per_mtok
+ cache_read_tokens * cache_read_price_per_mtok
+ cache_write_5m_tokens * cache_write_5m_price_per_mtok
+ cache_write_1h_tokens * cache_write_1h_price_per_mtok
+ audio_tokens * audio_price_per_mtok
+ image_input_tokens * image_input_price_per_mtok
+ per_call_charge
```
內部金額使用 **microUSD**（1 USD = 1,000,000 microUSD），避免小數精度問題。
控制台展示為 USD。
## 退款規則
| 上游結果 | 你支付什麼 |
| ------------------------------------------ | --------------------------- |
| `2xx` 成功 | 按上游返回的 usage 計費 |
| stream 中斷，但最終 trailer 有 usage | 按已生成並上報的 token 計費 |
| stream 中斷且沒有 usage trailer | 退款，支付 0 |
| `5xx`、timeout、網路錯誤 | 退款，支付 0 |
| `4xx`、內容政策、bad request | 退款，支付 0 |
| 少數按呼叫計費的圖片或音訊模型上游中途失敗 | 可能按完整 per-call 計費 |
## Usage 和 cache 欄位
OpenAI 相容回應會保留標準 `usage`，並在 provider 上報時附加 cache 欄位：
```json
{
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 300,
"total_tokens": 1500,
"prompt_tokens_details": {
"cached_tokens": 300,
"cache_write_tokens": 100,
"cache_write_5m_tokens": 100,
"cache_miss_tokens": 800
}
}
}
```
完整對帳請呼叫：
```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```
請求詳情會返回標準化的 `usage.dimensions`、`billing.line_items`、
`provider_usage.raw_fields` 和 routing metadata。
> [warning]
少數圖片生成和音訊模型按呼叫計費。如果上游已經開始生成後失敗，可能仍會產生完整
per-call 費用。生產環境使用這類模型時，請把它們視為 best-effort billed 能力。
## Search 計費
`POST /v1/search` 會記錄選中 search backend 對應的 `web_search` line item。
實際費用取決於 backend 設定的 `search_price`，或管理員啟用的 provider-cost
passthrough。目前託管版 Tavily、Serper 和 Jina 沒有明確設定 `search_price`，
所以 search line item 為 $0，但 usage 仍會記錄。響應會包含
`web_search_requests` 和 `web_search_billable_units`。Tavily `basic` 為 1 unit，
`advanced` 為 2 units；Serper 和 Jina 通常每次成功 query 為 1 unit。
## 儲值和免費額度
透過 [控制台](https://lazu.ai/console/topup) 使用 Stripe 儲值。儲值成功後餘額立即可用。
試用額度可用於測試，但不等於完成帳號驗證；要解除未驗證帳號的低頻率限制，需要完成一次真實儲值。
## 相關頁面
- [定價與通道](/zh-TW/models/pricing)
- [請求頻率限制](/zh-TW/limits)
- [錯誤碼](/zh-TW/errors)
# 料金体系
# 料金体系
Lazu は**プリペイド**で、基本的には**token 単位**で課金します。一部の画像、
音声、検索機能は per-call または provider billing unit で課金されます。残高をチャージし、
各 API 呼び出しがモデルと lane の価格に基づいて差し引かれます。
## 基本式
```txt
final_charge_microUSD =
input_tokens * input_price_per_mtok
+ output_tokens * output_price_per_mtok
+ cache_read_tokens * cache_read_price_per_mtok
+ cache_write_5m_tokens * cache_write_5m_price_per_mtok
+ cache_write_1h_tokens * cache_write_1h_price_per_mtok
+ audio_tokens * audio_price_per_mtok
+ image_input_tokens * image_input_price_per_mtok
+ per_call_charge
```
内部金額は **microUSD**（1 USD = 1,000,000 microUSD）で扱い、表示時に USD に丸めます。
## 返金ルール
| upstream の結果 | 課金内容 |
| ----------------------------------------- | -------------------------------------- |
| `2xx` success | upstream が報告した usage に基づき課金 |
| stream が途中終了し、usage trailer がある | 生成済み token 分を課金 |
| stream が途中終了し、usage trailer がない | 返金、0 課金 |
| `5xx`、timeout、network error | 返金、0 課金 |
| `4xx`、content policy、bad request | 返金、0 課金 |
| 一部 per-call 画像/音声モデルの途中失敗 | full per-call 課金になる場合があります |
## Usage と cache fields
OpenAI 互換レスポンスは標準の `usage` を保持し、provider が報告した場合に cache field
を追加します。
```json
{
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 300,
"total_tokens": 1500,
"prompt_tokens_details": {
"cached_tokens": 300,
"cache_write_tokens": 100,
"cache_write_5m_tokens": 100,
"cache_miss_tokens": 800
}
}
}
```
完全な照合には request detail API を使います。
```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```
> [warning]
一部の画像生成・音声モデルは per-call 課金です。upstream
が生成を開始したあとに失敗した場合でも、 full per-call
の課金になることがあります。
## Search 課金
`POST /v1/search` は、選択された search backend の `web_search` line item
を記録します。実際の charge は backend の `search_price`、または operator
が有効化した provider-cost passthrough に基づきます。現在の hosted Tavily、
Serper、Jina には明示的な `search_price` が設定されていないため、search
line item は $0 ですが usage は記録されます。Tavily `basic` は 1 unit、
`advanced` は 2 units、Serper と Jina は通常 1 successful query = 1 unit です。
## チャージと無料クレジット
[コンソール](https://lazu.ai/console/topup)から Stripe でチャージできます。無料クレジットはテストに使えますが、
未認証アカウントの低い rate limit を解除するには実際の支払いが必要です。
## 関連ページ
- [料金と経路](/ja/models/pricing)
- [レート制限](/ja/limits)
- [エラーコード](/ja/errors)
# Chat completions
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
} from "../../components/mdx";
}
>
## Basic configuration
Use https://api.lazu.ai/v1 with OpenAI SDKs, or call the full
path https://api.lazu.ai/v1/chat/completions directly.
Read GET /api/models/catalog at runtime. Filter entries where
supported_endpoint_types contains chat.
## Request body
Model ID, route alias or future route policy name. For explicit models, pass
IDs from GET /api/models/catalog. For SDK compatibility,
/v1/models remains available as a flat list.
Ordered conversation messages. Roles follow the OpenAI shape:
system, user, assistant, and
tool.
When true, Lazu forwards a Server-Sent Events stream and ends
with data: [DONE].
Function/tool definitions. Check parameters.tools in the model
catalog before sending tools to a model.
OpenAI-compatible tool choice control. Use auto,
none, required, or a named tool object when the
selected model supports it.
Structured output control. Use {'{"type":"json_object"}'}
or a JSON schema object when the model supports strict structured output.
Sampling temperature. Most models accept 0 to 2,
but provider-specific limits can differ.
Maximum generated tokens. The final cap is still bounded by the selected
model's context and output limits.
Use {'{"include_usage":true}'} when the upstream supports
streaming usage trailers.
## Message content
Message role.
Plain text for text-only turns, or an array of content parts for multimodal
requests.
Assistant tool calls returned by the model.
Required on tool messages so the model can associate a tool
result with the earlier tool call.
## Vision input
For image input, send OpenAI-compatible content parts. Use either HTTPS image
URLs or data URLs:
{`{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {"url": "data:image/png;base64,..."}
}
]
}
]
}`}
For PDFs and large documents, upload through [Files](/endpoints/files) and use
[Responses](/endpoints/responses). Chat completions does not automatically
dereference file_id.
## Tools
{`{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Weather in Tokyo?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
}
]
}`}
Tool support is not universal. Prefer /api/models/catalog and look
at parameters.tools before routing agent traffic.
## Response
Lazu or provider response ID. Use the response header
X-Lazu-Request-Id for request-level reconciliation.
Assistant output choices. Streaming responses send incremental
delta objects.
Prompt input tokens.
Generated output tokens.
Cache read tokens when the upstream reports them.
Cache creation/write tokens when the upstream reports them.
Cache misses when the provider reports them separately, for example
DeepSeek-compatible usage.
For complete usage, billing line items, provider raw usage fields and routing
metadata, call:
{`curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \\
-H "Authorization: Bearer $LAZU_API_KEY"`}
## Errors
Relay errors use OpenAI-compatible error envelopes where possible and include a
request ID. See [Errors](/errors) for code meanings and retry behavior.
## See also
- [Model catalog](/models/catalog)
- [Responses API](/endpoints/responses)
- [Billing and cache fields](/billing)
- [Request details](/endpoints/usage-requests)
# Chat completions
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
} from "../../../components/mdx";
}
>
## 基础配置
OpenAI SDK 使用 https://api.lazu.ai/v1。
生产代码应先读取 GET /api/models/catalog，筛选
supported_endpoint_types 包含 chat 的模型。
## 请求 Body
模型 ID，来自 GET /api/models/catalog。后续也可以承载
auto 或 route policy 名称。
对话消息数组。role 使用 OpenAI 兼容格式：
system、user、assistant、
tool。
设置为 true 时返回 SSE 流式响应，结尾为
data: [DONE]。
工具/函数定义。发送前建议检查模型目录里的
parameters.tools。
结构化输出控制，例如 {'{"type":"json_object"}'}。
采样温度。不同 provider 的有效范围可能不同。
最大输出 token，仍受模型上下文和输出限制约束。
## 消息格式
消息角色。
文本消息可直接传字符串；多模态请求可传 content parts。
assistant 消息里的工具调用。
tool 消息需要带这个字段，用来对应上一轮 tool call。
## 图片输入
{`{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {"url": "data:image/png;base64,..."}
}
]
}
]
}`}
PDF 和大文件应该使用 [Files](/zh/endpoints/files) +
[Responses](/zh/endpoints/responses)。Chat completions 不会自动读取
file_id。
## 响应 usage 和 cache 字段
输入 token。
输出 token。
cache read tokens。
provider 上报时返回的 cache write tokens。
provider 明确上报 cache miss 时返回，例如 DeepSeek 兼容字段。
完整对账信息使用请求详情 API：
{`curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \\
-H "Authorization: Bearer $LAZU_API_KEY"`}
## 相关页面
- [模型目录](/zh/models/catalog)
- [Responses API](/zh/endpoints/responses)
- [计费规则](/zh/billing)
- [请求详情](/zh/endpoints/usage-requests)
# Chat completions
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
} from "../../../components/mdx";
}
>
## 基本設定
使用 https://api.lazu.ai/v1 搭配 OpenAI SDK，或直接呼叫完整
path https://api.lazu.ai/v1/chat/completions。
執行時讀取 GET /api/models/catalog，並篩選
supported_endpoint_types 包含 chat 的模型。
## 請求 Body
模型 ID、route alias 或未來的 route policy 名稱。建議從
GET /api/models/catalog 讀取。
有序對話訊息。角色遵循 OpenAI shape。
為 true 時返回 Server-Sent Events stream，最後以
data: [DONE] 結束。
Function/tool 定義。送出前先檢查模型 catalog 中的{" "}
parameters.tools。
OpenAI-compatible tool choice 控制，例如 auto、
none
或指定工具物件。
Structured output 控制，例如 {'{"type":"json_object"}'}。
取樣溫度，多數模型接受 0 到 2。
產生 token 上限，仍受模型 context 和 output limit 限制。
## Vision input
圖片輸入使用 OpenAI-compatible content parts。可以傳 HTTPS 圖片 URL 或 data URL：
{`{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {"url": "data:image/png;base64,..."}
}
]
}
]
}`}
PDF 和大型文件請透過 [Files](/zh-TW/endpoints/files) 上傳，並使用
[Responses](/zh-TW/endpoints/responses)。Chat completions 不會自動解引用
file_id。
## Response
Lazu 或 provider response ID。
Assistant output choices。Streaming response 會送出增量 delta。
輸入 token 數。
輸出 token 數。
上游回報時的 cache read token。
完整對帳請使用 [請求詳情](/zh-TW/endpoints/usage-requests)。
## 相關頁面
- [模型目錄](/zh-TW/models/catalog)
- [Responses API](/zh-TW/endpoints/responses)
- [錯誤碼](/zh-TW/errors)
# Chat completions
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
} from "../../../components/mdx";
}
>
## 基本設定
OpenAI SDK では https://api.lazu.ai/v1{" "}
を使います。直接呼ぶ場合は
https://api.lazu.ai/v1/chat/completions です。
実行時に GET /api/models/catalog を読み、
supported_endpoint_types に chat{" "}
を含むモデルを選びます。
## Request body
model ID、route alias、または route policy name。明示的な model は
GET /api/models/catalog から選びます。
OpenAI shape の会話メッセージ配列です。
true の場合、Server-Sent Events stream を返し、最後に
data: [DONE] を送ります。
tool 定義です。送信前に catalog の parameters.tools{" "}
を確認してください。
auto、none、指定 tool object など。
structured output control。例：{'{"type":"json_object"}'}。
sampling temperature。多くの model は 0 から 2{" "}
を受け付けます。
生成 token の上限です。
## Vision input
画像入力は OpenAI-compatible content parts を使います。HTTPS image URL または data URL
を送れます。
{`{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {"url": "data:image/png;base64,..."}
}
]
}
]
}`}
PDF や大きな document は [Files](/ja/endpoints/files) で upload し、
[Responses](/ja/endpoints/responses) で参照してください。Chat completions は
file_id を自動 dereference しません。
## Response
Lazu または provider response ID。
assistant output choices。Streaming では incremental delta{" "}
です。
input token count。
generated output token count。
provider が報告した cache read tokens。
完全な照合には [リクエスト詳細](/ja/endpoints/usage-requests) を使ってください。
# Embeddings
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
supported_endpoint_types includes{" "}
embeddings
}
/>
}
>
## Request body
Embedding model ID from /api/models/catalog.
Text input or ordered batch of text inputs. The response preserves order.
Optional vector dimension for models that support truncation.
Output encoding format when supported by the upstream provider.
## Response
Usually list.
One embedding item per input.
Vector values or base64-encoded vector depending on
encoding_format.
Input tokens used for embedding.
## Batch guidance
Pass an array for small batches. For large data jobs, chunk client-side so each
request stays within provider body-size and token limits.
## Common models
| Model | Dim | Notes |
| ------------------------ | ---- | -------------------- |
| `BAAI/bge-m3` | 1024 | Multilingual |
| `text-embedding-3-small` | 1536 | OpenAI cheap default |
| `text-embedding-3-large` | 3072 | OpenAI high quality |
| `gemini-embedding-001` | 768 | Google default |
## See also
- [Model catalog](/models/catalog)
- [Pricing & lanes](/models/pricing)
# Embeddings
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
supported_endpoint_types 包含 embeddings
}
/>
}
>
## 请求 Body
来自 /api/models/catalog 的 embedding 模型 ID。
文本输入，或有序文本批量输入。响应会保持输入顺序。
支持截断的模型可使用可选向量维度。
上游支持时可选择输出编码格式。
## 响应
通常为 list。
每个 input 对应一个 embedding item。
向量数值，或取决于 encoding_format 的 base64 编码向量。
embedding 使用的输入 token 数。
## 批量建议
小批量可以直接传数组。大规模数据任务建议在客户端分块，确保每个请求都不超过
provider 的 body size 和 token 限制。
## 常见模型
| Model | Dim | Notes |
| ------------------------ | ---- | -------------------- |
| `BAAI/bge-m3` | 1024 | Multilingual |
| `text-embedding-3-small` | 1536 | OpenAI cheap default |
| `text-embedding-3-large` | 3072 | OpenAI high quality |
| `gemini-embedding-001` | 768 | Google default |
## 相关页面
- [模型目录](/zh/models/catalog)
- [定价与渠道](/zh/models/pricing)
# Embeddings
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
supported_endpoint_types 包含 embeddings
}
/>
}
>
## 請求 Body
來自 /api/models/catalog 的 embedding 模型 ID。
文字輸入，或有序文字批次輸入。響應會保持輸入順序。
支援截斷的模型可使用可選向量維度。
上游支援時可選擇輸出編碼格式。
## 響應
通常為 list。
每個 input 對應一個 embedding item。
向量數值，或取決於 encoding_format 的 base64 編碼向量。
embedding 使用的輸入 token 數。
## 批次建議
小批次可以直接傳陣列。大規模資料任務建議在用戶端分塊，確保每個請求都不超過
provider 的 body size 和 token 限制。
## 相關頁面
- [模型目錄](/zh-TW/models/catalog)
- [定價與通道](/zh-TW/models/pricing)
# Embeddings
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
supported_endpoint_types includes embeddings
}
/>
}
>
## Request body
/api/models/catalog の embedding model ID。
text input または ordered batch。response は入力順を保持します。
truncation を support する model の optional vector dimension。
upstream が support する場合の output encoding format。
## Response
通常は list。
input ごとの embedding item。
vector values または encoding_format に応じた base64 vector。
embedding に使われた input tokens。
## Batch guidance
小さな batch は array で渡せます。大規模 jobs では client-side chunking を行い、
provider の body-size と token limits を超えないようにしてください。
# Files API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
Files are kept for 30 days, then removed by the cleanup job.
}
/>
}
>
## File endpoints
| Method | Path | Purpose |
| ------ | ----------------------- | -------------- |
| POST | `/v1/files` | Upload |
| GET | `/v1/files` | List |
| GET | `/v1/files/:id` | Metadata |
| GET | `/v1/files/:id/content` | Download bytes |
| DELETE | `/v1/files/:id` | Delete |
All endpoints use Authorization: Bearer $LAZU_API_KEY.
## Upload request
Declares how the file can be used.
Uploaded file bytes.
## Supported purposes
Up to 512 MB. Use for PDFs, text and structured data passed through
Responses as input_file.
Up to 20 MB. Allowed mime types: image/png,
image/jpeg, image/gif, image/webp.
OpenAI's batch, fine-tune and
assistants purposes are not yet supported. Executable file
extensions are rejected regardless of purpose.
## Upload response
File ID, for example file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX.
Always file.
Uploaded byte size.
Original filename.
Stored purpose.
Usually processed.
Lazu returns 201 Created for successful uploads. Treat it as
success if your client SDK expects 200.
## Reference from Responses
Lazu dereferences file_id only on
[Responses](/endpoints/responses). Chat completions does not pull file content
automatically.
For images uploaded with purpose=vision, use
input_image instead of input_file.
## Limits
| Limit | Value |
| ---------------------------------------------- | ------ |
| Single file with `purpose=user_data` | 512 MB |
| Single file with `purpose=vision` | 20 MB |
| Total bytes dereferenced in one Responses call | 64 MB |
## Errors
Missing purpose or file bytes.
Unsupported purpose such as batch or fine-tune.
Single file or total dereferenced files exceed limits.
File does not exist or is not owned by the current API key.
# Files API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
文件保留 30 天，然后由清理任务删除。
}
/>
}
>
## File endpoints
| Method | Path | 用途 |
| ------ | ----------------------- | -------- |
| POST | `/v1/files` | 上传 |
| GET | `/v1/files` | 列表 |
| GET | `/v1/files/:id` | 元数据 |
| GET | `/v1/files/:id/content` | 下载内容 |
| DELETE | `/v1/files/:id` | 删除 |
所有 endpoint 都使用 Authorization: Bearer $LAZU_API_KEY。
## 上传请求
声明文件用途。
上传的文件字节。
## 支持的 purpose
最大 512 MB。用于 PDF、文本和结构化数据，通过 Responses 的
input_file 传入。
最大 20 MB。允许 image/png、image/jpeg、
image/gif、image/webp。
OpenAI 的 batch、fine-tune 和
assistants purpose 暂不支持。无论 purpose
如何，都会拒绝可执行文件扩展名。
## 上传响应
File ID，例如 file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX。
始终为 file。
上传字节数。
原始文件名。
存储的 purpose。
通常为 processed。
成功上传时 Lazu 返回 201 Created。如果客户端只接受 200，需要把
201 也视作成功。
## 在 Responses 中引用
Lazu 只会在 [Responses](/zh/endpoints/responses) 中解引用 file_id。
Chat completions 不会自动拉取文件内容。
对于 purpose=vision 的图片文件，请使用 input_image
而不是 input_file。
## 限制
| 限制 | 值 |
| ------------------------------- | ------ |
| 单个 `purpose=user_data` 文件 | 512 MB |
| 单个 `purpose=vision` 文件 | 20 MB |
| 单次 Responses 调用解引用总大小 | 64 MB |
## 错误
缺少 purpose 或文件字节。
不支持的 purpose，例如 batch 或 fine-tune。
单文件或解引用总大小超过限制。
文件不存在，或不属于当前 API Key。
# Files API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
檔案保留 30 天，然後由清理任務刪除。}
/>
}
>
## File endpoints
| Method | Path | 用途 |
| ------ | ----------------------- | -------- |
| POST | `/v1/files` | 上傳 |
| GET | `/v1/files` | 列表 |
| GET | `/v1/files/:id` | metadata |
| GET | `/v1/files/:id/content` | 下載內容 |
| DELETE | `/v1/files/:id` | 刪除 |
所有 endpoint 都使用 Authorization: Bearer $LAZU_API_KEY。
## 上傳請求
宣告檔案用途。
上傳的檔案位元組。
## 支援的 purpose
最大 512 MB。用於 PDF、文字和結構化資料，透過 Responses 的
input_file 傳入。
最大 20 MB。允許 image/png、image/jpeg、
image/gif、image/webp。
OpenAI 的 batch、fine-tune 和
assistants purpose 暫不支援。無論 purpose
如何，都會拒絕可執行檔副檔名。
## 上傳響應
File ID，例如 file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX。
始終為 file。
上傳位元組數。
原始檔名。
儲存的 purpose。
通常為 processed。
成功上傳時 Lazu 返回 201 Created。如果用戶端只接受 200，需要把
201 也視作成功。
## 在 Responses 中引用
Lazu 只會在 [Responses](/zh-TW/endpoints/responses) 中解引用 file_id。
Chat completions 不會自動拉取檔案內容。
## 限制
| 限制 | 值 |
| ------------------------------- | ------ |
| 單個 `purpose=user_data` 檔案 | 512 MB |
| 單個 `purpose=vision` 檔案 | 20 MB |
| 單次 Responses 呼叫解引用總大小 | 64 MB |
# Files API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
Files are kept for 30 days.}
/>
}
>
## File endpoints
| Method | Path | Purpose |
| ------ | ----------------------- | -------------- |
| POST | `/v1/files` | Upload |
| GET | `/v1/files` | List |
| GET | `/v1/files/:id` | Metadata |
| GET | `/v1/files/:id/content` | Download bytes |
| DELETE | `/v1/files/:id` | Delete |
すべて Authorization: Bearer $LAZU_API_KEY を使います。
## Upload request
file の用途。
upload する file bytes。
## Supported purposes
最大 512 MB。PDF、text、structured data を Responses の
input_file として渡す用途。
最大 20 MB。image/png、image/jpeg、
image/gif、image/webp を許可。
OpenAI の batch、fine-tune、assistants
purposes はまだ support していません。実行ファイル拡張子は purpose に関係なく拒否します。
## Upload response
File ID。例：file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX。
常に file。
upload byte size。
original filename。
stored purpose。
通常 processed。
成功時は 201 Created を返します。client SDK が 200 のみを想定している場合は
201 を success として扱ってください。
## Responses から参照する
Lazu は [Responses](/ja/endpoints/responses) でのみ file_id
を dereference します。Chat completions は file content を自動取得しません。
# Models list
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
Your SDK calls client.models.list() and expects the
OpenAI list shape.
}
/>
}
>
## Which model endpoint should I use?
OpenAI-compatible model list for existing SDKs and tools.
Rich token-scoped catalog for agents, routing, pricing, modalities, endpoint
support, parameters and usage/cache metadata.
## Response fields
Always list.
Accessible model records for the current API key.
Model ID.
Usually model.
Provider or owner label.
## Filtering behavior
A model appears here only when:
1. It is enabled on at least one usable Lazu channel.
2. The current API key is allowed to access it.
3. The token's model restrictions do not exclude it.
If an agent needs to choose well, read [Model catalog](/models/catalog) first.
# 模型列表
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
你的 SDK 调用 client.models.list()，并期望 OpenAI
list shape。
}
/>
}
>
## 应该使用哪个模型 endpoint？
面向现有 SDK 和工具的 OpenAI-compatible 模型列表。
面向 agent、路由、计费、模态、endpoint 支持、参数和 usage/cache metadata
的完整目录。
## 响应字段
始终为 list。
当前 API Key 可访问的模型记录。
模型 ID。
通常为 model。
provider 或 owner 标签。
## 过滤行为
模型只会在满足以下条件时出现在这里：
1. 至少有一个可用 Lazu channel 启用了该模型。
2. 当前 API Key 被允许访问该模型。
3. Token 的模型限制没有排除该模型。
如果 agent 需要做可靠选择，请优先读取 [模型目录](/zh/models/catalog)。
# 模型列表
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
你的 SDK 呼叫 client.models.list()，並期望 OpenAI list shape。
}
/>
}
>
## 應該使用哪個模型 endpoint？
面向既有 SDK 和工具的 OpenAI-compatible 模型列表。
面向 agent、路由、計費、模態、endpoint 支援、參數和 usage/cache metadata
的完整目錄。
## 響應欄位
始終為 list。
目前 API Key 可存取的模型記錄。
模型 ID。
通常為 model。
provider 或 owner 標籤。
## 過濾行為
模型只會在滿足以下條件時出現在這裡：
1. 至少有一個可用 Lazu channel 啟用了該模型。
2. 目前 API Key 被允許存取該模型。
3. Token 的模型限制沒有排除該模型。
如果 agent 需要做可靠選擇，請優先讀取 [模型目錄](/zh-TW/models/catalog)。
# モデル一覧
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
SDK が client.models.list() を呼び、OpenAI list shape を期待する場合。
}
/>
}
>
## どちらの endpoint を使うべきか
既存 SDK や tools 向けの OpenAI-compatible model list。
agents、routing、pricing、modalities、endpoint support、parameters、
usage/cache metadata のための rich catalog。
## Response fields
常に list。
現在の API Key でアクセスできる model records。
Model ID。
通常 model。
provider または owner label。
## Filtering behavior
モデルが表示される条件：
1. 少なくとも 1 つの usable Lazu channel で enabled。
2. 現在の API Key がアクセス可能。
3. token model restrictions により除外されていない。
agent が適切に選ぶ必要がある場合は、先に [モデルカタログ](/ja/models/catalog) を読んでください。
# Responses API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
- Reasoning models
- Uploaded PDFs or images
- Structured multimodal input
}
/>
}
>
## When to use it
Uploaded files, reasoning controls, document workflows, and multimodal
inputs that should be normalized server-side.
Simple chat, SDK compatibility, tool calling, and existing apps already
built around /v1/chat/completions.
## Request body
Model ID from /api/models/catalog. Prefer models where
supported_endpoint_types includes responses.
Text input or an array of response input messages.
System-level instructions for the response.
Reasoning effort controls for supported models, for example
{'{"effort":"medium"}'}.
Tool definitions using the OpenAI-compatible Responses shape.
Streams response events when supported by the selected model.
Upper bound for generated output tokens.
## Content parts
Text content sent to the model.
Image content. Lazu can dereference uploaded file_id values
with purpose vision.
Uploaded file reference. Lazu dereferences file content server-side before
forwarding the request upstream.
## File dereferencing
Upload via [Files](/endpoints/files), then reference the resulting
file_id. Lazu adds X-Lazu-File-Dereference: 1 when the
request dereferenced files.
Limits:
- Single file purpose limit still applies.
- Total dereferenced files in one Responses call must stay under 64 MB.
- Chat completions does not auto-dereference file_id.
## Response
Response ID.
Output messages, reasoning items, tool calls, or other response events.
Input token count when the upstream reports usage.
Output token count when the upstream reports usage.
Cache read tokens for providers that expose response-level cache usage.
For full reconciliation, use
GET /api/usage/requests/{"{request_id}"} with the same API key.
## See also
- [Files API](/endpoints/files)
- [Chat completions](/endpoints/chat)
- [Model catalog](/models/catalog)
# Responses API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
- Reasoning 模型
- 已上传的 PDF 或图片
- 结构化多模态输入
}
/>
}
>
## 何时使用
上传文件、reasoning 控制、文档 workflow，以及需要服务端标准化的多模态输入。
简单聊天、SDK 兼容、tool calling，以及已经围绕
/v1/chat/completions 构建的应用。
## 请求 Body
来自 /api/models/catalog 的模型 ID。优先选择
supported_endpoint_types 包含 responses 的模型。
文本输入，或 response input messages 数组。
response 的系统级 instructions。
支持 reasoning 的模型可使用 effort 控制，例如
{'{"effort":"medium"}'}。
OpenAI-compatible Responses shape 的工具定义。
当模型支持时，返回 response events stream。
生成输出 token 的上限。
## Content parts
发送给模型的文本内容。
图片内容。Lazu 可以解引用 purpose 为 vision 的上传文件。
上传文件引用。Lazu 会在服务端读取文件内容后再转发给上游。
## File 解引用
先通过 [Files](/zh/endpoints/files) 上传文件，再引用返回的 file_id。
如果请求中发生了解引用，Lazu 会添加 X-Lazu-File-Dereference: 1。
限制：
- 单文件仍受 purpose 对应大小限制。
- 单次 Responses 调用中解引用的文件总大小必须低于 64 MB。
- Chat completions 不会自动解引用 file_id。
## 响应
Response ID。
输出消息、reasoning items、tool calls 或其它 response events。
上游返回 usage 时的输入 token 数。
上游返回 usage 时的输出 token 数。
支持 response-level cache usage 的 provider 返回的 cache read tokens。
完整对账请使用同一个 API Key 调用：
GET /api/usage/requests/{"{request_id}"}
## 相关页面
- [Files API](/zh/endpoints/files)
- [Chat completions](/zh/endpoints/chat)
- [模型目录](/zh/models/catalog)
# Responses API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
- Reasoning 模型
- 已上傳的 PDF 或圖片
- 結構化多模態輸入
}
/>
}
>
## 何時使用
上傳檔案、reasoning 控制、文件 workflow，以及需要服務端標準化的多模態輸入。
簡單聊天、SDK 相容、tool calling，以及已經圍繞
/v1/chat/completions 建構的應用。
## 請求 Body
來自 /api/models/catalog 的模型 ID。優先選擇
supported_endpoint_types 包含 responses 的模型。
文字輸入，或 response input messages 陣列。
response 的系統級 instructions。
支援 reasoning 的模型可使用 effort 控制，例如
{'{"effort":"medium"}'}。
OpenAI-compatible Responses shape 的工具定義。
當模型支援時，返回 response events stream。
生成輸出 token 的上限。
## File 解引用
先透過 [Files](/zh-TW/endpoints/files) 上傳檔案，再引用返回的
file_id。如果請求中發生了解引用，Lazu 會加入
X-Lazu-File-Dereference: 1。
限制：
- 單檔案仍受 purpose 對應大小限制。
- 單次 Responses 呼叫中解引用的檔案總大小必須低於 64 MB。
- Chat completions 不會自動解引用 file_id。
## 響應
Response ID。
輸出訊息、reasoning items、tool calls 或其它 response events。
上游返回 usage 時的輸入 token 數。
上游返回 usage 時的輸出 token 數。
支援 response-level cache usage 的 provider 返回的 cache read tokens。
完整對帳請使用同一把 API Key 呼叫：
GET /api/usage/requests/{"{request_id}"}
## 相關頁面
- [Files API](/zh-TW/endpoints/files)
- [Chat completions](/zh-TW/endpoints/chat)
- [模型目錄](/zh-TW/models/catalog)
# Responses API
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
- Reasoning models
- Uploaded PDFs or images
- Structured multimodal input
}
/>
}
>
## 使い分け
uploaded files、reasoning controls、document workflows、server-side
normalized multimodal inputs。
simple chat、SDK compatibility、tool calling、既存の
/v1/chat/completions ベースのアプリ。
## Request body
/api/models/catalog の model ID。
supported_endpoint_typesに responses を含む model
を優先してください。
text input または response input messages array。
response の system-level instructions。
supported models で reasoning effort を制御します。例：
{'{"effort":"medium"}'}。
OpenAI-compatible Responses shape の tool definitions。
model が対応する場合、response events stream を返します。
generated output tokens の上限。
## File dereferencing
[Files](/ja/endpoints/files) で upload した file_id を参照できます。
dereference が発生した場合、Lazu は X-Lazu-File-Dereference: 1 を付けます。
制限：
- single file purpose limit は引き続き適用されます。
- 1 回の Responses call で dereference される files は合計 64 MB 未満。
- Chat completions は file_id を自動 dereference しません。
## Response
Response ID。
output messages、reasoning items、tool calls、その他 response events。
upstream が usage を返す場合の input token count。
upstream が usage を返す場合の output token count。
完全な照合には同じ API Key で
GET /api/usage/requests/{"{request_id}"} を使ってください。
# Search
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
Admins configure providers in{" "}
Search backends.
Users can test them from{" "}
Search.
}
/>
}
>
## What it returns
Every backend maps into title, url,
snippet, optional content,
published_at, score and source.
The response includes the selected backend and route receipt. Request logs
store the same routing metadata for support and billing reconciliation.
## Hosted configuration
The `/v1/search` implementation supports Tavily, Serper, Exa, Jina and Brave,
but the hosted Lazu deployment is configured with this active set:
| Backend | Hosted status | Capabilities | Notes |
| ----------- | ------------- | ----------------------------------- | --------------------------------------------------------------------- |
| Tavily | Enabled | `web_search`, `web_fetch`, `answer` | Supports `include_answer` and `search_depth`; `advanced` is 2 units. |
| Serper | Enabled | `web_search` | Maps `country` / `region`, `language` and `time_range` when provided. |
| Jina | Enabled | `web_search`, `web_fetch` | Uses `https://s.jina.ai`; best for retrieval-style snippets. |
| Exa / Brave | Supported | `web_search` after operator setup | Available for self-hosted or admin-configured deployments. |
Hosted backends currently use the default backend policy: up to 10 results per
request and an 8s upstream timeout. If you send a larger `max_results`, Lazu
clips it to the selected backend policy.
## Request body
Search query. The MVP supports one query per request.
Search vertical. Defaults to web.
auto, a provider name such as tavily or{" "}
serper, or a configured backend ID/name. Defaults to{" "}
auto.
Region hint. Serper maps this to gl; other providers may ignore
unsupported regions.
Language hint such as en or zh-CN.
Freshness hint. Providers that cannot map the value may ignore it.
Number of results to return. Defaults to 10 and is capped by
the selected backend policy.
Provider depth hint. Tavily advanced uses two billable credits.
Include a provider answer when the selected backend returns one. Lazu does
not generate its own final answer in this endpoint.
Include raw or cleaned content when the provider returns it. Defaults to
false.
Restrict results to domains. Token-level domain allowlists still apply.
Exclude domains when supported by the selected backend.
Return the provider-native payload for debugging. Defaults to
false.
Advanced provider passthrough. Only the selected provider's object is used,
for example {'{"serper":{"tbs":"qdr:d"}}'}.
## Response
{`{
"query": "latest OpenAI web search API changes",
"results": [
{
"title": "Web search - OpenAI API",
"url": "https://platform.openai.com/docs/guides/tools-web-search",
"snippet": "Use web search in the Responses API...",
"content": null,
"published_at": null,
"score": 0.91,
"source": "web"
}
],
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
},
"provider_trace": {
"backend": "tavily"
},
"route_receipt": {
"selection": "auto",
"selected_backend": "tavily",
"chose_provider": "tavily",
"candidates": ["tavily:Tavily"],
"rejected": [],
"downgraded": false,
"fallback_count": 0,
"decision_reason": "selected"
}
}`}
Normalized search result list. content is only populated when
raw content was requested and returned by the backend.
Lazu search request count, normally 1.
Provider billing units used for the charge. Tavily basic is 1 unit, Tavily
advanced is 2 units, and Serper or Jina is normally 1 successful query.
Actual provider selected after routing.
Candidate, fallback and rejection metadata. The same data is stored in the
request log.
## Billing
Search backends are priced from their configured search_price.
The value is the USD price per provider billing unit, not always per HTTP
request. The hosted Tavily, Serper and Jina backends currently have no explicit
search_price configured, so Lazu records web_search
usage and bills $0 for the search line item until an operator configures a price
or provider-cost passthrough.
| Backend | Unit mapping |
| ------- | ---------------------------------------------------------------- |
| Tavily | basic = 1 credit; advanced = 2 credits |
| Serper | 1 successful query = 1 unit |
| Jina | 1 successful query = 1 unit |
Failed upstream calls, timeouts and invalid requests are refunded according to
the normal Lazu billing rules.
## See also
- [How pricing works](/billing)
- [Request details](/endpoints/usage-requests)
- [Model catalog](/models/catalog)
# Search
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
管理员在{" "}
检索后端
配置 provider；用户在{" "}
搜索测试页
试搜并复制 cURL。
}
/>
}
>
## 返回什么
不同 provider 都会映射成 title、url、
snippet、可选的 content、published_at
、score 和 source。
响应会返回实际选中的 backend 和 route receipt。请求日志中也会保存同样的
routing 元数据，便于排障和对账。
## 托管版配置
`/v1/search` 的实现支持 Tavily、Serper、Exa、Jina 和 Brave，但当前托管版
Lazu 实际启用的是下面这组 backend：
| Backend | 托管版状态 | 能力 | 说明 |
| ----------- | ---------- | ----------------------------------- | --------------------------------------------------------------------- |
| Tavily | 已启用 | `web_search`、`web_fetch`、`answer` | 支持 `include_answer` 和 `search_depth`；`advanced` 按 2 units 计算。 |
| Serper | 已启用 | `web_search` | 会映射 `country` / `region`、`language` 和 `time_range`。 |
| Jina | 已启用 | `web_search`、`web_fetch` | 使用 `https://s.jina.ai`，更适合 retrieval 风格的 snippet。 |
| Exa / Brave | 代码支持 | 管理员配置后支持 `web_search` | 适用于自部署或管理员后续配置的托管环境。 |
当前托管版 backend 使用默认策略：每次请求最多返回 10 条结果，上游 timeout 为 8s。
如果请求里的 `max_results` 更大，Lazu 会按选中的 backend policy 截断。
## 请求 Body
搜索 query。当前 MVP 每次请求支持一个 query。
搜索类型，默认 web。
auto、provider 名称如 tavily /serper
，或已配置的 backend ID/name。默认 auto。
地区 hint。Serper 会映射到 gl。
语言 hint，例如 en 或 zh-CN。
时间范围 hint。provider 不支持时可能忽略。
返回结果数。默认 10，并受 backend policy 上限约束。
provider 深度 hint。Tavily advanced 会消耗 2 个计费 unit。
selected backend 返回 answer 时一并返回。Lazu 不在这个 endpoint
内生成最终答案。
provider 返回原文或清洗正文时是否透出，默认 false。
限制搜索域名。token 级 domain allowlist 仍会生效。
排除域名，取决于 selected backend 是否支持。
返回 provider 原始 payload，主要用于排障。默认 false。
高级 provider passthrough。只会使用当前 provider 对应对象，例如{" "}
{'{"serper":{"tbs":"qdr:d"}}'}。
## 响应
{`{
"query": "latest OpenAI web search API changes",
"results": [
{
"title": "Web search - OpenAI API",
"url": "https://platform.openai.com/docs/guides/tools-web-search",
"snippet": "Use web search in the Responses API...",
"content": null,
"published_at": null,
"score": 0.91,
"source": "web"
}
],
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
},
"provider_trace": {
"backend": "tavily"
},
"route_receipt": {
"selection": "auto",
"selected_backend": "tavily",
"chose_provider": "tavily",
"candidates": ["tavily:Tavily"],
"rejected": [],
"downgraded": false,
"fallback_count": 0,
"decision_reason": "selected"
}
}`}
归一化搜索结果。只有请求了 raw content 且 backend 返回时，
content 才会填充。
Lazu 搜索请求次数，通常为 1。
实际计费用的 provider unit。Tavily basic 为 1，Tavily advanced 为 2， Serper
和 Jina 通常为 1 个成功 query。
路由后实际选中的 provider。
候选、fallback、拒绝原因等路由元数据，同步写入请求日志。
## 计费
Search backend 的价格来自配置里的 search_price。这个值表示每个
provider billing unit 的 USD 价格，不一定等同于每个 HTTP request 的价格。
当前托管版 Tavily、Serper 和 Jina 没有显式配置 search_price，
所以 Lazu 会记录 web_search usage，但 search line item 费用为
$0；后续管理员配置价格或 provider-cost passthrough 后才会按配置收费。
| Backend | Unit 映射 |
| ------- | ---------------------------------------------------------------- |
| Tavily | basic = 1 credit；advanced = 2 credits |
| Serper | 1 个成功 query = 1 unit |
| Jina | 1 个成功 query = 1 unit |
上游失败、timeout、参数错误会按 Lazu 常规计费规则 refund。
## 相关页面
- [计费规则](/zh/billing)
- [请求详情](/zh/endpoints/usage-requests)
- [模型目录](/zh/models/catalog)
# Search
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
管理員在{" "}
Search backends
設定 provider；使用者在{" "}
Search 測試。
}
/>
}
>
## 返回什麼
不同 provider 都會映射成 title、url、
snippet、可選的 content、published_at
、score 和 source。
響應會返回實際選中的 backend 和 route receipt。請求日誌中也會保存同樣的
routing metadata，方便排障和對帳。
## 託管版設定
`/v1/search` 的實作支援 Tavily、Serper、Exa、Jina 和 Brave，但目前託管版
Lazu 實際啟用的是下面這組 backend：
| Backend | 託管版狀態 | 能力 | 說明 |
| ----------- | ---------- | ----------------------------------- | --------------------------------------------------------------------- |
| Tavily | 已啟用 | `web_search`、`web_fetch`、`answer` | 支援 `include_answer` 和 `search_depth`；`advanced` 按 2 units 計算。 |
| Serper | 已啟用 | `web_search` | 會映射 `country` / `region`、`language` 和 `time_range`。 |
| Jina | 已啟用 | `web_search`、`web_fetch` | 使用 `https://s.jina.ai`，較適合 retrieval 風格的 snippet。 |
| Exa / Brave | 程式支援 | 管理員設定後支援 `web_search` | 適用於自部署或管理員後續設定的託管環境。 |
目前託管版 backend 使用預設策略：每次請求最多返回 10 筆結果，上游 timeout 為
8s。如果請求裡的 `max_results` 更大，Lazu 會按選中的 backend policy 截斷。
## 請求 Body
搜尋 query。當前 MVP 每次請求支援一個 query。
搜尋類型，預設 web。
auto、provider 名稱如 tavily 或{" "}
serper， 或已設定的 backend ID/name。預設 auto。
地區 hint。Serper 會映射到 gl。
語言 hint，例如 en 或 zh-TW。
時間範圍 hint。provider 不支援時可能忽略。
返回結果數。預設 10，並受 backend policy 上限約束。
provider 深度 hint。Tavily advanced 會消耗 2 個計費 unit。
selected backend 返回 answer 時一併返回。Lazu 不會在這個 endpoint
內生成最終答案。
provider 返回原文或清洗正文時是否透出，預設 false。
限制搜尋網域。token 級 domain allowlist 仍會生效。
排除網域，取決於 selected backend 是否支援。
返回 provider 原始 payload，主要用於排障。預設 false。
進階 provider passthrough。只會使用當前 provider 對應物件，例如{" "}
{'{"serper":{"tbs":"qdr:d"}}'}。
## 響應
{`{
"query": "latest OpenAI web search API changes",
"results": [
{
"title": "Web search - OpenAI API",
"url": "https://platform.openai.com/docs/guides/tools-web-search",
"snippet": "Use web search in the Responses API...",
"content": null,
"published_at": null,
"score": 0.91,
"source": "web"
}
],
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
},
"provider_trace": {
"backend": "tavily"
},
"route_receipt": {
"selection": "auto",
"selected_backend": "tavily",
"chose_provider": "tavily",
"candidates": ["tavily:Tavily"],
"rejected": [],
"downgraded": false,
"fallback_count": 0,
"decision_reason": "selected"
}
}`}
標準化搜尋結果。只有請求了 raw content 且 backend 返回時，
content 才會填充。
Lazu 搜尋請求次數，通常為 1。
實際計費使用的 provider unit。Tavily basic 為 1，Tavily advanced 為 2，
Serper 和 Jina 通常為 1 個成功 query。
路由後實際選中的 provider。
候選、fallback、拒絕原因等路由 metadata，同步寫入請求日誌。
## 計費
Search backend 的價格來自設定中的 search_price。這個值表示每個
provider billing unit 的 USD 價格，不一定等同於每個 HTTP request 的價格。
目前託管版 Tavily、Serper 和 Jina 沒有明確設定 search_price，
所以 Lazu 會記錄 web_search usage，但 search line item 費用為
$0；後續管理員設定價格或 provider-cost passthrough 後才會按設定收費。
| Backend | Unit 映射 |
| ------- | ---------------------------------------------------------------- |
| Tavily | basic = 1 credit；advanced = 2 credits |
| Serper | 1 個成功 query = 1 unit |
| Jina | 1 個成功 query = 1 unit |
上游失敗、timeout、參數錯誤會按 Lazu 常規計費規則 refund。
## 相關頁面
- [計費規則](/zh-TW/billing)
- [請求詳情](/zh-TW/endpoints/usage-requests)
- [模型目錄](/zh-TW/models/catalog)
# Search
CodeSample,
EndpointGrid,
EndpointPage,
EndpointRail,
EndpointTile,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
Admins configure providers in{" "}
Search backends.
}
/>
}
>
## What it returns
backend ごとに title、url、snippet、
optional content、published_at、score
、source へ mapping します。
response は selected backend と route receipt を含みます。同じ routing
metadata が request logs に保存され、support と billing reconciliation
に使えます。
## Hosted configuration
`/v1/search` の実装は Tavily、Serper、Exa、Jina、Brave を support しますが、
現在の hosted Lazu で有効なのは次の backend です。
| Backend | Hosted status | Capabilities | Notes |
| ----------- | ------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| Tavily | Enabled | `web_search`, `web_fetch`, `answer` | `include_answer` と `search_depth` を support。`advanced` は 2 units。 |
| Serper | Enabled | `web_search` | `country` / `region`、`language`、`time_range` を mapping します。 |
| Jina | Enabled | `web_search`, `web_fetch` | `https://s.jina.ai` を使い、retrieval 形式の snippet に向いています。 |
| Exa / Brave | Supported | operator 設定後に `web_search` 対応 | self-hosted または admin-configured deployment 向けです。 |
Hosted backends は現在 default policy を使っています。1 request あたり最大
10 results、upstream timeout は 8s です。`max_results` がそれより大きい場合、
Lazu は selected backend policy に合わせて切り詰めます。
## Request body
search query。MVP は 1 request につき 1 query を support します。
search vertical。default は web。
auto、provider name（例：tavily）、または
configured backend ID/name。default は auto。
region hint。Serper は gl に mapping します。
language hint。例：en、ja。
freshness hint。provider が mapping できない value
は無視されることがあります。
結果数。default は 10 で、selected backend policy
の上限が適用されます。
provider depth hint。Tavily advanced は 2 billable credits。
selected backend が answer を返す場合に含めます。Lazu はこの endpoint
内で最終回答を生成しません。
provider が raw content または cleaned content を返す場合に透過します。
default は false。
検索対象 domain を制限します。token-level domain allowlist
は引き続き適用されます。
selected backend が support する場合に domain を除外します。
provider-native payload を debugging 用に返します。default は{" "}
false。
advanced provider passthrough。selected provider の object
だけが使われます。 例：{'{"serper":{"tbs":"qdr:d"}}'}。
## Response
{`{
"query": "latest OpenAI web search API changes",
"results": [
{
"title": "Web search - OpenAI API",
"url": "https://platform.openai.com/docs/guides/tools-web-search",
"snippet": "Use web search in the Responses API...",
"content": null,
"published_at": null,
"score": 0.91,
"source": "web"
}
],
"usage": {
"web_search_requests": 1,
"web_search_billable_units": 1
},
"provider_trace": {
"backend": "tavily"
},
"route_receipt": {
"selection": "auto",
"selected_backend": "tavily",
"chose_provider": "tavily",
"candidates": ["tavily:Tavily"],
"rejected": [],
"downgraded": false,
"fallback_count": 0,
"decision_reason": "selected"
}
}`}
normalized search result list。raw content を request し、backend
が返した場合だけ
content が入ります。
Lazu search request count。通常は 1。
charge に使われる provider unit。Tavily basic は 1、Tavily advanced は 2、
Serper と Jina は通常 1 successful query です。
routing 後に実際に選ばれた provider。
candidates、fallback、rejection metadata。同じ情報が request log
に保存されます。
## Billing
Search backend は configured search_price から課金されます。これは
provider billing unit あたりの USD 価格であり、常に HTTP request 単位とは限りません。
現在の hosted Tavily、Serper、Jina backends には明示的な
search_price が設定されていないため、Lazu はweb_search
usage を記録しますが、search line item は $0 です。 operator が価格または
provider-cost passthrough を設定したあとに、その設定で課金されます。
| Backend | Unit mapping |
| ------- | ---------------------------------------------------------------- |
| Tavily | basic = 1 credit、advanced = 2 credits |
| Serper | 1 successful query = 1 unit |
| Jina | 1 successful query = 1 unit |
upstream failure、timeout、invalid request は通常の Lazu billing rules に従って refund されます。
## See also
- [料金体系](/ja/billing)
- [リクエスト詳細](/ja/endpoints/usage-requests)
- [モデルカタログ](/ja/models/catalog)
# Request details
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../components/mdx";
Read X-Lazu-Request-Id, an error payload
request_id, or the gateway response request ID.
}
/>
}
>
## Path parameters
Request ID for a request made by the same API key. Lazu rejects attempts to
read another key's request details.
## Response fields
The requested request ID.
Requested model or route name.
Actual upstream model after routing and model mapping.
Normalized dimensions such as input, output,
cache_read, cache_write_5m,
cache_write_1h, cache_miss, audio and image
dimensions.
Billable usage lines with price, quantity and total charge.
Compact provider-native usage fields retained for reconciliation.
Route decision metadata when the request used routing.
## Cache field guidance
OpenAI-compatible responses may show cache reads as
usage.prompt_tokens_details.cached_tokens or
usage.input_tokens_details.cached_tokens. Cache writes may appear
as cache_write_tokens, cache_write_5m_tokens or
cache_write_1h_tokens only when the upstream reports them.
For billing and reconciliation, this endpoint is the more complete source.
## See also
- [Billing and cache fields](/billing)
- [Model catalog](/models/catalog)
- [Chat completions](/endpoints/chat)
# 请求详情
CodeSample,
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
使用响应头 X-Lazu-Request-Id、错误响应里的
request_id，或 gateway response request ID。
}
/>
}
>
## 路径参数
同一个 API key 发起的请求 ID。Lazu 不允许读取其它 key 的请求详情。
## 响应字段
请求 ID。
用户请求的模型或 route 名称。
实际上游模型。
标准化 usage 维度，例如 input、output、
cache_read、cache_write_5m、
cache_write_1h、cache_miss、audio/image 维度等。
计费明细。
用于对账的 provider 原始 usage 字段。
请求经过 routing 时返回路由元数据。
## Cache 字段
OpenAI-compatible 响应里，cache read 可能出现在
usage.prompt_tokens_details.cached_tokens 或
usage.input_tokens_details.cached_tokens。
cache write 只有在上游返回时才会出现，字段可能是
cache_write_tokens、cache_write_5m_tokens 或
cache_write_1h_tokens。
如果要对账或排查费用，以请求详情 API 为准。
## 相关页面
- [计费规则](/zh/billing)
- [模型目录](/zh/models/catalog)
- [Chat completions](/zh/endpoints/chat)
# 請求詳情
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
使用響應標頭 X-Lazu-Request-Id、錯誤響應裡的
request_id，或 gateway response request ID。
}
/>
}
>
## 路徑參數
同一把 API Key 發起的請求 ID。Lazu 不允許讀取其它 key 的請求詳情。
## 響應欄位
請求 ID。
使用者請求的模型或 route 名稱。
實際上游模型。
標準化 usage 維度，例如 input、output、
cache_read、cache_write_5m、
cache_write_1h、cache_miss。
計費明細。
用於對帳的 provider 原始 usage 欄位。
請求經過 routing 時返回路由 metadata。
## Cache 欄位
OpenAI-compatible 響應裡，cache read 可能出現在
usage.prompt_tokens_details.cached_tokens 或
usage.input_tokens_details.cached_tokens。cache write
只有在上游返回時才會出現。
如果要對帳或排查費用，以請求詳情 API 為準。
## 相關頁面
- [計費規則](/zh-TW/billing)
- [模型目錄](/zh-TW/models/catalog)
- [Chat completions](/zh-TW/endpoints/chat)
# リクエスト詳細
EndpointPage,
EndpointRail,
Field,
FieldList,
MiniCard,
} from "../../../components/mdx";
X-Lazu-Request-Id、error payload の
request_id、または gateway response request ID。
}
/>
}
>
## Path parameters
同じ API Key が発行した request ID。別 key の request details は読めません。
## Response fields
requested request ID。
requested model または route name。
routing/model mapping 後の actual upstream model。
normalized dimensions。例：input、output、
cache_read、cache_write_5m、
cache_miss。
price、quantity、total charge を含む billable usage lines。
reconciliation 用の provider-native usage fields。
request が routing を使った場合の route decision metadata。
## Cache field guidance
OpenAI-compatible responses では cache read が
usage.prompt_tokens_details.cached_tokens または
usage.input_tokens_details.cached_tokens に出る場合があります。
billing と reconciliation では、この endpoint がより完全な source です。
## See also
- [料金体系](/ja/billing)
- [モデルカタログ](/ja/models/catalog)
- [Chat completions](/ja/endpoints/chat)
# Errors
# Errors
Every Lazu error follows the OpenAI error envelope:
```json
{
"error": {
"message": "Human-readable description",
"type": "invalid_request_error",
"code": "missing_required_parameter",
"param": "purpose",
"request_id": "req_lazu_01ABCDEF..."
}
}
```
`code` is the stable machine-readable identifier — match on this, not on
`message`. `request_id` is also returned as the `X-Lazu-Request-Id` HTTP
header; include it when contacting support.
## HTTP status codes at a glance
| Status | Category | What to do |
| ------ | --------------------- | ------------------------------------------------------------- |
| 200 | Success | - |
| 201 | Created (file upload) | Same as 200; some clients reject 201 — patch them |
| 400 | Bad request | Fix the request body / params; safe to retry after fix |
| 401 | Auth failed | Wrong / missing API key; do **not** retry without fixing key |
| 403 | Forbidden | Key disabled, IP not allow-listed, or quota exhausted |
| 404 | Not found | Wrong path, missing model, deleted file_id |
| 413 | Payload too large | Single file exceeds purpose's max size |
| 422 | Validation failed | Body matched schema but values invalid (e.g. temperature OOB) |
| 429 | Rate limit | Sleep `Retry-After` seconds, then retry |
| 500 | Lazu internal error | Retry with backoff; if persistent, open a ticket |
| 502 | Upstream bad gateway | Retry; Lazu will try another channel automatically once |
| 503 | Upstream unavailable | Retry with backoff; usually transient |
| 504 | Upstream timeout | Retry with backoff; check if your request is too slow |
## Common error codes
### Auth
| Code | When |
| -------------------- | ------------------------------------------------------- |
| `invalid_api_key` | Header missing, malformed, or key deleted |
| `insufficient_quota` | Balance hit zero — top up to continue |
| `ip_not_allowed` | Key has IP allowlist, your request came from outside it |
| `token_disabled` | Key was manually disabled in console |
| `token_expired` | Key passed its `expired_time` |
### Request shape
| Code | When |
| ---------------------------- | ------------------------------------------------------------------- |
| `bad_request_body` | JSON didn't parse, or upstream rejected the request as malformed |
| `missing_required_parameter` | Required field absent (`param` shows which one) |
| `invalid_request` | Generic catch-all for malformed inputs |
| `model_not_found` | The model name doesn't exist or isn't accessible to this key |
| `convert_request_failed` | Internal: couldn't translate the request for the chosen vendor |
| `tokenization_error` | Couldn't count input tokens (rare; usually huge / malformed prompt) |
### Files API specific
| Code | When |
| ------------------------- | ------------------------------------------------------------- |
| `purpose_not_supported` | Used `batch` / `fine-tune` / `assistants` (not supported yet) |
| `file_not_found` | `file_id` doesn't exist or wasn't uploaded by this key |
| `file_expired` | File aged past its 30-day retention |
| `file_too_large` | Single file over purpose's max size, or Responses dereference |
| | total exceeds 64 MB |
| `file_dereference_failed` | Couldn't pull the file from storage (very rare) |
### Pricing & quota
| Code | When |
| -------------------------------- | -------------------------------------------------------- |
| `pricing_not_configured` | Model exists but no sell-price set in the requested lane |
| `pre_consume_token_quota_failed` | Token quota tracking conflict (retry once) |
### Rate limits
| Code | When |
| ----------------------------- | ----------------------------------------------------------- |
| `request_rate_limit_exceeded` | Hit your tier's RPM cap. `Retry-After` header shows seconds |
### Upstream / routing
| Code | When |
| -------------------------------- | ----------------------------------------------------------------- |
| `upstream_error` | Upstream returned non-2xx. `details.status_code` has the original |
| `upstream_timeout` | Upstream didn't respond in time |
| `upstream_network_error` | Network failure connecting to upstream |
| `channel_response_time_exceeded` | Channel exceeded the per-channel timeout budget |
| `no_available_channel` | No channel is configured to serve the requested model+lane combo |
## Retry strategy
Roughly: retry **idempotent** error categories with exponential backoff:
| Status / code | Retry? |
| ------------------------------------ | ------------------------------ |
| `429 request_rate_limit_exceeded` | Yes — honor `Retry-After` |
| `500` / `502` / `503` / `504` | Yes — exp backoff, max 3 tries |
| `400` / `404` / `422` | No — fix the request |
| `401` / `403` | No — fix auth / quota first |
| `upstream_error` with 4xx underneath | No |
| `upstream_error` with 5xx underneath | Yes — exp backoff |
Most popular OpenAI / Anthropic SDKs do this automatically. Don't disable
their retry logic unless you have a strong reason.
## Including a `request_id` in support tickets
Every Lazu response (success or error) includes:
```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```
Paste this into any support ticket. We can trace the full request path
through routing, upstream call, and billing — far faster than re-creating
the issue from a fuzzy description.
## See also
- [Rate limits](/limits)
- [Authentication](/authentication)
- [Request details](/endpoints/usage-requests)
# 错误码
# 错误码
Lazu 错误响应遵循 OpenAI 风格：
```json
{
"error": {
"message": "Human-readable description",
"type": "invalid_request_error",
"code": "missing_required_parameter",
"param": "purpose",
"request_id": "req_lazu_01ABCDEF..."
}
}
```
`code` 是稳定的机器可读字段，程序应匹配 `code` 而不是 `message`。
`request_id` 也会出现在 `X-Lazu-Request-Id` 响应头中；联系支持时请带上它。
## HTTP 状态码
| 状态码 | 类型 | 建议处理 |
| ------ | ------------- | ----------------------------------- |
| 200 | 成功 | 无需处理 |
| 201 | 文件上传成功 | 等同成功，部分客户端需要兼容 201 |
| 400 | 请求错误 | 修正请求 body 或参数后再试 |
| 401 | 鉴权失败 | 修正 API Key，不要盲目重试 |
| 403 | 禁止访问 | key 被禁用、IP 不在白名单或额度耗尽 |
| 404 | 不存在 | path、model 或 file_id 错误 |
| 413 | Payload 过大 | 文件或引用内容超过限制 |
| 422 | 校验失败 | body schema 正确但字段值非法 |
| 429 | 速率限制 | 按 `Retry-After` 等待后重试 |
| 500 | Lazu 内部错误 | 指数退避重试，持续出现则联系支持 |
| 502 | 上游错误 | 可重试，Lazu 会尽量切换备用 channel |
| 503 | 上游不可用 | 通常是临时问题，可重试 |
| 504 | 上游超时 | 可重试，并检查请求是否过慢或过大 |
## 常见错误码
### 鉴权
| Code | 含义 |
| -------------------- | ----------------------------------------- |
| `invalid_api_key` | Header 缺失、格式错误、key 不存在或已删除 |
| `insufficient_quota` | 余额为零，需要充值 |
| `ip_not_allowed` | 当前请求 IP 不在 key 的白名单内 |
| `token_disabled` | key 被手动禁用 |
| `token_expired` | key 超过过期时间 |
### 请求格式
| Code | 含义 |
| ---------------------------- | ------------------------------------------------- |
| `bad_request_body` | JSON 无法解析，或上游认为请求格式错误 |
| `missing_required_parameter` | 缺少必填字段，`param` 会指出字段名 |
| `invalid_request` | 通用请求格式错误 |
| `model_not_found` | 模型不存在，或当前 key 没有访问权限 |
| `convert_request_failed` | Lazu 无法把请求转换成目标 provider 格式 |
| `tokenization_error` | 输入 token 统计失败，通常是 prompt 过大或格式异常 |
### Files API
| Code | 含义 |
| ------------------------- | ----------------------------------- |
| `purpose_not_supported` | 使用了尚不支持的 purpose |
| `file_not_found` | `file_id` 不存在或不属于当前 key |
| `file_expired` | 文件超过 30 天保留期 |
| `file_too_large` | 单文件或 Responses 解引用总大小超限 |
| `file_dereference_failed` | 存储系统读取文件失败 |
### 计费与限额
| Code | 含义 |
| -------------------------------- | -------------------------------------- |
| `pricing_not_configured` | 模型存在，但当前 lane 没有配置售卖价格 |
| `pre_consume_token_quota_failed` | 额度预扣冲突，可重试一次 |
| `request_rate_limit_exceeded` | 触发账号层级 RPM 限制 |
| `token_rate_limit_exceeded` | 触发单个 API Key 的 RPM/TPM 限制 |
### 上游与路由
| Code | 含义 |
| -------------------------------- | ------------------------------------------------ |
| `upstream_error` | 上游返回非 2xx，`details.status_code` 是原始状态 |
| `upstream_timeout` | 上游超时 |
| `upstream_network_error` | 连接上游失败 |
| `channel_response_time_exceeded` | 单个 channel 超过响应时间预算 |
| `no_available_channel` | 没有可用 channel 服务当前模型和 lane |
## 重试策略
| 状态或 code | 是否重试 |
| --------------------------------- | ----------------------- |
| `429 request_rate_limit_exceeded` | 是，遵守 `Retry-After` |
| `500` / `502` / `503` / `504` | 是，指数退避，最多 3 次 |
| `400` / `404` / `422` | 否，先修正请求 |
| `401` / `403` | 否，先修正鉴权或额度 |
| `upstream_error` 且上游是 4xx | 否 |
| `upstream_error` 且上游是 5xx | 是 |
## 提交支持工单
每个成功或失败响应都会包含：
```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```
把这个 ID 放进支持工单，可以让我们直接追踪路由、上游调用和计费路径。
## 相关页面
- [请求频率限制](/zh/limits)
- [鉴权](/zh/authentication)
- [请求详情](/zh/endpoints/usage-requests)
# 錯誤碼
# 錯誤碼
Lazu 錯誤回應遵循 OpenAI 風格：
```json
{
"error": {
"message": "Human-readable description",
"type": "invalid_request_error",
"code": "missing_required_parameter",
"param": "purpose",
"request_id": "req_lazu_01ABCDEF..."
}
}
```
`code` 是穩定的機器可讀欄位，程式應匹配 `code` 而不是 `message`。
`request_id` 也會出現在 `X-Lazu-Request-Id` 回應標頭中；聯絡支援時請帶上它。
## HTTP 狀態碼
| 狀態碼 | 類型 | 建議處理 |
| ------ | ------------- | ----------------------------------- |
| 200 | 成功 | 無需處理 |
| 201 | 檔案上傳成功 | 等同成功，部分用戶端需要相容 201 |
| 400 | 請求錯誤 | 修正 request body 或參數後再試 |
| 401 | 認證失敗 | 修正 API Key，不要盲目重試 |
| 403 | 禁止存取 | key 被停用、IP 不在白名單或額度耗盡 |
| 404 | 不存在 | path、model 或 file_id 錯誤 |
| 413 | Payload 過大 | 檔案或引用內容超過限制 |
| 422 | 校驗失敗 | body schema 正確但欄位值非法 |
| 429 | 速率限制 | 按 `Retry-After` 等待後重試 |
| 500 | Lazu 內部錯誤 | 指數退避重試，持續出現則聯絡支援 |
| 502 | 上游錯誤 | 可重試，Lazu 會盡量切換備用 channel |
| 503 | 上游不可用 | 通常是暫時問題，可重試 |
| 504 | 上游逾時 | 可重試，並檢查請求是否過慢或過大 |
## 常見錯誤碼
| Code | 含義 |
| ----------------------------- | ------------------------------------------------ |
| `invalid_api_key` | Header 缺失、格式錯誤、key 不存在或已刪除 |
| `insufficient_quota` | 餘額為零，需要儲值 |
| `ip_not_allowed` | 目前請求 IP 不在 key 的白名單內 |
| `token_disabled` | key 被手動停用 |
| `token_expired` | key 超過過期時間 |
| `bad_request_body` | JSON 無法解析，或上游認為請求格式錯誤 |
| `missing_required_parameter` | 缺少必填欄位，`param` 會指出欄位名稱 |
| `model_not_found` | 模型不存在，或目前 key 沒有存取權限 |
| `file_not_found` | `file_id` 不存在或不屬於目前 key |
| `file_too_large` | 單檔案或 Responses 解引用總大小超限 |
| `pricing_not_configured` | 模型存在，但目前 lane 沒有設定售價 |
| `request_rate_limit_exceeded` | 觸發帳號層級 RPM 限制 |
| `token_rate_limit_exceeded` | 觸發單一 API Key 的 RPM/TPM 限制 |
| `upstream_error` | 上游返回非 2xx，`details.status_code` 是原始狀態 |
| `upstream_timeout` | 上游逾時 |
| `no_available_channel` | 沒有可用 channel 服務目前模型和 lane |
## 重試策略
可重試：`429`、`500`、`502`、`503`、`504`、上游 5xx。不可重試：`400`、
`401`、`403`、`404`、`422`，需要先修正請求、認證或額度。
## 相關頁面
- [請求頻率限制](/zh-TW/limits)
- [認證](/zh-TW/authentication)
- [請求詳情](/zh-TW/endpoints/usage-requests)
# エラーコード
# エラーコード
Lazu のエラーは OpenAI 互換の envelope を使います。
```json
{
"error": {
"message": "Human-readable description",
"type": "invalid_request_error",
"code": "missing_required_parameter",
"param": "purpose",
"request_id": "req_lazu_01ABCDEF..."
}
}
```
プログラムでは `message` ではなく、安定した `code` を見てください。
`request_id` は `X-Lazu-Request-Id` header にも入ります。
## HTTP status
| Status | 種類 | 対応 |
| ------ | ----------------- | ---------------------------------------- |
| 400 | Bad request | body や params を修正 |
| 401 | Auth failed | API Key を修正。修正なしに retry しない |
| 403 | Forbidden | key disabled、IP allowlist、quota を確認 |
| 404 | Not found | path、model、file_id を確認 |
| 413 | Payload too large | file や参照内容が大きすぎる |
| 422 | Validation failed | schema は合うが値が不正 |
| 429 | Rate limit | `Retry-After` 後に retry |
| 5xx | Lazu/upstream | exponential backoff で retry |
## よく使う code
| Code | 意味 |
| ----------------------------- | ------------------------------------------------- |
| `invalid_api_key` | key がない、形式不正、削除済み |
| `insufficient_quota` | 残高が不足 |
| `ip_not_allowed` | key の IP allowlist 外 |
| `token_disabled` | key が手動で無効化された |
| `token_expired` | key が期限切れ |
| `missing_required_parameter` | 必須 field がない |
| `model_not_found` | model が存在しない、または key がアクセスできない |
| `file_not_found` | file_id がない、または現在の key のものではない |
| `file_too_large` | file または dereference 合計が上限超過 |
| `pricing_not_configured` | model はあるが lane 価格が未設定 |
| `request_rate_limit_exceeded` | account tier の RPM 上限 |
| `token_rate_limit_exceeded` | API Key の RPM/TPM 上限 |
| `upstream_error` | upstream が非 2xx を返した |
| `upstream_timeout` | upstream timeout |
| `no_available_channel` | model+lane を処理できる channel がない |
## retry 方針
`429`、`500`、`502`、`503`、`504`、upstream 5xx は retry できます。
`400`、`401`、`403`、`404`、`422` は先にリクエスト、認証、quota を修正してください。
## 関連ページ
- [レート制限](/ja/limits)
- [認証](/ja/authentication)
- [リクエスト詳細](/ja/endpoints/usage-requests)
# Rate limits
# Rate limits
Lazu protects backends with three layers of limits:
1. **Tier-based RPM/TPM** — every account belongs to a tier (`Tier0..Tier3`)
based on rolling spend. Higher tier = higher rate caps.
2. **Anti-abuse for unverified accounts** — if you've never funded the
account (no successful top-up), you're capped at a tiny rate regardless
of tier.
3. **Per-key RPM/TPM** — you can set a stricter cap on an individual API key
for product or workload isolation. A per-key limit never raises the account
tier ceiling; it can only make that key stricter.
Both limits apply **per API key user**, not globally — your usage doesn't
affect other Lazu customers.
## Defaults
| Tier | Eligibility | RPM | TPM |
| -------------- | ------------------------------------------------- | --: | --------: |
| **Unverified** | No successful top-up yet | 5 | 5,000 |
| Tier 0 | Verified (paid at least once), 30-day spend < $10 | 60 | 100,000 |
| Tier 1 | 30-day spend ≥ $10 | 120 | 300,000 |
| Tier 2 | 30-day spend ≥ $100 | 300 | 1,000,000 |
| Tier 3 | 30-day spend ≥ $1,000 | 600 | 2,000,000 |
- **RPM** = requests per minute (rolling 60-second window)
- **TPM** = tokens per minute. Request preflight counts prompt/input tokens
plus an explicit output reservation when the request includes `max_tokens`,
`max_completion_tokens`, or `max_output_tokens`. If no maximum output is
present, preflight uses prompt/input tokens only.
## Per-key limits
Per-key RPM/TPM limits are configured on the token in the console. Use them
when one product, environment, or integration needs its own ceiling without
slowing the rest of the account.
- `0` means no key-level cap on that dimension; the account tier still applies.
- The effective cap is the stricter of the key cap and the account tier cap.
- Keys can carry an optional product label and JSON metadata for operational
attribution and audits.
- Token policy changes are audit-logged without storing the plaintext key.
## How tier is determined
- New account = `Tier0` after first successful top-up, `Unverified` before.
- Tier auto-adjusts daily at 04:30 (Asia/Shanghai) based on 30-day rolling
spend.
- A single top-up immediately upgrades you to the tier matching your
lifetime topup total — you don't have to wait for the daily job.
> [info]
Promotional credits ("free $5 to try Lazu", referral bonuses, admin-added
quota) do **not** count as funding. You stay `Unverified` until you complete a
real top-up with a payment method.
## When you hit a limit
HTTP `429` with:
```json
{
"error": {
"message": "Request rate limit exceeded (60/min)",
"type": "rate_limit_exceeded",
"code": "request_rate_limit_exceeded"
}
}
```
`request_rate_limit_exceeded` means an account/tier or success-request cap was
hit. `token_rate_limit_exceeded` means the individual key's RPM/TPM cap was
hit. `total_request_rate_limit_exceeded` is the legacy total-request guard.
Response headers include `Retry-After: 60` (seconds).
Best practice: catch `429`, sleep `Retry-After` seconds, then retry with
exponential backoff if you hit it twice in a row. The major OpenAI / Anthropic
SDKs already do this — make sure you haven't disabled retries.
## Streaming concurrency
Streaming (`stream: true`) responses count as **one request** for RPM. For TPM
preflight, Lazu uses the same prompt + explicit max-output reservation rule as
non-streaming requests. If you omit a max-output value, only prompt/input tokens
are available to the preflight limiter.
There's no separate "concurrent streams" cap beyond the RPM/TPM math.
## Per-vendor sub-limits
Lazu doesn't enforce vendor-side limits — upstream providers like OpenAI
and Anthropic still apply their own caps to the underlying API key pool.
On a busy day you may see upstream `429` or `503` propagate through. Lazu's
routing will retry against backup channels in the same lane when possible.
## Need higher limits?
For sustained high-throughput workloads (1,000+ RPM, several million TPM),
contact support via [lazu.ai](https://lazu.ai/) — limits can be raised
per-account with no public commitment.
## See also
- [Errors](/errors) — full error code table
- [Billing](/billing) — how spend rolls up to tier
- [Pricing & lanes](/models/pricing) — choosing direct vs cheap
# 请求频率限制
# 请求频率限制
Lazu 用三层限制保护后端：
1. **账号层级 RPM/TPM**：账号会根据消费进入 `Tier0..Tier3`，层级越高限制越高。
2. **未验证账号防滥用限制**：没有成功充值过的账号会被限制在很低的请求速率。
3. **单 key RPM/TPM**：你可以给单个 API Key 设置更严格的限制，用于产品或 workload 隔离。
单 key 限制只能变得更严格，不能突破账号层级上限。
## 默认限制
| 层级 | 条件 | RPM | TPM |
| -------------- | ------------------------- | --: | --------: |
| **Unverified** | 尚未成功充值 | 5 | 5,000 |
| Tier 0 | 已验证，30 天消费低于 $10 | 60 | 100,000 |
| Tier 1 | 30 天消费大于等于 $10 | 120 | 300,000 |
| Tier 2 | 30 天消费大于等于 $100 | 300 | 1,000,000 |
| Tier 3 | 30 天消费大于等于 $1,000 | 600 | 2,000,000 |
- **RPM** = 每分钟请求数，使用滚动 60 秒窗口。
- **TPM** = 每分钟 token 数。预检会统计 prompt/input tokens；当请求显式包含
`max_tokens`、`max_completion_tokens` 或 `max_output_tokens` 时，也会把输出
token 预留量计入预检。
## 单 key 限制
单 key RPM/TPM 在控制台的 API Key 设置中配置：
- `0` 表示该维度没有 key 级限制，但账号层级限制仍然生效。
- 最终生效值是 key 限制和账号层级限制中更严格的那个。
- key 可带产品标签和 JSON metadata，方便运维归因和审计。
- 策略变更会写入审计日志，不存储明文 key。
## 层级如何计算
- 新账号充值前是 `Unverified`，首次成功充值后进入 `Tier0`。
- 层级每天 04:30（Asia/Shanghai）按 30 天滚动消费自动更新。
- 单次充值也会立即按 lifetime top-up total 升级，不必等待定时任务。
> [info]
体验金、推荐奖励或管理员赠送额度不算真实充值。要解除未验证账号限制，需要完成一次真实支付。
## 触发限制时
HTTP `429` 响应通常是：
```json
{
"error": {
"message": "Request rate limit exceeded (60/min)",
"type": "rate_limit_exceeded",
"code": "request_rate_limit_exceeded"
}
}
```
常见 code：
- `request_rate_limit_exceeded`：触发账号层级或请求速率限制。
- `token_rate_limit_exceeded`：触发单个 API Key 的 RPM/TPM 限制。
- `total_request_rate_limit_exceeded`：旧版总请求保护。
响应会包含 `Retry-After`，客户端应等待对应秒数后重试，并使用指数退避。
## Stream 请求
`stream: true` 的响应在 RPM 上按一次请求计算。TPM 预检规则和普通请求一致：
prompt/input tokens 加上显式的最大输出 token 预留量。
## 上游 provider 限制
Lazu 不会消除上游 provider 自己的限制。OpenAI、Anthropic 等 provider
仍可能返回上游 `429` 或 `503`。可用时，Lazu 会尝试同 lane 的备用 channel。
## 需要更高限制
持续高吞吐场景（例如 1,000+ RPM 或数百万 TPM）请通过
[lazu.ai](https://lazu.ai/) 联系支持。
## 相关页面
- [错误码](/zh/errors)
- [计费规则](/zh/billing)
- [定价与渠道](/zh/models/pricing)
# 請求頻率限制
# 請求頻率限制
Lazu 用三層限制保護後端：
1. **帳號層級 RPM/TPM**：帳號會根據消費進入 `Tier0..Tier3`，層級越高限制越高。
2. **未驗證帳號防濫用限制**：沒有成功儲值過的帳號會被限制在很低的請求速率。
3. **單 key RPM/TPM**：你可以給單一 API Key 設定更嚴格的限制，用於產品或 workload 隔離。
單 key 限制只能變得更嚴格，不能突破帳號層級上限。
## 預設限制
| 層級 | 條件 | RPM | TPM |
| -------------- | ------------------------- | --: | --------: |
| **Unverified** | 尚未成功儲值 | 5 | 5,000 |
| Tier 0 | 已驗證，30 天消費低於 $10 | 60 | 100,000 |
| Tier 1 | 30 天消費大於等於 $10 | 120 | 300,000 |
| Tier 2 | 30 天消費大於等於 $100 | 300 | 1,000,000 |
| Tier 3 | 30 天消費大於等於 $1,000 | 600 | 2,000,000 |
- **RPM** = 每分鐘請求數，使用滾動 60 秒視窗。
- **TPM** = 每分鐘 token 數。預檢會統計 prompt/input tokens；當請求包含
`max_tokens`、`max_completion_tokens` 或 `max_output_tokens` 時，也會把輸出
token 預留量計入。
## 單 key 限制
- `0` 表示該維度沒有 key 級限制，但帳號層級限制仍生效。
- 最終生效值是 key 限制和帳號層級限制中更嚴格的那個。
- key 可帶產品標籤和 JSON metadata，方便運維歸因和稽核。
> [info]
試用額度、推薦獎勵或管理員贈送額度不算真實儲值。要解除未驗證帳號限制，需要完成一次真實付款。
## 觸發限制時
HTTP `429` 會返回 `rate_limit_exceeded` 類型錯誤。常見 code：
- `request_rate_limit_exceeded`：觸發帳號層級或請求速率限制。
- `token_rate_limit_exceeded`：觸發單一 API Key 的 RPM/TPM 限制。
- `total_request_rate_limit_exceeded`：舊版總請求保護。
響應會包含 `Retry-After`，用戶端應等待對應秒數後重試，並使用指數退避。
## 相關頁面
- [錯誤碼](/zh-TW/errors)
- [計費規則](/zh-TW/billing)
- [定價與通道](/zh-TW/models/pricing)
# レート制限
# レート制限
Lazu は 3 層の制限で backend を保護します。
1. **Tier-based RPM/TPM**：アカウントは支出に応じて `Tier0..Tier3` に属します。
2. **未認証アカウントの abuse 対策**：実際の top-up がないアカウントは低い rate に制限されます。
3. **Per-key RPM/TPM**：個別の API Key にさらに厳しい上限を設定できます。
per-key limit はアカウント tier の上限を引き上げません。より厳しくするだけです。
## デフォルト
| Tier | 条件 | RPM | TPM |
| -------------- | -------------------------- | --: | --------: |
| **Unverified** | 成功した top-up がまだない | 5 | 5,000 |
| Tier 0 | verified、30 日支出 < $10 | 60 | 100,000 |
| Tier 1 | 30 日支出 >= $10 | 120 | 300,000 |
| Tier 2 | 30 日支出 >= $100 | 300 | 1,000,000 |
| Tier 3 | 30 日支出 >= $1,000 | 600 | 2,000,000 |
- **RPM** = requests per minute。
- **TPM** = tokens per minute。preflight は prompt/input tokens を数え、明示的な
`max_tokens`、`max_completion_tokens`、`max_output_tokens` がある場合は出力予約分も含めます。
> [info]
Promotional credits や admin-added quota は funding
として扱われません。未認証制限を解除するには実際の top-up が必要です。
## 429 の読み方
`request_rate_limit_exceeded` はアカウント tier または request rate の上限です。
`token_rate_limit_exceeded` は個別 API Key の RPM/TPM 上限です。レスポンスの
`Retry-After` 秒数を待ってから指数バックオフで再試行してください。
## 関連ページ
- [エラーコード](/ja/errors)
- [料金体系](/ja/billing)
- [料金と経路](/ja/models/pricing)
# Model catalog
# Model catalog
Lazu publishes the full set of models a given API key can access. Read this
catalog at runtime instead of hardcoding model names — new models get added,
old ones get deprecated, and which models a key can reach depends on the
key's scope.
## GET `/api/models/catalog`
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY"
```
Response (abridged):
```json
{
"object": "list",
"data": [
{
"id": "gpt-4o-mini",
"object": "model",
"name": "gpt-4o-mini",
"provider": "openai",
"owned_by": "openai",
"modality": {
"input": ["text", "image"],
"output": ["text"]
},
"capabilities": {
"supports_function_calling": true,
"supports_parallel_function_calling": true,
"supports_vision": true,
"supports_reasoning": false,
"supports_response_schema": true,
"supports_prompt_caching": true
},
"supported_endpoint_types": ["openai", "openai-response"],
"supported_endpoints": [
{ "type": "openai", "path": "/v1/chat/completions", "method": "POST" },
{ "type": "openai-response", "path": "/v1/responses", "method": "POST" }
],
"default_endpoint_type": "openai",
"context_length": 128000,
"max_output_tokens": 16384,
"pricing": {
"currency": "USD",
"billing_type": "per_token",
"input": 0.15,
"output": 0.6,
"cache_read": 0.075,
"pricing_version": 3
},
"usage_capabilities": {
"reported_dimensions": [
"input",
"output",
"cache_read",
"cache_write",
"cache_write_5m",
"cache_write_1h"
],
"billable_dimensions": [
"input",
"output",
"cache_read",
"cache_write_5m"
],
"response_fields": {
"openai_compatible": [
"usage.prompt_tokens_details.cached_tokens",
"usage.prompt_tokens_details.cache_write_tokens",
"usage.prompt_tokens_details.cache_write_5m_tokens"
],
"request_detail": [
"usage.dimensions",
"billing.line_items",
"provider_usage.raw_fields"
]
}
},
"supported_parameters": [
"tools",
"tool_choice",
"response_format",
"cache_control"
],
"parameters": {
"model": { "type": "string", "required": true },
"messages": { "type": "array", "required": true },
"temperature": { "type": "float", "default": 1, "range": [0, 2] },
"max_tokens": { "type": "integer", "default": 1024 },
"stream": { "type": "boolean", "default": false }
},
"example": {
"curl": "curl https://api.lazu.ai/v1/chat/completions ..."
}
},
"..."
]
}
```
## Picking a model
| You want | Filter on | Common endpoint |
| -------------------- | ------------------------------------------------- | ----------------------------------------- |
| Text chat | `modality.output` includes `text` | `/v1/chat/completions` |
| Multimodal (vision) | `modality.input` includes `image` | `/v1/chat/completions` or `/v1/responses` |
| Reasoning (o-series) | `capabilities.supports_reasoning === true` | `/v1/responses` (recommended) |
| Embeddings | `supported_endpoint_types` includes `embeddings` | `/v1/embeddings` |
| Tool / function call | `capabilities.supports_function_calling === true` | `/v1/chat/completions` |
Use `default_endpoint_type` unless your client SDK specifically needs a
native provider endpoint (Anthropic's `/v1/messages`, Gemini's
`/v1beta/models/…:generateContent`, etc.).
## Usage and cache metadata
Each model includes `usage_capabilities` so production clients can discover
which usage dimensions may appear before sending traffic. This matters for
prompt caching because providers do not use one shared field set.
| Dimension | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cache_read` | Cached input tokens read from an existing cache entry. In OpenAI-compatible responses this appears as `usage.prompt_tokens_details.cached_tokens` or `usage.input_tokens_details.cached_tokens`. |
| `cache_write` | Cache creation/write tokens when the provider reports a total but not a TTL bucket. |
| `cache_write_5m` | Cache creation/write tokens for a 5-minute TTL bucket. |
| `cache_write_1h` | Cache creation/write tokens for a 1-hour TTL bucket. |
| `cache_miss` | Cache misses reported separately by the provider, for example DeepSeek `prompt_cache_miss_tokens`. |
Provider notes:
- OpenAI-compatible cache reads use `cached_tokens`; OpenAI chat responses do
not expose a separate cache-write token count.
- Anthropic reports cache reads and cache creation, including 5-minute and
1-hour buckets when available.
- Gemini reports cached content reads through `cachedContentTokenCount`.
- Qwen/DashScope may report `cached_tokens` and cache creation fields,
including Anthropic-compatible cache field names on some routes.
- DeepSeek reports `prompt_cache_hit_tokens` and
`prompt_cache_miss_tokens`; Lazu normalizes hits to `cache_read` and misses
to `cache_miss`.
Use `reported_dimensions` to decide which fields may appear, and
`billable_dimensions` to decide which dimensions can affect price for the
current catalog price context.
## Listing via `/v1/models`
If your SDK uses OpenAI-style `models.list()`, Lazu also serves a flatter
OpenAI-compatible response at `/v1/models`:
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
See [Models list](/endpoints/models) for the exact schema.
## Pricing detail
Each catalog entry has a `pricing` object for the current API key's effective
catalog price. See [Pricing & lanes](/models/pricing) for how routing lane
preferences affect the price returned for a key.
# 模型目录
# 模型目录
Lazu 会按当前 API Key 返回可访问模型集合。生产客户端、agent 和脚本应在运行时读取
catalog，而不是把模型名写死。模型是否可用取决于 key 的权限、channel 状态和模型配置。
## GET `/api/models/catalog`
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY"
```
响应会包含：
- `id`、`provider`、`owned_by`
- `modality.input` / `modality.output`
- `capabilities`
- `supported_endpoint_types`
- `supported_endpoints`
- `default_endpoint_type`
- `context_length`、`max_output_tokens`
- 当前 key 的有效 `pricing`
- `usage_capabilities`
- `supported_parameters` 和 `parameters`
- 可直接复用的 `example`
## 如何选模型
| 需求 | 关注字段 | 常用 endpoint |
| --------------- | ------------------------------------------------- | ----------------------------------------- |
| 文本聊天 | `modality.output` 包含 `text` | `/v1/chat/completions` |
| 多模态/图片输入 | `modality.input` 包含 `image` | `/v1/chat/completions` 或 `/v1/responses` |
| 推理模型 | `capabilities.supports_reasoning === true` | `/v1/responses` |
| Embeddings | `supported_endpoint_types` 包含 `embeddings` | `/v1/embeddings` |
| 工具调用 | `capabilities.supports_function_calling === true` | `/v1/chat/completions` |
除非客户端 SDK 明确需要 Anthropic/Gemini 原生接口，否则优先使用
`default_endpoint_type`。
## Usage 和 cache metadata
每个模型都有 `usage_capabilities`，让客户端在发请求前知道可能出现哪些 usage 维度：
| 维度 | 含义 |
| ---------------- | --------------------------------------------------- |
| `cache_read` | 命中并读取已有 cache 的输入 token |
| `cache_write` | provider 返回总 cache write token 但没有 TTL bucket |
| `cache_write_5m` | 5 分钟 TTL 的 cache creation/write token |
| `cache_write_1h` | 1 小时 TTL 的 cache creation/write token |
| `cache_miss` | provider 单独上报的 cache miss token |
不同 provider 的字段不同：OpenAI 常见 `cached_tokens`；Anthropic 会上报 cache
creation/read；Gemini 使用 cached content 计数；DeepSeek 使用
`prompt_cache_hit_tokens` 和 `prompt_cache_miss_tokens`，Lazu 会标准化为
`cache_read` 和 `cache_miss`。
使用 `reported_dimensions` 判断哪些字段可能出现，使用 `billable_dimensions`
判断哪些维度会影响价格。
## `/v1/models`
如果你的 SDK 调用 OpenAI 风格的 `models.list()`，Lazu 也提供扁平响应：
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
但它只适合 SDK 兼容。需要路由、价格、能力、参数和 usage metadata 时，请使用
`/api/models/catalog`。
## 相关页面
- [模型列表](/zh/endpoints/models)
- [定价与渠道](/zh/models/pricing)
# 模型目錄
# 模型目錄
Lazu 會按目前 API Key 返回可存取模型集合。生產用戶端、agent 和腳本應在執行時讀取
catalog，而不是把模型名稱寫死。
## GET `/api/models/catalog`
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY"
```
響應會包含：
- `id`、`provider`、`owned_by`
- `modality.input` / `modality.output`
- `capabilities`
- `supported_endpoint_types`
- `supported_endpoints`
- `default_endpoint_type`
- `context_length`、`max_output_tokens`
- 目前 key 的有效 `pricing`
- `usage_capabilities`
- `supported_parameters` 和 `parameters`
## 如何選模型
| 需求 | 關注欄位 | 常用 endpoint |
| --------------- | ------------------------------------------------- | ----------------------------------------- |
| 文字聊天 | `modality.output` 包含 `text` | `/v1/chat/completions` |
| 多模態/圖片輸入 | `modality.input` 包含 `image` | `/v1/chat/completions` 或 `/v1/responses` |
| 推理模型 | `capabilities.supports_reasoning === true` | `/v1/responses` |
| Embeddings | `supported_endpoint_types` 包含 `embeddings` | `/v1/embeddings` |
| 工具呼叫 | `capabilities.supports_function_calling === true` | `/v1/chat/completions` |
除非用戶端 SDK 明確需要 Anthropic/Gemini 原生介面，否則優先使用
`default_endpoint_type`。
## Usage 和 cache metadata
每個模型都有 `usage_capabilities`，讓用戶端在發請求前知道可能出現哪些 usage 維度：
| 維度 | 含義 |
| ---------------- | --------------------------------------------------- |
| `cache_read` | 命中並讀取既有 cache 的輸入 token |
| `cache_write` | provider 返回總 cache write token 但沒有 TTL bucket |
| `cache_write_5m` | 5 分鐘 TTL 的 cache creation/write token |
| `cache_write_1h` | 1 小時 TTL 的 cache creation/write token |
| `cache_miss` | provider 單獨上報的 cache miss token |
使用 `reported_dimensions` 判斷哪些欄位可能出現，使用 `billable_dimensions`
判斷哪些維度會影響價格。
## `/v1/models`
如果你的 SDK 呼叫 OpenAI 風格的 `models.list()`，Lazu 也提供扁平響應：
```bash
curl https://api.lazu.ai/v1/models \
-H "Authorization: Bearer $LAZU_API_KEY"
```
但它只適合 SDK 相容。需要路由、價格、能力、參數和 usage metadata 時，請使用
`/api/models/catalog`。
## 相關頁面
- [模型列表](/zh-TW/endpoints/models)
- [定價與通道](/zh-TW/models/pricing)
# モデルカタログ
# モデルカタログ
Lazu は現在の API Key がアクセスできるモデル集合を返します。本番クライアント、
agent、スクリプトはモデル名を hard-code せず、実行時に catalog を読んでください。
## GET `/api/models/catalog`
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY"
```
レスポンスには次の情報が含まれます。
- `id`、`provider`、`owned_by`
- `modality.input` / `modality.output`
- `capabilities`
- `supported_endpoint_types`
- `supported_endpoints`
- `default_endpoint_type`
- `context_length`、`max_output_tokens`
- 現在の key に対する有効な `pricing`
- `usage_capabilities`
- `supported_parameters` と `parameters`
## モデルの選び方
| 目的 | 見る field | 一般的な endpoint |
| ---------------- | ------------------------------------------------- | --------------------------------------------- |
| テキストチャット | `modality.output` に `text` がある | `/v1/chat/completions` |
| 画像入力 | `modality.input` に `image` がある | `/v1/chat/completions` または `/v1/responses` |
| reasoning | `capabilities.supports_reasoning === true` | `/v1/responses` |
| embeddings | `supported_endpoint_types` に `embeddings` がある | `/v1/embeddings` |
| tool calling | `capabilities.supports_function_calling === true` | `/v1/chat/completions` |
SDK が明示的に Anthropic/Gemini ネイティブ endpoint を必要としない限り、
`default_endpoint_type` を優先してください。
## Usage と cache metadata
`usage_capabilities` は、リクエスト前にどの usage dimension が返る可能性があるかを示します。
`reported_dimensions` は出現可能な dimension、`billable_dimensions` は価格に影響する
dimension です。
## `/v1/models`
OpenAI style の `models.list()` が必要な SDK には `/v1/models` もあります。ただし、
routing、pricing、modality、parameter、usage metadata が必要なら `/api/models/catalog`
を使ってください。
## 関連ページ
- [モデル一覧](/ja/endpoints/models)
- [料金と経路](/ja/models/pricing)
# Pricing & lanes
# Pricing & lanes
Lazu shows three numbers on every model:
1. **Official reference price** — the upstream provider's public price for
comparison. We don't bill this; it's only here so you can see how much
Lazu saves vs. paying the provider direct.
2. **Direct lane price** — what we charge when routing via first-party /
official cloud (OpenAI direct, Anthropic direct, Azure, AWS, GCP).
3. **Cheap lane price** — what we charge when routing via a lower-cost
path. Available only for some models / vendors. Slightly less consistent
uptime in exchange for big cost savings.
## What `direct` and `cheap` mean
| Lane | What it routes to | When to use |
| -------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| `direct` | First-party endpoints + major cloud (Azure / AWS / GCP) | Production, regulated workloads, latency-sensitive |
| `cheap` | Lower-cost third-party paths | Batch jobs, experiments, prototyping, anything cost-sensitive |
Every model is guaranteed to have a `direct` lane. `cheap` is opt-in per
model — some models (small open-source, embeddings, Cloudflare Workers AI)
only ship as `direct` because there's no meaningful cheaper path.
## Example: gpt-4o-mini
```
gpt-4o-mini Context: 128K
─────────────────────────────────────────────────
input /1M output /1M
Official (reference) $0.15 $0.60
─────────────────────────────────────────────────
direct $0.14 $0.56
discount -6.7% -6.7%
─────────────────────────────────────────────────
cheap $0.05 $0.20
discount -66.7% -66.7%
```
Both lanes are billed per token, in microUSD precision. Your dashboard's
USD figure is rounded for display.
## Picking a lane per vendor
In the [console → API keys](https://lazu.ai/console/token), open a key and
expand **Advanced**. For each vendor you can choose:
- **direct** — always route this vendor's models through direct lane
- **cheap** — prefer cheap lane; fall back to direct if no cheap route
exists for the requested model
If you don't configure anything, the default is **cheap** — most users want
the cheapest available option.
> [info]
Lane is chosen **per vendor**, not per model. A key set to `cheap` for OpenAI
will use the cheap lane for every OpenAI model that has one, and fall back to
direct for models that don't.
## Fallback behaviour
If you ask for `cheap` but the requested model only ships as `direct`,
Lazu transparently falls back to `direct`:
- Request succeeds with HTTP 200
- Response header: `X-Lazu-Lane-Fallback: cheap->direct`
- You're billed at the **direct** lane price (since that's what served you)
If you ask for `direct` but no direct channel exists, Lazu returns
HTTP 404 `model_not_found` — we don't silently downgrade. This is to
avoid surprising regulated workloads with non-direct routing.
## What's NOT charged extra
Some token categories are billed at the lane's headline price, **without
any extra Lazu markup or hidden surcharge**:
- Prompt caching reads (when supported by the model)
- Cache writes (5-minute and 1-hour)
- Audio input/output tokens
- Image input tokens
- Per-call image / video generation cost
The same prompt sent to the same lane always bills the same way; there's no
"premium tier discount" or "loyalty multiplier" layered on top.
## API: reading effective prices programmatically
The model catalog returns the effective catalog price for the current API key.
Use `/api/models/catalog` when token-scoped access matters; use `/api/pricing`
only when you need the public list-pricing view.
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY" \
| jq '.data[] | select(.id=="gpt-4o-mini") | .pricing'
```
```json
{
"currency": "USD",
"billing_type": "per_token",
"input": 0.05,
"output": 0.2,
"cache_read": 0.025,
"pricing_version": 12,
"updated_at": "2026-06-01T00:00:00Z"
}
```
For agents and scripts: read `/api/models/catalog` at startup and choose from
models the key can actually access. Lane preference is configured on the API
key; the returned `pricing` object is the price that key should use for
estimation.
## When prices change
We update prices when upstream providers change theirs, and announce in the
[Changelog](/changelog). Active billing is always at the price in effect at
**request time** — we never retroactively re-bill.
# 定价与渠道
# 定价与渠道
Lazu 在模型页展示三类价格：
1. **官方参考价**：上游 provider 公布价格，仅用于对比。
2. **direct lane 价格**：通过官方或一方云路径路由时的价格。
3. **cheap lane 价格**：通过更低成本路径路由时的价格，适合实验、批处理和成本敏感场景。
## direct 和 cheap 的区别
| Lane | 路由到哪里 | 适合场景 |
| -------- | ----------------------------------------- | -------------------------------- |
| `direct` | 官方 endpoint 或主流云：Azure / AWS / GCP | 生产、合规、延迟敏感 workload |
| `cheap` | 更低成本的第三方路径 | 批处理、实验、原型、成本敏感任务 |
每个模型至少有 `direct` lane。`cheap` 按模型和 vendor 单独启用；不是所有模型都有。
## 按 vendor 设置 lane
在 [控制台 -> API Keys](https://lazu.ai/console/token) 打开一个 key 的
**Advanced** 设置，可以为每个 vendor 选择：
- **direct**：该 vendor 的模型总是走 direct lane。
- **cheap**：优先 cheap；如果请求模型没有 cheap route，则回退到 direct。
如果没有配置，默认偏好是 **cheap**。
> [info]
Lane 是按 vendor 选择，不是按单个模型选择。OpenAI 设置为 cheap 时，所有有
cheap route 的 OpenAI 模型都会优先走 cheap；没有 cheap route 的模型会回退
direct。
## Fallback 行为
如果请求 cheap，但目标模型只有 direct：
- 请求仍返回 HTTP 200
- 响应头包含 `X-Lazu-Lane-Fallback: cheap->direct`
- 按 direct lane 价格计费
如果请求 direct 但没有 direct channel，Lazu 返回 HTTP 404 `model_not_found`，不会静默降级。
## 通过 API 读取有效价格
对 agent 和脚本，推荐启动时读取 `/api/models/catalog`：
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY" \
| jq '.data[] | select(.id=="gpt-4o-mini") | .pricing'
```
返回的 `pricing` 已经是当前 API Key 的有效价格，包含它的 lane 偏好和可访问范围。
只有需要公开 list-pricing 视图时才使用 `/api/pricing`。
## 价格变更
当上游 provider 调整价格时，Lazu 会更新价格并在 [更新日志](/zh/changelog)
说明。实际扣费始终按请求发生时生效的价格计算，不会 retroactively re-bill。
## 相关页面
- [模型目录](/zh/models/catalog)
- [计费规则](/zh/billing)
# 定價與通道
# 定價與通道
Lazu 在模型頁展示三類價格：
1. **官方參考價**：上游 provider 公布價格，僅用於比較。
2. **direct lane 價格**：透過官方或一方雲路徑路由時的價格。
3. **cheap lane 價格**：透過更低成本路徑路由時的價格，適合實驗、批次處理和成本敏感場景。
## direct 和 cheap 的差異
| Lane | 路由到哪裡 | 適合場景 |
| -------- | ----------------------------------------- | ---------------------------------- |
| `direct` | 官方 endpoint 或主流雲：Azure / AWS / GCP | 生產、合規、延遲敏感 workload |
| `cheap` | 更低成本的第三方路徑 | 批次處理、實驗、原型、成本敏感任務 |
每個模型至少有 `direct` lane。`cheap` 按模型和 vendor 單獨啟用；不是所有模型都有。
## 按 vendor 設定 lane
在 [控制台 -> API Keys](https://lazu.ai/console/token) 開啟一把 key 的
**Advanced** 設定，可以為每個 vendor 選擇 direct 或 cheap。沒有設定時，預設偏好是
**cheap**。
> [info]
Lane 是按 vendor 選擇，不是按單一模型選擇。OpenAI 設為 cheap 時，所有有 cheap
route 的 OpenAI 模型都會優先走 cheap；沒有 cheap route 的模型會回退 direct。
## Fallback 行為
如果請求 cheap，但目標模型只有 direct，請求仍會成功，響應頭包含
`X-Lazu-Lane-Fallback: cheap->direct`，並按 direct lane 價格計費。如果請求 direct
但沒有 direct channel，Lazu 返回 HTTP 404 `model_not_found`。
## 透過 API 讀取有效價格
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY" \
| jq '.data[] | select(.id=="gpt-4o-mini") | .pricing'
```
返回的 `pricing` 已經是目前 API Key 的有效價格。只有需要公開 list-pricing 視圖時才使用
`/api/pricing`。
## 相關頁面
- [模型目錄](/zh-TW/models/catalog)
- [計費規則](/zh-TW/billing)
# 料金と経路
# 料金と経路
Lazu は各モデルに 3 つの価格を表示します。
1. **Official reference price**：upstream provider の公開価格。比較用であり、この価格で請求しません。
2. **Direct lane price**：first-party または主要 cloud 経路で routing する価格。
3. **Cheap lane price**：低コスト経路で routing する価格。実験、batch、cost-sensitive な用途向けです。
## direct と cheap
| Lane | routing 先 | 使う場面 |
| -------- | ---------------------------------- | ---------------------- |
| `direct` | 公式 endpoint や Azure / AWS / GCP | 本番、規制対象、低遅延 |
| `cheap` | 低コスト third-party 経路 | batch、実験、prototype |
すべてのモデルには `direct` lane があります。`cheap` は model/vendor ごとに有効化されます。
## vendor ごとの lane 設定
[コンソール -> API Keys](https://lazu.ai/console/token) で key を開き、**Advanced**
から vendor ごとの lane preference を設定できます。未設定なら既定は **cheap** です。
> [info]
Lane は model 単位ではなく vendor 単位で選択します。OpenAI を cheap
にすると、cheap route を持つ OpenAI model は cheap を優先し、ない場合は direct
に fallback します。
## API から有効価格を読む
agent や script は起動時に `/api/models/catalog` を読み、現在の API Key が実際に使える
モデルと価格を使ってください。
```bash
curl https://api.lazu.ai/api/models/catalog \
-H "Authorization: Bearer $LAZU_API_KEY" \
| jq '.data[] | select(.id=="gpt-4o-mini") | .pricing'
```
## 関連ページ
- [モデルカタログ](/ja/models/catalog)
- [料金体系](/ja/billing)
# Quickstart
# Quickstart
## 1. Get an API key
Sign in to the [Lazu console](https://lazu.ai/console), open **API keys** and
click **Create key**. Copy the key (it starts with `sk-lazu-…`).
## 2. Pick a base URL
```
https://api.lazu.ai
```
For self-hosted Lazu, replace with your domain.
## 3. Make a request
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer $LAZU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Say hello from Lazu"}
]
}'
```
### Python (OpenAI SDK)
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say hello from Lazu"}],
)
print(resp.choices[0].message.content)
```
### TypeScript (OpenAI SDK)
```ts
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Say hello from Lazu" }],
});
console.log(resp.choices[0].message.content);
```
## 4. Next steps
- Browse available models: [Catalog](/models/catalog)
- See pricing per lane: [Pricing](/models/pricing)
- Stream responses, send images, upload PDFs: [Examples](/examples)
- Hit a rate limit?: [Rate limits](/limits) · [Errors](/errors)
# 快速开始
# 快速开始
## 1. 创建 API Key
登录 [Lazu 控制台](https://lazu.ai/console)，进入 **API Keys**，点击
**Create key**。复制生成的 key，它通常以 `sk-lazu-` 开头。
## 2. 选择 Base URL
```txt
https://api.lazu.ai
```
自部署 Lazu 时，把这个地址替换成你自己的 API 域名。
## 3. 发起请求
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer $LAZU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Say hello from Lazu"}
]
}'
```
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say hello from Lazu"}],
)
print(resp.choices[0].message.content)
```
### TypeScript
```ts
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Say hello from Lazu" }],
});
console.log(resp.choices[0].message.content);
```
## 4. 下一步
- 运行时发现模型：[模型目录](/zh/models/catalog)
- 查看不同通道价格：[定价与渠道](/zh/models/pricing)
- 学习 stream、图片和文件用法：[代码示例](/zh/examples)
- 排查 429 或鉴权错误：[请求频率限制](/zh/limits) · [错误码](/zh/errors)
# 快速開始
# 快速開始
## 1. 建立 API Key
登入 [Lazu 控制台](https://lazu.ai/console)，進入 **API Keys**，點擊
**Create key**。複製產生的 key，它通常以 `sk-lazu-` 開頭。
## 2. 選擇 Base URL
```txt
https://api.lazu.ai
```
自部署 Lazu 時，請把這個地址替換成你自己的 API 網域。
## 3. 發起請求
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer $LAZU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Say hello from Lazu"}
]
}'
```
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say hello from Lazu"}],
)
print(resp.choices[0].message.content)
```
### TypeScript
```ts
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Say hello from Lazu" }],
});
console.log(resp.choices[0].message.content);
```
## 4. 下一步
- 執行時發現模型：[模型目錄](/zh-TW/models/catalog)
- 查看不同通道價格：[定價與通道](/zh-TW/models/pricing)
- 學習 stream、圖片和檔案用法：[程式碼範例](/zh-TW/examples)
- 排查 429 或認證錯誤：[請求頻率限制](/zh-TW/limits) · [錯誤碼](/zh-TW/errors)
# クイックスタート
# クイックスタート
## 1. API Key を作成する
[Lazu コンソール](https://lazu.ai/console)にサインインし、**API Keys** を開いて
**Create key** をクリックします。生成された key は通常 `sk-lazu-` で始まります。
## 2. Base URL を選ぶ
```txt
https://api.lazu.ai
```
Self-hosted Lazu では、自分の API ドメインに置き換えてください。
## 3. リクエストする
### cURL
```bash
curl https://api.lazu.ai/v1/chat/completions \
-H "Authorization: Bearer $LAZU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Say hello from Lazu"}
]
}'
```
### Python
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.lazu.ai/v1",
api_key="YOUR_LAZU_KEY",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say hello from Lazu"}],
)
print(resp.choices[0].message.content)
```
### TypeScript
```ts
const client = new OpenAI({
baseURL: "https://api.lazu.ai/v1",
apiKey: process.env.LAZU_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Say hello from Lazu" }],
});
console.log(resp.choices[0].message.content);
```
## 次に読むページ
- 利用可能なモデルを確認する：[モデルカタログ](/ja/models/catalog)
- lane ごとの価格を見る：[料金と経路](/ja/models/pricing)
- stream、画像、ファイルを試す：[コードサンプル](/ja/examples)
- 429 や認証エラーを調べる：[レート制限](/ja/limits) · [エラーコード](/ja/errors)