# Build on one key.

An OpenAI-compatible gateway to the models your key can reach. Discover a model, call its endpoint, read the receipt.

**Base URL**: `https://api.lazu.ai/v1` · **Auth**: `Authorization: Bearer $LAZU_API_KEY` · **Index**: `https://lazu.ai/docs/llms.txt`

## Start

- [Quickstart](https://lazu.ai/docs/quickstart)
- [Authentication](https://lazu.ai/docs/authentication)
- [Model catalog](https://lazu.ai/docs/models/catalog)
- [Pricing & lanes](https://lazu.ai/docs/models/pricing)

## Endpoints

- [Chat completions](https://lazu.ai/docs/endpoints/chat)
- [Responses](https://lazu.ai/docs/endpoints/responses)
- [Embeddings](https://lazu.ai/docs/endpoints/embeddings)
- [Search](https://lazu.ai/docs/endpoints/search)
- [Files](https://lazu.ai/docs/endpoints/files)
- [Images, video and audio](https://lazu.ai/docs/endpoints/media)

## Reference

- [Errors](https://lazu.ai/docs/errors)
- [Rate limits](https://lazu.ai/docs/limits)
- [How pricing works](https://lazu.ai/docs/billing)
- [API Explorer](https://lazu.ai/docs/api-reference)
- [Changelog](https://lazu.ai/docs/changelog)

## Hello, Lazu

Change the base URL. Keep your 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-6-luna",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)
```

## Give these docs to your agent

[llms.txt](https://lazu.ai/docs/llms.txt)

---

# 一个 Key，接入所有模型。

OpenAI 兼容的网关，接入你的 Key 可用的所有模型。先查模型，再调接口，最后看回执。

**Base URL**: `https://api.lazu.ai/v1` · **Auth**: `Authorization: Bearer $LAZU_API_KEY` · **Index**: `https://lazu.ai/docs/llms.txt`

## 开始

- [快速开始](https://lazu.ai/docs/zh/quickstart)
- [鉴权](https://lazu.ai/docs/zh/authentication)
- [模型目录](https://lazu.ai/docs/zh/models/catalog)
- [定价与渠道](https://lazu.ai/docs/zh/models/pricing)

## 接口

- [Chat completions](https://lazu.ai/docs/zh/endpoints/chat)
- [Responses](https://lazu.ai/docs/zh/endpoints/responses)
- [Embeddings](https://lazu.ai/docs/zh/endpoints/embeddings)
- [Search](https://lazu.ai/docs/zh/endpoints/search)
- [Files](https://lazu.ai/docs/zh/endpoints/files)
- [图片、视频与音频](https://lazu.ai/docs/zh/endpoints/media)

## 参考

- [错误码](https://lazu.ai/docs/zh/errors)
- [请求频率限制](https://lazu.ai/docs/zh/limits)
- [计费规则](https://lazu.ai/docs/zh/billing)
- [API Explorer](https://lazu.ai/docs/zh/api-reference)
- [更新日志](https://lazu.ai/docs/zh/changelog)

## Hello, Lazu

只改 base URL， 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-6-luna",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)
```

## 把文档交给你的 Agent

[llms.txt](https://lazu.ai/docs/llms.txt)

---

# 一把 Key，接入所有模型。

OpenAI 相容的閘道，接入你的 Key 可用的所有模型。先查模型，再呼叫介面，最後看回執。

**Base URL**: `https://api.lazu.ai/v1` · **Auth**: `Authorization: Bearer $LAZU_API_KEY` · **Index**: `https://lazu.ai/docs/llms.txt`

## 開始

- [快速開始](https://lazu.ai/docs/zh-TW/quickstart)
- [驗證](https://lazu.ai/docs/zh-TW/authentication)
- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)
- [定價與通道](https://lazu.ai/docs/zh-TW/models/pricing)

## 端點

- [Chat completions](https://lazu.ai/docs/zh-TW/endpoints/chat)
- [Responses](https://lazu.ai/docs/zh-TW/endpoints/responses)
- [Embeddings](https://lazu.ai/docs/zh-TW/endpoints/embeddings)
- [Search](https://lazu.ai/docs/zh-TW/endpoints/search)
- [Files](https://lazu.ai/docs/zh-TW/endpoints/files)
- [圖片、影片與音訊](https://lazu.ai/docs/zh-TW/endpoints/media)

## 參考

- [錯誤碼](https://lazu.ai/docs/zh-TW/errors)
- [請求頻率限制](https://lazu.ai/docs/zh-TW/limits)
- [計費規則](https://lazu.ai/docs/zh-TW/billing)
- [API Explorer](https://lazu.ai/docs/zh-TW/api-reference)
- [更新日誌](https://lazu.ai/docs/zh-TW/changelog)

## Hello, Lazu

只改 base URL， 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-6-luna",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)
```

## 把文件交給你的 Agent

[llms.txt](https://lazu.ai/docs/llms.txt)

---

# 1 つのキーで、すべてのモデルへ。

キーで使えるモデルにつながる OpenAI 互換ゲートウェイ。モデルを探し、エンドポイントを呼び、明細を読む。

**Base URL**: `https://api.lazu.ai/v1` · **Auth**: `Authorization: Bearer $LAZU_API_KEY` · **Index**: `https://lazu.ai/docs/llms.txt`

## はじめに

- [クイックスタート](https://lazu.ai/docs/ja/quickstart)
- [認証](https://lazu.ai/docs/ja/authentication)
- [モデルカタログ](https://lazu.ai/docs/ja/models/catalog)
- [料金と経路](https://lazu.ai/docs/ja/models/pricing)

## エンドポイント

- [Chat completions](https://lazu.ai/docs/ja/endpoints/chat)
- [Responses](https://lazu.ai/docs/ja/endpoints/responses)
- [Embeddings](https://lazu.ai/docs/ja/endpoints/embeddings)
- [Search](https://lazu.ai/docs/ja/endpoints/search)
- [Files](https://lazu.ai/docs/ja/endpoints/files)
- [画像・動画・音声](https://lazu.ai/docs/ja/endpoints/media)

## リファレンス

- [エラーコード](https://lazu.ai/docs/ja/errors)
- [レート制限](https://lazu.ai/docs/ja/limits)
- [料金体系](https://lazu.ai/docs/ja/billing)
- [API Explorer](https://lazu.ai/docs/ja/api-reference)
- [更新履歴](https://lazu.ai/docs/ja/changelog)

## Hello, Lazu

base URL を変えるだけ。 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-6-luna",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)
```

## ドキュメントをエージェントに渡す

[llms.txt](https://lazu.ai/docs/llms.txt)

---

# 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-6-luna",
    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
import OpenAI from "openai";

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-6-luna",
  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-6-luna",
    "messages": [
      {"role": "user", "content": "Reply with: Lazu test successful"}
    ]
  }'
```

## Streaming

```python
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    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"
```

> 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-6-luna",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用一段话解释模型路由。"},
    ],
)

print(response.choices[0].message.content)
```

### JavaScript

```javascript
import OpenAI from "openai";

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-6-luna",
  messages: [{ role: "user", content: "Hello from Lazu" }],
});

console.log(response.choices[0].message.content);
```

## 流式响应

```python
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    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"
```

> 用 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-6-luna",
    messages=[
        {"role": "system", "content": "你是一個有幫助的助手。"},
        {"role": "user", "content": "用一段話解釋模型路由。"},
    ],
)

print(response.choices[0].message.content)
```

### JavaScript

```javascript
import OpenAI from "openai";

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-6-luna",
  messages: [{ role: "user", content: "Hello from Lazu" }],
});

console.log(response.choices[0].message.content);
```

## 串流回應

```python
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    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"
```

> 用 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-6-luna",
    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
import OpenAI from "openai";

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-6-luna",
  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-6-luna",
    "messages": [
      {"role": "user", "content": "Reply with: Lazu test successful"}
    ]
  }'
```

## ストリーミング

```python
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    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"
```

> catalog レスポンスを使って、endpoint、モダリティ、パラメータを選んでください。
> Agent や SDK wrapper
> の中にグローバルなモデル一覧をハードコードしないでください。

## トラブルシューティング

すべてのレスポンスには `x-request-id` が含まれている必要があります。コンソールでこの ID を使うと、モデル、upstream channel、ステータス、トークン計上を追跡できます。

---

# 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](https://lazu.ai/docs/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`.

OpenAPI: `/openapi.json` · `/openapi.yaml`

---

# 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 连接。

OpenAPI: `/openapi.json` · `/openapi.yaml`

---

# 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 連線。

OpenAPI: `/openapi.json` · `/openapi.yaml`

---

# 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 接続ではなく非同期ジョブとポーリングを使用します。

OpenAPI: `/openapi.json` · `/openapi.yaml`

---

# Changelog

## 2026-09-30 — Agent sessions, receipts and long-context prices

- Rebuilt Agent sessions around tasks, models and individual request receipts ([#322](https://github.com/JessyTsui/lazu/pull/322)).
- Added session activity views and subagent lanes ([#327](https://github.com/JessyTsui/lazu/pull/327)). These show gateway activity; local tools are outside the observation boundary.
- Connected long-context pricing to cost calculation, request receipts and public model pages ([#333](https://github.com/JessyTsui/lazu/pull/333)). The actual tier depends on the configured model and lane.
- Corrected sitemap modification dates to reflect actual content changes ([#337](https://github.com/JessyTsui/lazu/pull/337)).

These dates refer to changes merged into the source repository. A self-hosted installation's availability depends on its deployed version. [Reconcile a session's costs](https://lazu.ai/docs/agent-session-costs) using the exported details.

## 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-09-30 — Agent 会话、请求回执与长上下文价格

- 围绕任务、模型和逐请求回执重做 Agent 会话（[#322](https://github.com/JessyTsui/lazu/pull/322)）。
- 增加会话活动视图与子代理线路（[#327](https://github.com/JessyTsui/lazu/pull/327)）；展示范围是网关活动，不包含本地工具执行。
- 将长上下文价格接入成本计算、请求回执与公开模型页（[#333](https://github.com/JessyTsui/lazu/pull/333)）；实际阶梯取决于模型与线路配置。
- sitemap 的修改日期改为真实内容变更时间（[#337](https://github.com/JessyTsui/lazu/pull/337)）。

以上日期指源码合并时间，自部署实例是否可用取决于部署版本。可按[会话费用核对指南](https://lazu.ai/docs/zh/agent-session-costs)复算导出的明细。

## 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-09-30 — Agent 工作階段、請求明細與長上下文价格

- 以任務、模型及逐請求明細重做 Agent 工作階段（[#322](https://github.com/JessyTsui/lazu/pull/322)）。
- 新增工作階段活動視圖與子代理路線（[#327](https://github.com/JessyTsui/lazu/pull/327)），觀測範圍為網關活動，不含本機工具。
- 長上下文價格接入成本計算、請求明細與公開模型頁（[#333](https://github.com/JessyTsui/lazu/pull/333)）；實際階梯依模型與路線設定。
- sitemap 修改日期採用真實內容變更時間（[#337](https://github.com/JessyTsui/lazu/pull/337)）。

日期為原始碼合併時間，自部署實例以部署版本為準。另見[工作階段費用核對指南](https://lazu.ai/docs/zh-TW/agent-session-costs)。

## 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-09-30 — Agent セッション、明細と長文脈料金

- タスク、モデル、個別請求明細を中心に Agent セッションを再構成しました（[#322](https://github.com/JessyTsui/lazu/pull/322)）。
- セッションの活動表示とサブエージェントのレーンを追加しました（[#327](https://github.com/JessyTsui/lazu/pull/327)）。ローカルツールの実行は観測対象外です。
- 長文脈料金を原価計算、請求明細、公開モデルページに接続しました（[#333](https://github.com/JessyTsui/lazu/pull/333)）。適用条件はモデルとレーンの設定によります。
- sitemap の更新日時を実際の内容変更日に修正しました（[#337](https://github.com/JessyTsui/lazu/pull/337)）。

日付はソースへのマージ日です。セルフホスト環境では導入バージョンを確認してください。[セッション費用の照合](https://lazu.ai/docs/ja/agent-session-costs)も参照してください。

## 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 に同期。
- リクエストとレスポンスのフィールド確認に使えるインタラクティブリファレンスを維持。

---

# Reconcile an Agent session

Lazu groups gateway requests by the session identifier sent by the client. A session is a view of API activity: it cannot observe local tools, editor time or every action an agent performs. Requests without a client session identifier cannot reliably identify a single task.

## From a task to its cost

1. Connect a client using the [Claude Code guide](https://lazu.ai/blog/claude-code-custom-api) or [Codex guide](https://lazu.ai/blog/codex-custom-provider).
2. Run a small task. In the console, open **Usage → Agent sessions** and select that task. Confirm the client, time window and models.
3. Read the session total, then open individual request receipts. Check input, output, cache reads, cache writes, lane and any applicable long-context or plan conditions. A failed request is not automatically a zero-charge request; read its receipt.
4. Load all available batches before exporting JSON. The coverage notice distinguishes loaded requests from retained requests and the durable session count. Expired records cannot be restored by pagination.

## A reproducible calculation

The repository includes a [reconciliation script](https://github.com/JessyTsui/lazu/blob/main/ops/scripts/summarize-agent-session.py) and a deliberately **synthetic** fixture. They are arithmetic examples, not customer results or current model prices.

```sh
python3 ops/scripts/summarize-agent-session.py ops/fixtures/agent-session.example.json
python3 ops/scripts/summarize-agent-session.py session.json
```

The fixture totals $0.015 across three requests. Only two have a comparable official price: $0.0145 charged against $0.020 official, a $0.0055 difference. That comparison excludes the third request and must not be applied to the whole session. The script exits unsuccessfully for incomplete exports or totals that do not reconcile, and suppresses the savings comparison. It prints no prompt text or request identifiers; model names and cost data may still be private.

## What the chart can establish

Request concurrency uses completion timestamps minus recorded durations, at whole-second resolution. Idle gaps between a thread's requests are not running time. Missing details suppress whole-session analysis. Cost changes around a compaction are observations from nearby requests, not proof that compaction caused the savings.

Session totals can remain after request details expire. First-message text is available only when content was captured and remains within the configured retention period. Before sharing an export, remove prompts, account information and any proprietary model identifiers, and obtain permission from its owner.

See [billing](https://lazu.ai/docs/billing) and [request receipts](https://lazu.ai/docs/endpoints/usage-requests) for the authoritative charge breakdown.

---

# 核对一次 Agent 会话的费用

Lazu 根据客户端发送的会话标识归集网关请求。会话展示的是 API 活动，无法观察本地工具、编辑器耗时或代理的所有动作。客户端不发送会话标识时，不能可靠地把同一 Key 的请求当成一项任务。

## 从任务找到费用

1. 按 [Claude Code 指南](https://lazu.ai/zh/blog/claude-code-custom-api)或 [Codex 指南](https://lazu.ai/zh/blog/codex-custom-provider)接入。
2. 执行一个小任务，在控制台的**用量与日志 → Agent 会话**中找到它，核对客户端、时间和模型。
3. 查看会话总额，再打开逐请求回执。核对输入、输出、缓存读写、线路，以及适用的长上下文和专属价格条件。请求失败不自动代表费用为零，应以回执为准。
4. 导出 JSON 前加载所有可读取批次。覆盖提示会区分已加载明细、仍保留的明细和会话总数；已经过期的数据无法通过翻页恢复。

## 可复算的例子

仓库提供[核对脚本](https://github.com/JessyTsui/lazu/blob/main/ops/scripts/summarize-agent-session.py)和**合成示例**。这是算术演示，不是客户实测，也不是当前模型报价。

```sh
python3 ops/scripts/summarize-agent-session.py ops/fixtures/agent-session.example.json
python3 ops/scripts/summarize-agent-session.py session.json
```

示例中三次请求合计 $0.015。只有两次具有官方可比价格：实际 $0.0145，对应官方 $0.020，差额 $0.0055。第三次请求不在比较范围内，不能把这个比例套到整个会话。导出不完整或费用加总不一致时，脚本返回失败并不输出节省比较。脚本不输出提示词与请求编号；模型名和费用本身仍可能是私有信息。

## 图表能够证明什么

请求并发使用完成时间减去记录耗时，精度为整秒。一个线程两次调用之间的空档不算正在运行。明细不完整时不生成全程分析。上下文压缩前后的费用差异只是相邻请求样本的观察，不能直接证明压缩带来了节省。

请求明细过期后，会话费用合计仍可保留。首条消息仅在已采集且未超过部署的内容保留期时可用。公开案例前，应移除提示词、账号信息、私有模型标识，并取得所有者授权。

具体计费以[计费规则](https://lazu.ai/docs/zh/billing)和[请求回执](https://lazu.ai/docs/zh/endpoints/usage-requests)为准。

---

# 核對 Agent 工作階段費用

Lazu 依客戶端傳送的工作階段識別碼彙整網關請求。它呈現 API 活動，無法觀察本機工具、編輯器耗時或代理的所有動作。沒有工作階段識別碼時，不能把同一 Key 的所有請求視為同一任務。

## 從任務核對到明細

1. 依 [Claude Code 指南](https://lazu.ai/blog/claude-code-custom-api)或 [Codex 指南](https://lazu.ai/blog/codex-custom-provider)接入。
2. 執行小任務，在控制台的用量頁開啟 Agent 工作階段，核對客戶端、時間和模型。
3. 查看總額及逐請求明細，核對輸入、輸出、快取讀寫、路線、長上下文和專屬價格條件。失敗不自動代表零費用。
4. 匯出 JSON 前載入所有可讀取的批次。已載入、仍保留和工作階段總數是不同數字；到期明細不能透過翻頁恢復。

## 可重現的算術示例

[核對腳本](https://github.com/JessyTsui/lazu/blob/main/ops/scripts/summarize-agent-session.py)附有**合成示例**，不是客戶實測或目前報價。

```sh
python3 ops/scripts/summarize-agent-session.py ops/fixtures/agent-session.example.json
python3 ops/scripts/summarize-agent-session.py session.json
```

三次請求合計 $0.015。其中兩次具有可比官方價格：實收 $0.0145，官方 $0.020，差額 $0.0055。第三次不在比較範圍，不能套用該比例推算整個工作階段。不完整或加總不一致時，腳本返回失敗並省略節省比較。輸出不含提示詞或請求編號，但模型名及費用仍可能需要保密。

## 分析範圍

並發以完成時間減去耗時估算，精度為整秒；同一執行緒兩次請求之間的空檔不算執行時間。明細不完整時不作全程分析。壓縮前後的平均費用差異只是相鄰樣本觀察，不能證明因果關係。

明細到期後可保留費用合計。首條訊息僅在已擷取且未超過內容保留期時可用。分享前請移除私有資料並取得所有者授權。另見[計費規則](https://lazu.ai/docs/zh-TW/billing)及[請求明細](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)。

---

# Agent セッションの費用を照合する

Lazu はクライアントが送信したセッション ID でゲートウェイのリクエストを集計します。ローカルツールやエディタ内の作業時間は観測できません。ID がない場合、同じ Key のリクエストを一つのタスクとみなすことはできません。

## タスクから請求明細へ

1. [Claude Code](https://lazu.ai/blog/claude-code-custom-api) または [Codex](https://lazu.ai/blog/codex-custom-provider) のガイドで接続します。
2. 小さなタスクを実行し、コンソールの使用量ページから Agent セッションを開きます。クライアント、時刻、モデルを確認します。
3. 合計から個別明細を開き、入力・出力・キャッシュの読み書き、レーン、長文脈や個別価格の条件を確認します。失敗したリクエストが無料とは限りません。
4. JSON をエクスポートする前に参照可能な全バッチを読み込みます。読み込み済み件数、保存中の件数、セッション総数は別です。期限切れの明細はページングで復元できません。

## 再計算できる例

リポジトリの[照合スクリプト](https://github.com/JessyTsui/lazu/blob/main/ops/scripts/summarize-agent-session.py)には**合成データ**を用意しています。顧客の実測値や現在のモデル価格ではありません。

```sh
python3 ops/scripts/summarize-agent-session.py ops/fixtures/agent-session.example.json
python3 ops/scripts/summarize-agent-session.py session.json
```

例の 3 件は合計 $0.015 です。公式価格と比較できるのは 2 件で、請求 $0.0145、公式 $0.020、差額 $0.0055 です。残りの 1 件を含めた全体にこの割合を適用できません。不完全な明細や合計不一致ではスクリプトは失敗終了し、節約比較を出力しません。プロンプトやリクエスト ID は出力しませんが、モデル名や金額も非公開情報となり得ます。

## 分析の限界

並列数は終了時刻と所要時間から秒単位で推定します。スレッド内の待機時間は実行時間に含めません。不完全な明細では全体分析を表示しません。圧縮前後の平均費用差は近傍標本の観察であり、因果関係の証明ではありません。

明細の保存期限後も合計は保持されます。最初のメッセージは記録され、保存期間内の場合のみ参照できます。共有前に私的情報を削除し、所有者の許可を得てください。[請求ルール](https://lazu.ai/docs/ja/billing)と[リクエスト明細](https://lazu.ai/docs/ja/endpoints/usage-requests)も参照してください。

---

# 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
import os
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
import os

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、本番で同じ 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 は即座に無効になります。

---

# Billing

Lazu uses prepaid balance. Charges depend on the selected model, lane and billable dimensions. Read the current catalog before estimating cost and the request receipt after completion.

## Prices and units

Token prices are USD per million tokens; multiply the token quantity by the price and divide by 1,000,000. Per-call prices are USD per billable invocation; per-second prices are USD per billable second. Audio input and output, cache reads and writes, and image input and output may have separate prices. Only use dimensions reported for the selected model; a missing price is not a promise of free service.

## Reservations and final charges

A reservation is an estimate, not final usage or a maximum charge. Provider usage takes priority. Partial output with incomplete usage may include supported local estimates, with their provenance preserved. A failed or canceled request with no useful output or billable usage releases its reservation. HTTP status alone does not establish the charge after streaming starts. For asynchronous media, submission is not completion; repeated terminal checks must not charge twice.

## Balance and top-ups

Use the [wallet](https://lazu.ai/console/wallet) to see available payment methods, amounts and credited transactions. Credit is reflected after payment confirmation and processing; if it is missing, retain the order ID and contact support. Top-ups are not refundable. Review the amount before confirming a payment.

## First top-up bonus and referrals

- **First top-up bonus:** an account's first top-up gets 10% extra, up to $10, credited with the payment. Signing up adds no credit. The bonus does not stack with a promotion code.
- **Referral reward:** copy your link from the wallet — `https://lazu.ai/?ref=<your-code>` — or add `?ref=<your-code>` to any lazu.ai link. For 30 days after a friend signs up through it, you get 10% of every top-up they pay, up to $30 per friend; each reward is credited to your wallet 7 days after the payment. Up to 100 friends count per person, and people in a team with you don't count. If a payment is refunded or disputed before its reward arrives, that reward is voided. A month's rewards past $300 are reviewed by us before they are credited.
- **Your code:** you can rename it up to three times. Every name you used keeps working, so links you already shared never break.
- Rewards and bonuses are Lazu credit. They can't be withdrawn or transferred, and they can be voided when abuse is found.
- If you publish your referral link in an article or video, mark the link `rel="sponsored"`, as search engines ask for promoted links.

## Reconcile a request

Inspect `usage.dimensions`, `billing.line_items` and the pricing version in request details. Measurement fields may distinguish provider usage, local estimates and unavailable evidence; older receipts may omit them. Search can have its own billable units: check the configured price and receipt instead of assuming it is free. Report billing discrepancies with the request ID, not your secret key.

```bash
curl --fail-with-body "https://api.lazu.ai/api/usage/requests/$LAZU_REQUEST_ID" \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

[Pricing and lanes](https://lazu.ai/docs/models/pricing) · [Images, video and audio](https://lazu.ai/docs/endpoints/media)

---

# 计费说明

Lazu 使用预付费余额。费用取决于所选模型、通道和实际计费维度。请求前读取当前目录估算费用，请求完成后按回执对账。

## 价格与单位

Token 价格单位为美元／百万 token，费用为数量乘以单价再除以 1,000,000。按次价格为美元／计费调用，按秒价格为美元／计费秒数。音频输入和输出、缓存读取和写入、图片输入和输出可能分别定价。只使用所选模型实际提供的维度；缺失价格不代表免费。

## 预留与最终扣费

预留金额是估算，不是最终用量或费用上限。优先使用上游报告的用量；已有部分输出但用量不完整时，可能使用支持的本地估算，并保留来源。失败或取消且没有有效输出或可计费用量时释放预留。开始流式输出后，不能只凭 HTTP 状态判断费用。异步媒体提交成功不代表任务完成，重复查询终态不应重复扣费。

## 余额与充值

在[钱包](https://lazu.ai/console/wallet)查看实际可用的付款方式、金额和入账记录。支付确认并处理后反映余额；未到账时保留订单 ID 并联系支持。充值后不退款，付款前请确认实际金额。

## 首充赠送与推荐奖励

- \*\*首充赠送：\*\*每个账号第一次充值多送 10%，最多送 $10，和这笔充值一起到账。注册本身不送额度。首充赠送和优惠码不叠加。
- \*\*推荐奖励：\*\*在钱包里复制你的推荐链接 `https://lazu.ai/?ref=<你的名字>`，也可以在任何 lazu.ai 链接后面加 `?ref=<你的名字>`。好友用它注册后 30 天内，每笔实付充值的 10% 归你，每位好友最多 $30；每笔奖励在付款 7 天后到账。每人最多算 100 位好友；和你在同一个团队的人不计入。到账前某笔付款被退款或拒付，那一笔奖励作废。单月奖励超过 $300 的部分，由我们审核后再到账。
- \*\*推荐名字：\*\*最多可以改三次。用过的名字都继续有效，已经发出去的链接不会失效。
- 赠送和奖励都是 Lazu 额度，不能提现或转让，发现滥用时可以作废。
- 如果在文章或视频里放推荐链接，请给链接加 `rel="sponsored"`，这是搜索引擎对推广链接的要求。

## 请求对账

在请求详情中查看 `usage.dimensions`、`billing.line_items` 和价格版本。计量字段可能区分上游用量、本地估算和未知证据；旧回执可能没有这些字段。搜索有独立的计费单位，应查实际价格和回执，不应默认免费。反馈账单问题时提供请求 ID，不要发送密钥。

```bash
curl --fail-with-body "https://api.lazu.ai/api/usage/requests/$LAZU_REQUEST_ID" \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

[价格与线路](https://lazu.ai/docs/zh/models/pricing) · [图片、视频与音频](https://lazu.ai/docs/zh/endpoints/media)

---

# 計費說明

Lazu 使用預付費餘額。費用取決於所選模型、通道與實際計費維度。請求前讀取目前目錄估算費用，完成後按回執對帳。

## 價格與單位

Token 價格單位為美元／百萬 token，費用為數量乘以單價再除以 1,000,000。按次價格為美元／計費呼叫，按秒價格為美元／計費秒數。音訊輸入與輸出、快取讀取與寫入、圖片輸入與輸出可能分別定價。只使用所選模型實際提供的維度；缺少價格不代表免費。

## 預留與最終扣費

預留金額是估算，不是最終用量或費用上限。優先使用上游回報的用量；已有部分輸出但用量不完整時，可能使用支援的本地估算並保留來源。失敗或取消且沒有有效輸出或可計費用量時釋放預留。開始串流輸出後，不能只憑 HTTP 狀態判斷費用。非同步媒體提交成功不代表任務完成，重複查詢終態不應重複扣費。

## 餘額與儲值

在[錢包](https://lazu.ai/console/wallet)查看實際可用付款方式、金額與入帳紀錄。支付確認並處理後反映餘額；未入帳時保留訂單 ID 並聯絡支援。儲值後不退款，付款前請確認實際金額。

## 首次儲值贈送與推薦獎勵

- \*\*首次儲值贈送：\*\*每個帳號第一次儲值多送 10%，最多送 $10，和這筆儲值一起入帳。註冊本身不送額度。首次儲值贈送和優惠碼不疊加。
- \*\*推薦獎勵：\*\*在錢包裡複製你的推薦連結 `https://lazu.ai/?ref=<你的名字>`，也可以在任何 lazu.ai 連結後面加 `?ref=<你的名字>`。好友用它註冊後 30 天內，每筆實付儲值的 10% 歸你，每位好友最多 $30；每筆獎勵在付款 7 天後入帳。每人最多算 100 位好友；和你在同一個團隊的人不計入。入帳前某筆付款被退款或拒付，那一筆獎勵作廢。單月獎勵超過 $300 的部分，由我們審核後再入帳。
- \*\*推薦名字：\*\*最多可以改三次。用過的名字都繼續有效，已經發出去的連結不會失效。
- 贈送和獎勵都是 Lazu 額度，不能提領或轉讓，發現濫用時可以作廢。
- 如果在文章或影片裡放推薦連結，請給連結加 `rel="sponsored"`，這是搜尋引擎對推廣連結的要求。

## 請求對帳

在請求詳情查看 `usage.dimensions`、`billing.line_items` 與價格版本。計量欄位可能區分上游用量、本地估算與未知證據；舊回執可能沒有這些欄位。搜尋有獨立計費單位，應查實際價格與回執，不應預設免費。回報帳單問題時提供請求 ID，不要傳送金鑰。

```bash
curl --fail-with-body "https://api.lazu.ai/api/usage/requests/$LAZU_REQUEST_ID" \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

[價格與線路](https://lazu.ai/docs/zh-TW/models/pricing) · [圖片、影片與音訊](https://lazu.ai/docs/zh-TW/endpoints/media)

---

# 料金体系

Lazu はプリペイド残高を使用します。料金はモデル、レーン、課金項目によって決まります。実行前は最新カタログで見積もり、完了後はリクエスト明細で照合してください。

## 価格と単位

Token 単価は USD／100万 token です。数量に単価を掛けて 1,000,000 で割ります。呼び出し単価は USD／課金対象呼び出し、秒単価は USD／課金対象秒数です。音声の入力と出力、キャッシュの読み取りと書き込み、画像の入力と出力は別単価の場合があります。選んだモデルが公開する項目を確認してください。価格の欠落は無料を意味しません。

## 予約額と最終料金

予約額は見積もりであり、最終使用量や料金上限ではありません。上流の使用量を優先します。部分出力があり使用量が不完全な場合、対応するローカル推定を出所とともに使用することがあります。有効な出力も課金対象使用量もない失敗・キャンセルでは予約額を解放します。ストリーム開始後は HTTP ステータスだけで料金を判断できません。非同期メディアの受付は完了ではなく、終端状態の繰り返し確認で二重請求しません。

## 残高とチャージ

[ウォレット](https://lazu.ai/console/wallet)で実際に利用できる支払方法、金額、入金履歴を確認します。支払確認と処理後に残高へ反映されます。反映されない場合は注文 ID を保存しサポートへ連絡してください。チャージ後の返金はできません。支払確定前に金額を確認してください。

## 初回チャージ特典と紹介特典

- **初回チャージ特典：** 各アカウントの初回チャージは 10% 上乗せ（最大 $10）で、チャージと同時に反映されます。登録だけでは残高は付与されません。プロモーションコードとは併用できません。
- **紹介特典：** ウォレットで紹介リンク `https://lazu.ai/?ref=<あなたの名前>` をコピーするか、lazu.ai のどのリンクにも `?ref=<あなたの名前>` を付けてください。友だちがそのリンクから登録してから 30 日間、支払ったチャージの 10%（1 人あたり最大 $30）があなたに付与され、各特典は支払いの 7 日後にウォレットへ反映されます。対象は 1 人あたり最大 100 人で、同じチームの人は対象外です。反映前に支払いが返金またはチャージバックされた場合、その特典は取り消されます。月間 $300 を超える分は、当社の確認後に反映されます。
- **紹介名：** 最大 3 回まで変更できます。使った名前はすべて引き続き有効で、共有済みのリンクが切れることはありません。
- 特典はすべて Lazu の残高です。出金や譲渡はできず、不正が見つかった場合は取り消されることがあります。
- 記事や動画に紹介リンクを載せる場合は、検索エンジンの求めに従いリンクに `rel="sponsored"` を付けてください。

## リクエストの照合

リクエスト詳細の `usage.dimensions`、`billing.line_items`、価格バージョンを確認します。計測項目は上流値、ローカル推定、不明を区別する場合があり、古い明細には存在しないことがあります。検索には独自の課金単位があるため、無料と仮定せず実際の価格と明細を確認してください。問い合わせにはリクエスト ID を使い、秘密キーは送らないでください。

```bash
curl --fail-with-body "https://api.lazu.ai/api/usage/requests/$LAZU_REQUEST_ID" \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

[価格とレーン](https://lazu.ai/docs/ja/models/pricing) · [画像・動画・音声](https://lazu.ai/docs/ja/endpoints/media)

---

# Chat completions

**POST** `/v1/chat/completions`

Send OpenAI-compatible chat requests through Lazu. Use this page as the working reference: base URL, auth, required body fields, examples, response usage, streaming and tool calling all live here.

## Example request

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## Example response

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## Basic configuration

- **Base URL** — Use `https://api.lazu.ai/v1` with OpenAI SDKs, or call the full
  path `https://api.lazu.ai/v1/chat/completions` directly.
- **Model discovery** — Read `GET /api/models/catalog` at runtime. Filter entries where
  `supported_endpoint_types` contains `chat`.

## Request body

- `model` `string` (required) — 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.
- `messages` `object[]` (required) — Ordered conversation messages. Roles follow the OpenAI shape:
  `system`, `user`, `assistant`, and
  `tool`.

  - `role` `string` — One of system, user, assistant or tool.
  - `content` `string | content_part[]` — Plain text, or an array of content parts for multimodal requests.
  - `tool_call_id` `string` — Required on tool messages so the model can associate the result with the earlier call.
- `stream` `boolean` (optional) — When `true`, Lazu forwards a Server-Sent Events stream and ends
  with `data: [DONE]`.
- `tools` `object[]` (optional) — Function/tool definitions. Check `parameters.tools` in the model
  catalog before sending tools to a model.

  - `type` `"function"` — Only function tools are supported today.
  - `function.name` `string` — Tool name the model will call.
  - `function.parameters` `object` — JSON Schema describing the tool arguments.
- `tool_choice` `string | object` (optional) — OpenAI-compatible tool choice control. Use `auto`,
  `none`, `required`, or a named tool object when the
  selected model supports it.
- `response_format` `object` (optional) — Structured output control. Use `{"type":"json_object"}`
  or a JSON schema object when the model supports strict structured output.
- `temperature` `number` (optional) — Sampling temperature. Most models accept `0` to `2`,
  but provider-specific limits can differ.
- `max_tokens` `integer` (optional) — Maximum generated tokens. The final cap is still bounded by the selected
  model's context and output limits.
- `stream_options` `object` (optional) — Use `{"include_usage":true}` when the upstream supports
  streaming usage trailers.

## Message content

- `role` `string` (required) — Message role. One of: `system`, `user`, `assistant`, `tool`
- `content` `string | content_part[]` (required) — Plain text for text-only turns, or an array of content parts for multimodal
  requests.
- `tool_calls` `object[]` (optional) — Assistant tool calls returned by the model.
- `tool_call_id` `string` (optional) — 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:

**Image input**

```json
{
"model": "gpt-6-luna",
"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](https://lazu.ai/docs/endpoints/files) and use
[Responses](https://lazu.ai/docs/endpoints/responses). Chat completions does not automatically
dereference `file_id`.

## Tools

**Tool definition**

```json
{
"model": "gpt-6-luna",
"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

- `id` `string` — Lazu or provider response ID. Use the response header
  `X-Lazu-Request-Id` for request-level reconciliation.
- `choices` `object[]` — Assistant output choices. Streaming responses send incremental
  `delta` objects.
- `usage.prompt_tokens` `integer` — Prompt input tokens.
- `usage.completion_tokens` `integer` — Generated output tokens.
- `usage.prompt_tokens_details.cached_tokens` `integer` (optional) — Cache read tokens when the upstream reports them.
- `usage.prompt_tokens_details.cache_write_tokens` `integer` (optional) — Cache creation/write tokens when the upstream reports them.
- `usage.prompt_tokens_details.cache_miss_tokens` `integer` (optional) — 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:

**Request detail**

```bash
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](https://lazu.ai/docs/errors) for code meanings and retry behavior.

## See also

- [Model catalog](https://lazu.ai/docs/models/catalog)
- [Responses API](https://lazu.ai/docs/endpoints/responses)
- [Billing and cache fields](https://lazu.ai/docs/billing)
- [Request details](https://lazu.ai/docs/endpoints/usage-requests)

---

# Chat completions

**POST** `/v1/chat/completions`

通过 Lazu 发送 OpenAI 兼容的对话请求。本页直接包含 base URL、鉴权、请求字段、响应 usage、流式输出、工具调用和请求详情查询，不需要跳到单独的 OpenAPI Explorer 页面。

## 请求示例

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## 响应示例

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## 基础配置

- **SDK base\_url** — OpenAI SDK 使用 `https://api.lazu.ai/v1`。
- **模型发现** — 生产代码应先读取 `GET /api/models/catalog`，筛选
  `supported_endpoint_types` 包含 `chat` 的模型。

## 请求 Body

- `model` `string` (必填) — 模型 ID，来自 `GET /api/models/catalog`。后续也可以承载
  `auto` 或 route policy 名称。
- `messages` `object[]` (必填) — 对话消息数组。role 使用 OpenAI 兼容格式：
  `system`、`user`、`assistant`、
  `tool`。
- `stream` `boolean` (可选) — 设置为 `true` 时返回 SSE 流式响应，结尾为
  `data: [DONE]`。
- `tools` `object[]` (可选) — 工具/函数定义。发送前建议检查模型目录里的
  `parameters.tools`。
- `response_format` `object` (可选) — 结构化输出控制，例如 `{"type":"json_object"}`。
- `temperature` `number` (可选) — 采样温度。不同 provider 的有效范围可能不同。
- `max_tokens` `integer` (可选) — 最大输出 token，仍受模型上下文和输出限制约束。

## 消息格式

- `role` `string` (必填) — 消息角色。 取值: `system`, `user`, `assistant`, `tool`
- `content` `string | content_part[]` (必填) — 文本消息可直接传字符串；多模态请求可传 content parts。
- `tool_calls` `object[]` (可选) — assistant 消息里的工具调用。
- `tool_call_id` `string` (可选) — `tool` 消息需要带这个字段，用来对应上一轮 tool call。

## 图片输入

**Vision input**

```json
{
"model": "gpt-6-luna",
"messages": [
  {
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,..."}
      }
    ]
  }
]
}
```

PDF 和大文件应该使用 [Files](https://lazu.ai/docs/zh/endpoints/files) +
[Responses](https://lazu.ai/docs/zh/endpoints/responses)。Chat completions 不会自动读取

`file_id`。

## 响应 usage 和 cache 字段

- `usage.prompt_tokens` `integer` — 输入 token。
- `usage.completion_tokens` `integer` — 输出 token。
- `usage.prompt_tokens_details.cached_tokens` `integer` (可选) — cache read tokens。
- `usage.prompt_tokens_details.cache_write_tokens` `integer` (可选) — provider 上报时返回的 cache write tokens。
- `usage.prompt_tokens_details.cache_miss_tokens` `integer` (可选) — provider 明确上报 cache miss 时返回，例如 DeepSeek 兼容字段。

完整对账信息使用请求详情 API：

**Request detail**

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```

## 相关页面

- [模型目录](https://lazu.ai/docs/zh/models/catalog)
- [Responses API](https://lazu.ai/docs/zh/endpoints/responses)
- [计费规则](https://lazu.ai/docs/zh/billing)
- [请求详情](https://lazu.ai/docs/zh/endpoints/usage-requests)

---

# Chat completions

**POST** `/v1/chat/completions`

透過 Lazu 發送 OpenAI-compatible chat 請求。Base URL、認證、必要 body 欄位、stream、tools、response usage 和排障入口都在這一頁。

## 請求範例

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## 回應範例

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## 基本設定

- **Base URL** — 使用 `https://api.lazu.ai/v1` 搭配 OpenAI SDK，或直接呼叫完整
  path `https://api.lazu.ai/v1/chat/completions`。
- **模型發現** — 執行時讀取 `GET /api/models/catalog`，並篩選
  `supported_endpoint_types` 包含 `chat` 的模型。

## 請求 Body

- `model` `string` (必填) — 模型 ID、route alias 或未來的 route policy 名稱。建議從
  `GET /api/models/catalog` 讀取。
- `messages` `object[]` (必填) — 有序對話訊息。角色遵循 OpenAI shape。

  - `role` `string` — system、user、assistant 或 tool。
  - `content` `string | content_part[]` — 純文字，或多模態 content parts。
  - `tool_call_id` `string` — tool message 用於關聯先前的 tool call。
- `stream` `boolean` (可選) — 為 `true` 時返回 Server-Sent Events stream，最後以
  `data: [DONE]` 結束。
- `tools` `object[]` (可選) — Function/tool 定義。送出前先檢查模型 catalog 中的&#x20;
  `parameters.tools`。

  - `type` `"function"` — 目前支援 function tools。
  - `function.name` `string` — 模型可呼叫的工具名稱。
  - `function.parameters` `object` — 描述參數的 JSON Schema。
- `tool_choice` `string | object` (可選) — OpenAI-compatible tool choice 控制，例如 `auto`、
  `none`
  或指定工具物件。
- `response_format` `object` (可選) — Structured output 控制，例如 `{"type":"json_object"}`。
- `temperature` `number` (可選) — 取樣溫度，多數模型接受 `0` 到 `2`。
- `max_tokens` `integer` (可選) — 產生 token 上限，仍受模型 context 和 output limit 限制。

## Vision input

圖片輸入使用 OpenAI-compatible content parts。可以傳 HTTPS 圖片 URL 或 data URL：

**Image input**

```json
{
"model": "gpt-6-luna",
"messages": [
  {
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,..."}
      }
    ]
  }
]
}
```

PDF 和大型文件請透過 [Files](https://lazu.ai/docs/zh-TW/endpoints/files) 上傳，並使用
[Responses](https://lazu.ai/docs/zh-TW/endpoints/responses)。Chat completions 不會自動解引用

`file_id`。

## Response

- `id` `string` — Lazu 或 provider response ID。
- `choices` `object[]` — Assistant output choices。Streaming response 會送出增量 `delta`。
- `usage.prompt_tokens` `integer` — 輸入 token 數。
- `usage.completion_tokens` `integer` — 輸出 token 數。
- `usage.prompt_tokens_details.cached_tokens` `integer` (可選) — 上游回報時的 cache read token。

完整對帳請使用 [請求詳情](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)。

## 相關頁面

- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)
- [Responses API](https://lazu.ai/docs/zh-TW/endpoints/responses)
- [錯誤碼](https://lazu.ai/docs/zh-TW/errors)

---

# Chat completions

**POST** `/v1/chat/completions`

Lazu 経由で OpenAI-compatible chat request を送ります。Base URL、認証、必須 body fields、stream、tools、response usage、troubleshooting をこのページで確認できます。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## レスポンス例

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## 基本設定

- **Base URL** — OpenAI SDK では `https://api.lazu.ai/v1`&#x20;
  を使います。直接呼ぶ場合は
  `https://api.lazu.ai/v1/chat/completions` です。
- **モデル検出** — 実行時に `GET /api/models/catalog` を読み、
  `supported_endpoint_types` に `chat`&#x20;
  を含むモデルを選びます。

## Request body

- `model` `string` (必須) — model ID、route alias、または route policy name。明示的な model は
  `GET /api/models/catalog` から選びます。
- `messages` `object[]` (必須) — OpenAI shape の会話メッセージ配列です。

  - `role` `string` — system、user、assistant、tool のいずれか。
  - `content` `string | content_part[]` — plain text または multimodal content parts。
  - `tool_call_id` `string` — tool message を先行 tool call と関連付けます。
- `stream` `boolean` (任意) — `true` の場合、Server-Sent Events stream を返し、最後に
  `data: [DONE]` を送ります。
- `tools` `object[]` (任意) — tool 定義です。送信前に catalog の `parameters.tools`&#x20;
  を確認してください。

  - `type` `"function"` — 現在は function tools を扱います。
  - `function.name` `string` — モデルが呼べる tool name。
  - `function.parameters` `object` — tool arguments の JSON Schema。
- `tool_choice` `string | object` (任意) — `auto`、`none`、指定 tool object など。
- `response_format` `object` (任意) — structured output control。例：`{"type":"json_object"}`。
- `temperature` `number` (任意) — sampling temperature。多くの model は `0` から `2`&#x20;
  を受け付けます。
- `max_tokens` `integer` (任意) — 生成 token の上限です。

## Vision input

画像入力は OpenAI-compatible content parts を使います。HTTPS image URL または data URL
を送れます。

**Image input**

```json
{
"model": "gpt-6-luna",
"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](https://lazu.ai/docs/ja/endpoints/files) で upload し、
[Responses](https://lazu.ai/docs/ja/endpoints/responses) で参照してください。Chat completions は

`file_id` を自動 dereference しません。

## Response

- `id` `string` — Lazu または provider response ID。
- `choices` `object[]` — assistant output choices。Streaming では incremental `delta`&#x20;
  です。
- `usage.prompt_tokens` `integer` — input token count。
- `usage.completion_tokens` `integer` — generated output token count。
- `usage.prompt_tokens_details.cached_tokens` `integer` (任意) — provider が報告した cache read tokens。

完全な照合には [リクエスト詳細](https://lazu.ai/docs/ja/endpoints/usage-requests) を使ってください。

---

# Decisions

`POST /v1/decisions` evaluates explicit questions over text, JSON or embedded images. Discover available models and their `decision_capabilities` through the [model catalog](https://lazu.ai/docs/models/catalog). This endpoint returns one JSON response and does not support streaming.

```bash
curl https://api.lazu.ai/v1/decisions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13",
    "state": {"ticket": "The checkout service is down."},
    "questions": {
      "urgent": {"type": "noul", "instructions": "Does this need immediate attention?"},
      "owner": {"type": "choice", "instructions": "Choose the responsible team.", "criteria": {"engineering": "Service reliability", "billing": "Payment reconciliation"}},
      "severity": {"type": "score", "instructions": "Rate operational impact.", "criteria": ["No impact", "Degraded service", "Service unavailable"]}
    }
  }'
```

`state` is the material to judge. `questions` defines what to judge: `noul` returns a probability from 0 to 1; `choice` returns an option ID and probabilities; `score` returns a score against your ordered rubric. Business JSON inside instructions and criteria is preserved. Supply 1–64 questions with unique ASCII IDs using letters, numbers, `_`, `.` or `-`. Choice allows 2–255 options; score allows 2–10 levels. Answers include confidence and preserve additional provider fields.

## Images

`clef` and `clef-flash` accept `images` containing PNG, JPEG or WebP data URLs, either as strings or `{ "url": "data:image/png;base64,..." }`. State must still be supplied; it may be empty when images are valid. Remote URLs, uploaded file IDs, audio and video are unsupported. Jev accepts text and JSON.

Each image may contain at most 4 MiB decoded data and 16 million pixels. At most 4 images and 8 MiB total decoded data are allowed; the entire encoded upstream request may not exceed 13 MiB. Clef currently applies a **conservative 2000 UTF-8 byte limit to state**, in addition to token estimates, to prevent silent upstream truncation. Check `max_state_bytes` and token limits in the catalog.

## Optional question generation

Question generation is disabled by default. When your operator enables it, opt in per request or in your API Key settings:

```json
{
  "model": "jev-1.13",
  "state": "Checkout is down. Customers cannot pay.",
  "question_generation": {"enabled": true, "model": "gpt-6-luna"}
}
```

You may omit the generation model to use the Key's model or the platform default. Specifying a model alone does not enable generation. Explicit `questions` always take precedence. Automatically inferred questions can change with the material; use explicit questions when stable business rules are required.

Generation uses an independently authorized Responses call. Your Key and temporary credential must allow both models. The gateway checks pricing, Key, project, member and account budgets before generation, with a separate 2 requests/minute generation limit per Key and account. There is no questions cache. Generation may take up to 15 seconds; native evaluation has a total 10-second budget and at most two provider attempts; both stages share a 25-second budget.

## Usage and failures

Native `usage` contains only the decision model's input and output tokens. `question_generation` includes its own model, request ID, prompt version and usage; `questions` contains the generated questions. Each stage has a separate usage record and charge. Upstream output tokens remain visible even when configured output pricing is zero.

Unusable generated questions are refunded to the original wallet and Key with an auditable refund record. If valid generation is followed by a native failure, the generation charge is retained and `error.details.questions` contains reusable questions. Retry those explicitly to avoid another generation charge. [Request details](https://lazu.ai/docs/endpoints/usage-requests) and Console logs link the parent and generation requests.

When the decision API is disabled it returns 404 and decision models are hidden from the catalog. Use `error.code` and `Retry-After` for machine handling; see [errors](https://lazu.ai/docs/errors).

## Operator configuration

Select a decision dialect on each source: TypeSafe, OpenRouter, Cloudflare AI Gateway, or Cloudflare Workers AI. Cloudflare sources also require the account ID. Register Jev, Clef and Clef Flash as decision models, configure input pricing and set output pricing to zero where applicable. Set channel and shared account RPS/in-flight caps; a shared group uses the smallest positive configured member limit. **Multiple API replicas require Redis** for shared admission. With Redis unavailable, the gateway retains local in-flight protection and emits an operational error; shared multi-replica capacity is temporarily unavailable.

The generator model must declare structured-output support in the model catalog, plus vision support for image requests. Native and generation permissions are checked before the paid generation call.

Enable `/v1/decisions` and automatic generation separately in upstream settings. Both switches default to off. Use the source health test with endpoint type `decisions` before exposing a model.

---

# 判别模型

通过 `POST /v1/decisions` 对文本、JSON 和内嵌图片进行概率、选择和评分判断。高级调用者传入明确的 questions；可选自动生成默认关闭。原生判别和问题生成分别鉴权、计费、记录请求 ID。

```json
{
  "model": "jev-1.13",
  "state": {"ticket": "服务中断，需要立即处理。"},
  "questions": {"urgent": {"type": "noul", "instructions": "是否需要立即处理？"}}
}
```

完整参数、图片限制、自动生成、独立计费及错误重试规则见 [英文协议文档](https://lazu.ai/docs/endpoints/decisions)。Clef 当前对 state 使用保守的 2000 UTF-8 字节安全限制；图片只接受内嵌 PNG/JPEG/WebP。接口不支持流式。

---

# 判別模型

透過 `POST /v1/decisions` 對文字、JSON 和內嵌圖片進行機率、選擇和評分判斷。可選的問題自動產生預設關閉；原生判別與問題產生分別驗證、計費及記錄請求 ID。

```json
{
  "model": "jev-1.13",
  "state": {"ticket": "服务中断，需要立即处理。"},
  "questions": {"urgent": {"type": "noul", "instructions": "是否需要立即处理？"}}
}
```

完整參數、圖片限制、自動產生、獨立計費與錯誤重試請參閱 [英文協定文件](https://lazu.ai/docs/endpoints/decisions)。Clef 目前限制 state 為保守的 2000 UTF-8 位元組；圖片僅接受內嵌 PNG/JPEG/WebP，不支援串流。

---

# 判別モデル

`POST /v1/decisions` でテキスト、JSON、埋め込み画像を確率・選択・スコアとして評価します。質問の自動生成は既定で無効です。生成と判別はそれぞれ認証・課金され、個別のリクエスト ID を持ちます。

```json
{
  "model": "jev-1.13",
  "state": {"ticket": "服务中断，需要立即处理。"},
  "questions": {"urgent": {"type": "noul", "instructions": "是否需要立即处理？"}}
}
```

パラメータ、画像制限、自動生成、課金と再試行の詳細は [英語の仕様](https://lazu.ai/docs/endpoints/decisions) を参照してください。Clef の state は保守的に 2000 UTF-8 バイトに制限されます。画像は埋め込み PNG/JPEG/WebP のみ、ストリーミングは非対応です。

---

# Embeddings

**POST** `/v1/embeddings`

Create vector embeddings with OpenAI-compatible clients. Use the model catalog to discover which models support embeddings and whether they accept custom dimensions.

## Example request

```bash
curl https://api.lazu.ai/v1/embeddings \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["doc one", "doc two"]
  }'
```

## Example response

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.013] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}
```

## Request body

- `model` `string` (required) — Embedding model ID from `/api/models/catalog`.
- `input` `string | string[]` (required) — Text input or ordered batch of text inputs. The response preserves order.
- `dimensions` `integer` (optional) — Optional vector dimension for models that support truncation.
- `encoding_format` `string` (optional) — Output encoding format when supported by the upstream provider. One of: `float`, `base64`

## Response

- `object` `string` — Usually `list`.
- `data` `object[]` — One embedding item per input.
- `data[].embedding` `number[] | string` — Vector values or base64-encoded vector depending on
  `encoding_format`.
- `usage.prompt_tokens` `integer` — 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](https://lazu.ai/docs/models/catalog)
- [Pricing & lanes](https://lazu.ai/docs/models/pricing)

---

# Embeddings

**POST** `/v1/embeddings`

使用 OpenAI-compatible 客户端创建向量 embedding。通过模型目录确认哪些模型支持 embeddings，以及是否支持自定义 dimensions。

## 请求示例

```bash
curl https://api.lazu.ai/v1/embeddings \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["doc one", "doc two"]
  }'
```

## 响应示例

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.013] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}
```

## 请求 Body

- `model` `string` (必填) — 来自 `/api/models/catalog` 的 embedding 模型 ID。
- `input` `string | string[]` (必填) — 文本输入，或有序文本批量输入。响应会保持输入顺序。
- `dimensions` `integer` (可选) — 支持截断的模型可使用可选向量维度。
- `encoding_format` `string` (可选) — 上游支持时可选择输出编码格式。 取值: `float`, `base64`

## 响应

- `object` `string` — 通常为 `list`。
- `data` `object[]` — 每个 input 对应一个 embedding item。
- `data[].embedding` `number[] | string` — 向量数值，或取决于 `encoding_format` 的 base64 编码向量。
- `usage.prompt_tokens` `integer` — 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       |

## 相关页面

- [模型目录](https://lazu.ai/docs/zh/models/catalog)
- [定价与渠道](https://lazu.ai/docs/zh/models/pricing)

---

# Embeddings

**POST** `/v1/embeddings`

使用 OpenAI-compatible 用戶端建立向量 embedding。透過模型目錄確認哪些模型支援 embeddings，以及是否支援自訂 dimensions。

## 請求範例

```bash
curl https://api.lazu.ai/v1/embeddings \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["doc one", "doc two"]
  }'
```

## 回應範例

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.013] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}
```

## 請求 Body

- `model` `string` (必填) — 來自 `/api/models/catalog` 的 embedding 模型 ID。
- `input` `string | string[]` (必填) — 文字輸入，或有序文字批次輸入。響應會保持輸入順序。
- `dimensions` `integer` (可選) — 支援截斷的模型可使用可選向量維度。
- `encoding_format` `string` (可選) — 上游支援時可選擇輸出編碼格式。 取值: `float`, `base64`

## 響應

- `object` `string` — 通常為 `list`。
- `data` `object[]` — 每個 input 對應一個 embedding item。
- `data[].embedding` `number[] | string` — 向量數值，或取決於 `encoding_format` 的 base64 編碼向量。
- `usage.prompt_tokens` `integer` — embedding 使用的輸入 token 數。

## 批次建議

小批次可以直接傳陣列。大規模資料任務建議在用戶端分塊，確保每個請求都不超過
provider 的 body size 和 token 限制。

## 相關頁面

- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)
- [定價與通道](https://lazu.ai/docs/zh-TW/models/pricing)

---

# Embeddings

**POST** `/v1/embeddings`

OpenAI-compatible clients で vector embeddings を作成します。モデルカタログで embeddings support と custom dimensions support を確認してください。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/embeddings \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["doc one", "doc two"]
  }'
```

## レスポンス例

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.013] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}
```

## Request body

- `model` `string` (必須) — `/api/models/catalog` の embedding model ID。
- `input` `string | string[]` (必須) — text input または ordered batch。response は入力順を保持します。
- `dimensions` `integer` (任意) — truncation を support する model の optional vector dimension。
- `encoding_format` `string` (任意) — upstream が support する場合の output encoding format。 指定可能な値: `float`, `base64`

## Response

- `object` `string` — 通常は `list`。
- `data` `object[]` — input ごとの embedding item。
- `data[].embedding` `number[] | string` — vector values または `encoding_format` に応じた base64 vector。
- `usage.prompt_tokens` `integer` — embedding に使われた input tokens。

## Batch guidance

小さな batch は array で渡せます。大規模 jobs では client-side chunking を行い、
provider の body-size と token limits を超えないようにしてください。

---

# Files API

**POST** `/v1/files`

Upload documents and images once, then reference them by file\_id from the Responses API. The file API is OpenAI-compatible where possible, with explicit Lazu retention and purpose rules.

## Example request

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## Example response

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## 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

- `purpose` `string` (required) — Declares how the file can be used. One of: `user_data`, `vision`
- `file` `multipart file` (required) — Uploaded file bytes.

## Supported purposes

- **user\_data** — Up to 512 MB. Use for PDFs, text and structured data passed through
  Responses as `input_file`.
- **vision** — 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

- `id` `string` — File ID, for example `file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`.
- `object` `string` — Always `file`.
- `bytes` `integer` — Uploaded byte size.
- `filename` `string` — Original filename.
- `purpose` `string` — Stored purpose.
- `status` `string` — 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](https://lazu.ai/docs/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_required_parameter` `400` — Missing `purpose` or file bytes.
- `purpose_not_supported` `400` — Unsupported purpose such as `batch` or `fine-tune`.
- `file_too_large` `413` — Single file or total dereferenced files exceed limits.
- `file_not_found` `404` — File does not exist or is not owned by the current API key.

---

# Files API

**POST** `/v1/files`

文档和图片可以先上传一次，再在 Responses API 中通过 file\_id 引用。Files API 尽量保持 OpenAI-compatible，同时明确 Lazu 的保留期和 purpose 规则。

## 请求示例

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## 响应示例

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## 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` `string` (必填) — 声明文件用途。 取值: `user_data`, `vision`
- `file` `multipart file` (必填) — 上传的文件字节。

## 支持的 purpose

- **user\_data** — 最大 512 MB。用于 PDF、文本和结构化数据，通过 Responses 的
  `input_file` 传入。
- **vision** — 最大 20 MB。允许 `image/png`、`image/jpeg`、
  `image/gif`、`image/webp`。

OpenAI 的 `batch`、`fine-tune` 和

`assistants` purpose 暂不支持。无论 purpose
如何，都会拒绝可执行文件扩展名。

## 上传响应

- `id` `string` — File ID，例如 `file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`。
- `object` `string` — 始终为 `file`。
- `bytes` `integer` — 上传字节数。
- `filename` `string` — 原始文件名。
- `purpose` `string` — 存储的 purpose。
- `status` `string` — 通常为 `processed`。

成功上传时 Lazu 返回 `201 Created`。如果客户端只接受 200，需要把
201 也视作成功。

## 在 Responses 中引用

Lazu 只会在 [Responses](https://lazu.ai/docs/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  |

## 错误

- `missing_required_parameter` `400` — 缺少 `purpose` 或文件字节。
- `purpose_not_supported` `400` — 不支持的 purpose，例如 `batch` 或 `fine-tune`。
- `file_too_large` `413` — 单文件或解引用总大小超过限制。
- `file_not_found` `404` — 文件不存在，或不属于当前 API Key。

---

# Files API

**POST** `/v1/files`

文件和圖片可以先上傳一次，再在 Responses API 中透過 file\_id 引用。Files API 盡量保持 OpenAI-compatible，同時明確 Lazu 的保留期和 purpose 規則。

## 請求範例

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## 回應範例

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## 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` `string` (必填) — 宣告檔案用途。 取值: `user_data`, `vision`
- `file` `multipart file` (必填) — 上傳的檔案位元組。

## 支援的 purpose

- **user\_data** — 最大 512 MB。用於 PDF、文字和結構化資料，透過 Responses 的
  `input_file` 傳入。
- **vision** — 最大 20 MB。允許 `image/png`、`image/jpeg`、
  `image/gif`、`image/webp`。

OpenAI 的 `batch`、`fine-tune` 和

`assistants` purpose 暫不支援。無論 purpose
如何，都會拒絕可執行檔副檔名。

## 上傳響應

- `id` `string` — File ID，例如 `file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`。
- `object` `string` — 始終為 `file`。
- `bytes` `integer` — 上傳位元組數。
- `filename` `string` — 原始檔名。
- `purpose` `string` — 儲存的 purpose。
- `status` `string` — 通常為 `processed`。

成功上傳時 Lazu 返回 `201 Created`。如果用戶端只接受 200，需要把
201 也視作成功。

## 在 Responses 中引用

Lazu 只會在 [Responses](https://lazu.ai/docs/zh-TW/endpoints/responses) 中解引用 `file_id`。
Chat completions 不會自動拉取檔案內容。

## 限制

| 限制                        | 值      |
| ------------------------- | ------ |
| 單個 `purpose=user_data` 檔案 | 512 MB |
| 單個 `purpose=vision` 檔案    | 20 MB  |
| 單次 Responses 呼叫解引用總大小     | 64 MB  |

---

# Files API

**POST** `/v1/files`

documents と images を一度 upload し、Responses API から file\_id で参照できます。OpenAI-compatible に寄せつつ、Lazu の retention と purpose rules を明示します。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## レスポンス例

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## 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

- `purpose` `string` (必須) — file の用途。 指定可能な値: `user_data`, `vision`
- `file` `multipart file` (必須) — upload する file bytes。

## Supported purposes

- **user\_data** — 最大 512 MB。PDF、text、structured data を Responses の
  `input_file` として渡す用途。
- **vision** — 最大 20 MB。`image/png`、`image/jpeg`、
  `image/gif`、`image/webp` を許可。

OpenAI の `batch`、`fine-tune`、`assistants`
purposes はまだ support していません。実行ファイル拡張子は purpose に関係なく拒否します。

## Upload response

- `id` `string` — File ID。例：`file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`。
- `object` `string` — 常に `file`。
- `bytes` `integer` — upload byte size。
- `filename` `string` — original filename。
- `purpose` `string` — stored purpose。
- `status` `string` — 通常 `processed`。

成功時は `201 Created` を返します。client SDK が 200 のみを想定している場合は
201 を success として扱ってください。

## Responses から参照する

Lazu は [Responses](https://lazu.ai/docs/ja/endpoints/responses) でのみ `file_id`
を dereference します。Chat completions は file content を自動取得しません。

---

# Images, video and audio

For images and video, query the [model catalog](https://lazu.ai/docs/models/catalog) with your key and inspect the exact endpoint, parameters and example. For audio, use the model-selection guidance below. Availability and options depend on the model and deployment; one model need not support all media types. Examples require Python 3 and the `requests` package (`python -m pip install requests`). Set `LAZU_API_KEY` and the model variables below.

## Generate an image

Set `LAZU_IMAGE_MODEL` to a model supporting `/v1/images/generations`. The response can include `data[].url` or `data[].b64_json`; handle the actual returned form. Size, quality and output format depend on the model. Do not assume generated URLs are permanent.

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
response = requests.post(origin + "/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
    json={"model": os.environ["LAZU_IMAGE_MODEL"], "prompt": "A blue ceramic cup"},
    timeout=180)
response.raise_for_status()
print(response.json()["data"])
```

## Submit and poll a video

Set `LAZU_VIDEO_MODEL` to a model supporting `/v1/videos`. A successful submission returns HTTP 202 and a job ID. Poll the same job with the same key: `pending` and `running` are not final; `succeeded` provides artifact information, and `failed` includes an error. A local wait timeout does not cancel or fail the job. Save the ID and resume polling; do not submit another paid job just because the wait ended.

```python
import os
import time
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/videos", headers=headers,
    json={"model": os.environ["LAZU_VIDEO_MODEL"], "prompt": "Ocean waves at sunrise"},
    timeout=180)
response.raise_for_status()
job_id = response.json()["id"]
print("Save job ID:", job_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(origin + "/v1/videos/" + job_id,
                            headers=headers, timeout=30)
    if response.status_code in (429, 503):
        retry_after = response.headers.get("Retry-After", "5")
        delay = float(retry_after) if retry_after.isdecimal() else 5
        if delay >= deadline - time.monotonic():
            print("Still waiting; resume GET for job:", job_id)
            break
        time.sleep(max(1, delay))
        continue
    response.raise_for_status()
    job = response.json()
    if job["status"] == "succeeded":
        print(job.get("artifact", {}))
        break
    if job["status"] == "failed":
        raise RuntimeError(job.get("error", {"message": "Video failed"}))
    time.sleep(5)
else:
    print("Still waiting; resume GET for job:", job_id)
# A local timeout does not cancel the remote job. Keep job_id for later GETs.
```

## Generate speech or transcribe audio

Set `LAZU_AUDIO_MODEL` to a speech model and `LAZU_VOICE` to a supported voice. `/v1/audio/speech` returns binary audio, not JSON. For transcription, choose a compatible model and upload a local audio file to `/v1/audio/transcriptions` as multipart data. These are separate model capabilities.

The catalog currently has no speech/transcription endpoint types. Audio modality alone cannot identify either capability. Obtain the exact model ID, endpoint and supported voice from your deployment operator or Lazu support, and confirm that the model is accessible to your API key. Do not select these models by audio modality alone. Set `LAZU_TRANSCRIPTION_MODEL` to the confirmed transcription model and `LAZU_AUDIO_FILE` to your local audio path.

```python
import os
from pathlib import Path
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/audio/speech", headers=headers,
    json={"model": os.environ["LAZU_AUDIO_MODEL"], "input": "Hello from Lazu",
          "voice": os.environ["LAZU_VOICE"], "response_format": "mp3"}, timeout=180)
response.raise_for_status()
Path("speech.mp3").write_bytes(response.content)
```

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
with open(os.environ["LAZU_AUDIO_FILE"], "rb") as audio:
    response = requests.post(origin + "/v1/audio/transcriptions",
        headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
        data={"model": os.environ["LAZU_TRANSCRIPTION_MODEL"]},
        files={"file": audio}, timeout=180)
response.raise_for_status()
print(response.json())
```

## Errors and results

On failure, preserve the request or job ID and inspect the error code. If submission times out before a job ID arrives, check the video job list (`GET /v1/videos`) or contact support before resubmitting. For a succeeded job, use `artifact.url` when available; if only `artifact.file_id` is returned, retrieve it through the [Files API](https://lazu.ai/docs/endpoints/files). Reconcile charges through [Billing](https://lazu.ai/docs/billing).

[API Explorer](https://lazu.ai/docs/api-reference)

---

# 图片、视频与音频

图片和视频先用密钥查询[模型目录](https://lazu.ai/docs/zh/models/catalog)，检查具体端点、参数与示例；音频模型按下方说明选择。可用性和选项取决于模型及部署，一个模型不一定支持所有媒体类型。示例需要 Python 3 和 `requests`（`python -m pip install requests`）；请设置 `LAZU_API_KEY` 及下文模型变量。

## 生成图片

将 `LAZU_IMAGE_MODEL` 设为支持 `/v1/images/generations` 的模型。响应可能包含 `data[].url` 或 `data[].b64_json`，按实际形式读取。尺寸、质量和格式由模型决定，不要假设生成链接永久有效。

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
response = requests.post(origin + "/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
    json={"model": os.environ["LAZU_IMAGE_MODEL"], "prompt": "A blue ceramic cup"},
    timeout=180)
response.raise_for_status()
print(response.json()["data"])
```

## 提交并轮询视频

将 `LAZU_VIDEO_MODEL` 设为支持 `/v1/videos` 的模型。提交成功返回 HTTP 202 和任务 ID；用同一密钥查询同一任务。`pending`、`running` 均未完成；`succeeded` 提供产物信息，`failed` 提供错误。本地等待超时不会取消任务或令任务失败，应保存 ID 并继续查询，不要因等待结束重复创建付费任务。

```python
import os
import time
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/videos", headers=headers,
    json={"model": os.environ["LAZU_VIDEO_MODEL"], "prompt": "Ocean waves at sunrise"},
    timeout=180)
response.raise_for_status()
job_id = response.json()["id"]
print("Save job ID:", job_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(origin + "/v1/videos/" + job_id,
                            headers=headers, timeout=30)
    if response.status_code in (429, 503):
        retry_after = response.headers.get("Retry-After", "5")
        delay = float(retry_after) if retry_after.isdecimal() else 5
        if delay >= deadline - time.monotonic():
            print("Still waiting; resume GET for job:", job_id)
            break
        time.sleep(max(1, delay))
        continue
    response.raise_for_status()
    job = response.json()
    if job["status"] == "succeeded":
        print(job.get("artifact", {}))
        break
    if job["status"] == "failed":
        raise RuntimeError(job.get("error", {"message": "Video failed"}))
    time.sleep(5)
else:
    print("Still waiting; resume GET for job:", job_id)
# A local timeout does not cancel the remote job. Keep job_id for later GETs.
```

## 语音生成与转写

将 `LAZU_AUDIO_MODEL` 设为语音生成模型，`LAZU_VOICE` 设为其支持的音色。`/v1/audio/speech` 返回二进制音频而非 JSON。转写需另选兼容模型，通过 multipart 向 `/v1/audio/transcriptions` 上传本地音频；两者是独立能力。

目录目前没有语音生成或转写端点类型，仅凭音频模态无法判断这两种能力。请向部署管理员或 Lazu 支持获取已确认的模型 ID、端点与支持的音色，并确认该模型对当前 Key 可用，不要只按音频模态选模型。将 `LAZU_TRANSCRIPTION_MODEL` 设置为已确认的转写模型，`LAZU_AUDIO_FILE` 设置为本地音频路径。

```python
import os
from pathlib import Path
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/audio/speech", headers=headers,
    json={"model": os.environ["LAZU_AUDIO_MODEL"], "input": "Hello from Lazu",
          "voice": os.environ["LAZU_VOICE"], "response_format": "mp3"}, timeout=180)
response.raise_for_status()
Path("speech.mp3").write_bytes(response.content)
```

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
with open(os.environ["LAZU_AUDIO_FILE"], "rb") as audio:
    response = requests.post(origin + "/v1/audio/transcriptions",
        headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
        data={"model": os.environ["LAZU_TRANSCRIPTION_MODEL"]},
        files={"file": audio}, timeout=180)
response.raise_for_status()
print(response.json())
```

## 错误与结果

失败时保存请求或任务 ID 并查看错误码。若提交超时且未拿到任务 ID，先查询视频任务列表（`GET /v1/videos`）或联系支持，再决定是否重提。成功任务优先使用 `artifact.url`；如只返回 `artifact.file_id`，通过 [Files API](https://lazu.ai/docs/zh/endpoints/files)获取。费用按[计费说明](https://lazu.ai/docs/zh/billing)对账。

[API Explorer](https://lazu.ai/docs/zh/api-reference)

---

# 圖片、影片與音訊

圖片和影片先用金鑰查詢[模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)，檢查具體端點、參數與示例；音訊模型依下方說明選擇。可用性與選項取決於模型及部署，一個模型不一定支援所有媒體類型。示例需要 Python 3 與 `requests`（`python -m pip install requests`）；請設定 `LAZU_API_KEY` 及下文模型變數。

## 生成圖片

將 `LAZU_IMAGE_MODEL` 設為支援 `/v1/images/generations` 的模型。回應可能包含 `data[].url` 或 `data[].b64_json`，依實際形式讀取。尺寸、品質與格式依模型而定，不要假設生成連結永久有效。

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
response = requests.post(origin + "/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
    json={"model": os.environ["LAZU_IMAGE_MODEL"], "prompt": "A blue ceramic cup"},
    timeout=180)
response.raise_for_status()
print(response.json()["data"])
```

## 提交並輪詢影片

將 `LAZU_VIDEO_MODEL` 設為支援 `/v1/videos` 的模型。提交成功回傳 HTTP 202 與任務 ID；用同一金鑰查詢同一任務。`pending`、`running` 均未完成；`succeeded` 提供產物資訊，`failed` 提供錯誤。本地等待逾時不會取消任務或令任務失敗，應保存 ID 並繼續查詢，不要因等待結束重複建立付費任務。

```python
import os
import time
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/videos", headers=headers,
    json={"model": os.environ["LAZU_VIDEO_MODEL"], "prompt": "Ocean waves at sunrise"},
    timeout=180)
response.raise_for_status()
job_id = response.json()["id"]
print("Save job ID:", job_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(origin + "/v1/videos/" + job_id,
                            headers=headers, timeout=30)
    if response.status_code in (429, 503):
        retry_after = response.headers.get("Retry-After", "5")
        delay = float(retry_after) if retry_after.isdecimal() else 5
        if delay >= deadline - time.monotonic():
            print("Still waiting; resume GET for job:", job_id)
            break
        time.sleep(max(1, delay))
        continue
    response.raise_for_status()
    job = response.json()
    if job["status"] == "succeeded":
        print(job.get("artifact", {}))
        break
    if job["status"] == "failed":
        raise RuntimeError(job.get("error", {"message": "Video failed"}))
    time.sleep(5)
else:
    print("Still waiting; resume GET for job:", job_id)
# A local timeout does not cancel the remote job. Keep job_id for later GETs.
```

## 語音生成與轉寫

將 `LAZU_AUDIO_MODEL` 設為語音生成模型，`LAZU_VOICE` 設為其支援的音色。`/v1/audio/speech` 回傳二進位音訊而非 JSON。轉寫需另選相容模型，透過 multipart 向 `/v1/audio/transcriptions` 上傳本地音訊；兩者是獨立能力。

目錄目前沒有語音生成或轉寫端點類型，僅憑音訊模態無法判斷這兩種能力。請向部署管理員或 Lazu 支援取得已確認的模型 ID、端點與支援的音色，並確認該模型對目前 Key 可用，不要只按音訊模態選模型。將 `LAZU_TRANSCRIPTION_MODEL` 設為已確認的轉寫模型，`LAZU_AUDIO_FILE` 設為本地音訊路徑。

```python
import os
from pathlib import Path
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/audio/speech", headers=headers,
    json={"model": os.environ["LAZU_AUDIO_MODEL"], "input": "Hello from Lazu",
          "voice": os.environ["LAZU_VOICE"], "response_format": "mp3"}, timeout=180)
response.raise_for_status()
Path("speech.mp3").write_bytes(response.content)
```

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
with open(os.environ["LAZU_AUDIO_FILE"], "rb") as audio:
    response = requests.post(origin + "/v1/audio/transcriptions",
        headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
        data={"model": os.environ["LAZU_TRANSCRIPTION_MODEL"]},
        files={"file": audio}, timeout=180)
response.raise_for_status()
print(response.json())
```

## 錯誤與結果

失敗時保存請求或任務 ID 並查看錯誤碼。若提交逾時且未取得任務 ID，先查詢影片任務清單（`GET /v1/videos`）或聯絡支援，再決定是否重提。成功任務優先使用 `artifact.url`；若只有 `artifact.file_id`，透過 [Files API](https://lazu.ai/docs/zh-TW/endpoints/files)取得。費用按[計費說明](https://lazu.ai/docs/zh-TW/billing)對帳。

[API Explorer](https://lazu.ai/docs/zh-TW/api-reference)

---

# 画像・動画・音声

画像と動画はキーで[モデルカタログ](https://lazu.ai/docs/ja/models/catalog)を取得し、対象エンドポイント、パラメータと例を確認します。音声モデルは下記の手順で選択してください。利用可否はモデルとデプロイに依存し、一つのモデルが全メディアに対応するとは限りません。例には Python 3 と `requests`（`python -m pip install requests`）が必要です。`LAZU_API_KEY` と下記モデル変数を設定してください。

## 画像を生成する

`LAZU_IMAGE_MODEL` に `/v1/images/generations` 対応モデルを設定します。返り値は `data[].url` または `data[].b64_json` の場合があるため実際の形式を処理してください。サイズ、品質、形式はモデルに依存します。生成 URL が恒久的とは限りません。

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
response = requests.post(origin + "/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
    json={"model": os.environ["LAZU_IMAGE_MODEL"], "prompt": "A blue ceramic cup"},
    timeout=180)
response.raise_for_status()
print(response.json()["data"])
```

## 動画を送信してポーリングする

`LAZU_VIDEO_MODEL` に `/v1/videos` 対応モデルを設定します。受付成功時は HTTP 202 とジョブ ID が返ります。同じキーで同じジョブを取得してください。`pending` と `running` は未完了、`succeeded` は成果物情報、`failed` はエラーを示します。ローカル待機のタイムアウトはジョブのキャンセルや失敗ではありません。ID を保存して取得を再開し、待機終了だけを理由に有料ジョブを再作成しないでください。

```python
import os
import time
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/videos", headers=headers,
    json={"model": os.environ["LAZU_VIDEO_MODEL"], "prompt": "Ocean waves at sunrise"},
    timeout=180)
response.raise_for_status()
job_id = response.json()["id"]
print("Save job ID:", job_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(origin + "/v1/videos/" + job_id,
                            headers=headers, timeout=30)
    if response.status_code in (429, 503):
        retry_after = response.headers.get("Retry-After", "5")
        delay = float(retry_after) if retry_after.isdecimal() else 5
        if delay >= deadline - time.monotonic():
            print("Still waiting; resume GET for job:", job_id)
            break
        time.sleep(max(1, delay))
        continue
    response.raise_for_status()
    job = response.json()
    if job["status"] == "succeeded":
        print(job.get("artifact", {}))
        break
    if job["status"] == "failed":
        raise RuntimeError(job.get("error", {"message": "Video failed"}))
    time.sleep(5)
else:
    print("Still waiting; resume GET for job:", job_id)
# A local timeout does not cancel the remote job. Keep job_id for later GETs.
```

## 音声の生成と文字起こし

`LAZU_AUDIO_MODEL` に音声生成モデル、`LAZU_VOICE` に対応する声を設定します。`/v1/audio/speech` は JSON ではなく音声バイナリを返します。文字起こしは別の対応モデルを選び、`/v1/audio/transcriptions` にローカル音声ファイルを multipart で送信します。両者は別の機能です。

現在のカタログには音声生成・文字起こしのエンドポイント型がなく、音声モダリティだけでは判別できません。デプロイ管理者または Lazu サポートから確認済みのモデル ID、エンドポイント、対応する声を取得し、現在の API キーでアクセスできることを確認してください。`LAZU_TRANSCRIPTION_MODEL` に確認済みの文字起こしモデル、`LAZU_AUDIO_FILE` にローカル音声ファイルのパスを設定します。

```python
import os
from pathlib import Path
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]}
response = requests.post(origin + "/v1/audio/speech", headers=headers,
    json={"model": os.environ["LAZU_AUDIO_MODEL"], "input": "Hello from Lazu",
          "voice": os.environ["LAZU_VOICE"], "response_format": "mp3"}, timeout=180)
response.raise_for_status()
Path("speech.mp3").write_bytes(response.content)
```

```python
import os
import requests

origin = os.environ.get("LAZU_API_ORIGIN", "https://api.lazu.ai").rstrip("/")
with open(os.environ["LAZU_AUDIO_FILE"], "rb") as audio:
    response = requests.post(origin + "/v1/audio/transcriptions",
        headers={"Authorization": "Bearer " + os.environ["LAZU_API_KEY"]},
        data={"model": os.environ["LAZU_TRANSCRIPTION_MODEL"]},
        files={"file": audio}, timeout=180)
response.raise_for_status()
print(response.json())
```

## エラーと成果物

失敗時はリクエストまたはジョブ ID とエラーコードを保存します。送信がタイムアウトし ID がない場合、再送前に動画一覧（`GET /v1/videos`）やサポートで確認してください。成功したジョブは `artifact.url` を使用し、`artifact.file_id` のみの場合は [Files API](https://lazu.ai/docs/ja/endpoints/files) で取得します。請求は[料金説明](https://lazu.ai/docs/ja/billing)で照合してください。

[API Explorer](https://lazu.ai/docs/ja/api-reference)

---

# Models list

**GET** `/v1/models`

List models available to the current API key in the flat OpenAI-compatible shape. For routing, pricing, modality and usage metadata, use /api/models/catalog instead.

## Example request

```bash
curl https://api.lazu.ai/v1/models \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## Example response

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-6-luna", "object": "model", "owned_by": "openai" },
    { "id": "claude-sonnet-5", "object": "model", "owned_by": "anthropic" }
  ]
}
```

## Which model endpoint should I use?

- **/v1/models** — OpenAI-compatible model list for existing SDKs and tools.
- **/api/models/catalog** — Rich token-scoped catalog for agents, routing, pricing, modalities, endpoint
  support, parameters and usage/cache metadata.

## Response fields

- `object` `string` — Always `list`.
- `data` `object[]` — Accessible model records for the current API key.
- `data[].id` `string` — Model ID.
- `data[].object` `string` — Usually `model`.
- `data[].owned_by` `string` — 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](https://lazu.ai/docs/models/catalog) first.

---

# 模型列表

**GET** `/v1/models`

以扁平 OpenAI-compatible shape 列出当前 API Key 可访问的模型。需要路由、价格、模态和 usage metadata 时，请使用 /api/models/catalog。

## 请求示例

```bash
curl https://api.lazu.ai/v1/models \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## 响应示例

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-6-luna", "object": "model", "owned_by": "openai" },
    { "id": "claude-sonnet-5", "object": "model", "owned_by": "anthropic" }
  ]
}
```

## 应该使用哪个模型 endpoint？

- **/v1/models** — 面向现有 SDK 和工具的 OpenAI-compatible 模型列表。
- **/api/models/catalog** — 面向 agent、路由、计费、模态、endpoint 支持、参数和 usage/cache metadata
  的完整目录。

## 响应字段

- `object` `string` — 始终为 `list`。
- `data` `object[]` — 当前 API Key 可访问的模型记录。
- `data[].id` `string` — 模型 ID。
- `data[].object` `string` — 通常为 `model`。
- `data[].owned_by` `string` — provider 或 owner 标签。

## 过滤行为

模型只会在满足以下条件时出现在这里：

1. 至少有一个可用 Lazu channel 启用了该模型。
2. 当前 API Key 被允许访问该模型。
3. Token 的模型限制没有排除该模型。

如果 agent 需要做可靠选择，请优先读取 [模型目录](https://lazu.ai/docs/zh/models/catalog)。

---

# 模型列表

**GET** `/v1/models`

以扁平 OpenAI-compatible shape 列出目前 API Key 可存取的模型。需要路由、價格、模態和 usage metadata 時，請使用 /api/models/catalog。

## 請求範例

```bash
curl https://api.lazu.ai/v1/models \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## 回應範例

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-6-luna", "object": "model", "owned_by": "openai" },
    { "id": "claude-sonnet-5", "object": "model", "owned_by": "anthropic" }
  ]
}
```

## 應該使用哪個模型 endpoint？

- **/v1/models** — 面向既有 SDK 和工具的 OpenAI-compatible 模型列表。
- **/api/models/catalog** — 面向 agent、路由、計費、模態、endpoint 支援、參數和 usage/cache metadata
  的完整目錄。

## 響應欄位

- `object` `string` — 始終為 `list`。
- `data` `object[]` — 目前 API Key 可存取的模型記錄。
- `data[].id` `string` — 模型 ID。
- `data[].object` `string` — 通常為 `model`。
- `data[].owned_by` `string` — provider 或 owner 標籤。

## 過濾行為

模型只會在滿足以下條件時出現在這裡：

1. 至少有一個可用 Lazu channel 啟用了該模型。
2. 目前 API Key 被允許存取該模型。
3. Token 的模型限制沒有排除該模型。

如果 agent 需要做可靠選擇，請優先讀取 [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)。

---

# モデル一覧

**GET** `/v1/models`

現在の API Key で利用できるモデルを flat OpenAI-compatible shape で返します。routing、pricing、modality、usage metadata には /api/models/catalog を使ってください。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/models \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## レスポンス例

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-6-luna", "object": "model", "owned_by": "openai" },
    { "id": "claude-sonnet-5", "object": "model", "owned_by": "anthropic" }
  ]
}
```

## どちらの endpoint を使うべきか

- **/v1/models** — 既存 SDK や tools 向けの OpenAI-compatible model list。
- **/api/models/catalog** — agents、routing、pricing、modalities、endpoint support、parameters、
  usage/cache metadata のための rich catalog。

## Response fields

- `object` `string` — 常に `list`。
- `data` `object[]` — 現在の API Key でアクセスできる model records。
- `data[].id` `string` — Model ID。
- `data[].object` `string` — 通常 `model`。
- `data[].owned_by` `string` — provider または owner label。

## Filtering behavior

モデルが表示される条件：

1. 少なくとも 1 つの usable Lazu channel で enabled。
2. 現在の API Key がアクセス可能。
3. token model restrictions により除外されていない。

agent が適切に選ぶ必要がある場合は、先に [モデルカタログ](https://lazu.ai/docs/ja/models/catalog) を読んでください。

---

# Responses API

**POST** `/v1/responses`

Use Responses for reasoning models, multimodal inputs and Lazu file\_id dereferencing. This is the recommended endpoint when a request needs uploaded files or newer OpenAI response features.

## Example request

```bash
curl https://api.lazu.ai/v1/responses \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Say hi"}
      ]
    }]
  }'
```

## Example response

```json
{
  "id": "resp_01ABCDEF",
  "model": "gpt-6-luna",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hi!" }]
    }
  ],
  "usage": { "input_tokens": 9, "output_tokens": 2 }
}
```

## When to use it

- **Use Responses** — Uploaded files, reasoning controls, document workflows, and multimodal
  inputs that should be normalized server-side.
- **Use Chat completions** — Simple chat, SDK compatibility, tool calling, and existing apps already
  built around `/v1/chat/completions`.

## Request body

- `model` `string` (required) — Model ID from `/api/models/catalog`. Prefer models where
  `supported_endpoints` includes the path `/v1/responses`.
- `input` `string | object[]` (required) — Text input or an array of response input messages.
- `instructions` `string` (optional) — System-level instructions for the response.
- `reasoning` `object` (optional) — Reasoning effort controls for supported models, for example
  `{"effort":"medium"}`.
- `tools` `object[]` (optional) — Tool definitions using the OpenAI-compatible Responses shape.
- `stream` `boolean` (optional) — Streams response events when supported by the selected model.
- `max_output_tokens` `integer` (optional) — Upper bound for generated output tokens.

## Content parts

- `input_text` `content part` — Text content sent to the model.
- `input_image` `content part` — Image content. Lazu can dereference uploaded `file_id` values
  with purpose `vision`.
- `input_file` `content part` — Uploaded file reference. Lazu dereferences file content server-side before
  forwarding the request upstream.

## File dereferencing

Upload via [Files](https://lazu.ai/docs/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`.

## Stateless compatibility bridges

Some catalog entries expose Responses through a lossless Chat bridge; check
`supported_endpoints[].mode`. On such a route, omitted
`store` is accepted and returns
`X-Lazu-Warning: stateless_bridge`, while
`store: false` is accepted without a warning. Explicit
`store: true`, stateful fields, and unknown cross-protocol fields
return `400 protocol_bridge_unsupported` before an upstream call.
The standard Responses body is not extended with Lazu-only fields.

## Response

- `id` `string` — Response ID.
- `output` `object[]` — Output messages, reasoning items, tool calls, or other response events.
- `usage.input_tokens` `integer` (optional) — Input token count when the upstream reports usage.
- `usage.output_tokens` `integer` (optional) — Output token count when the upstream reports usage.
- `usage.input_tokens_details.cached_tokens` `integer` (optional) — 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](https://lazu.ai/docs/endpoints/files)
- [Chat completions](https://lazu.ai/docs/endpoints/chat)
- [Model catalog](https://lazu.ai/docs/models/catalog)

## Complete tool round trip

Select a model with Responses and function tools from your token-scoped catalog, then set `LAZU_API_KEY` and `LAZU_MODEL`. Keep every output item when continuing a stateless conversation, including reasoning items; append the tool result with the same `call_id`. Encrypted or provider-specific reasoning state remains native-only when a bridge cannot preserve it.

```python
import json
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ.get("LAZU_BASE_URL", "https://api.lazu.ai/v1"),
    max_retries=0,
)
model = os.environ["LAZU_MODEL"]
tools = [{"type": "function", "name": "add", "description": "Add two integers",
          "parameters": {"type": "object", "properties": {
              "a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"], "additionalProperties": False}}]
history = [{"role": "user", "content": "Use add to calculate 2 + 3."}]
try:
    first = client.responses.create(model=model, input=history, tools=tools,
        tool_choice={"type": "function", "name": "add"}, store=False,
        max_output_tokens=1024)
    history.extend(item.model_dump(exclude_unset=True) for item in first.output)
    for item in first.output:
        if item.type == "function_call":
            if item.name != "add":
                raise ValueError("Unexpected tool")
            args = json.loads(item.arguments)
            history.append({"type": "function_call_output", "call_id": item.call_id,
                            "output": json.dumps({"result": args["a"] + args["b"]})})
    final = client.responses.create(model=model, input=history, tools=tools,
        tool_choice="none", store=False, max_output_tokens=1024)
    print(final.output_text)
except APIStatusError as exc:
    print(exc.status_code, exc.response.headers.get("x-lazu-request-id"), exc.body)
    raise
```

Do not replay automatically after output has arrived. For 413 `request_body_too_large`, reduce the request; for 503 `gateway_overloaded`, retry later with backoff. Local overload does not imply a provider failure. Use request details to reconcile partial usage.

---

# Responses API

**POST** `/v1/responses`

Responses 适合 reasoning 模型、多模态输入和 Lazu file\_id 解引用。上传文件或使用较新的 OpenAI response 特性时，优先使用这个 endpoint。

## 请求示例

```bash
curl https://api.lazu.ai/v1/responses \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Say hi"}
      ]
    }]
  }'
```

## 响应示例

```json
{
  "id": "resp_01ABCDEF",
  "model": "gpt-6-luna",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hi!" }]
    }
  ],
  "usage": { "input_tokens": 9, "output_tokens": 2 }
}
```

## 何时使用

- **使用 Responses** — 上传文件、reasoning 控制、文档 workflow，以及需要服务端标准化的多模态输入。
- **使用 Chat completions** — 简单聊天、SDK 兼容、tool calling，以及已经围绕
  `/v1/chat/completions` 构建的应用。

## 请求 Body

- `model` `string` (必填) — 来自 `/api/models/catalog` 的模型 ID。优先选择
  `supported_endpoints` 包含 `/v1/responses` 路径 的模型。
- `input` `string | object[]` (必填) — 文本输入，或 response input messages 数组。
- `instructions` `string` (可选) — response 的系统级 instructions。
- `reasoning` `object` (可选) — 支持 reasoning 的模型可使用 effort 控制，例如
  `{"effort":"medium"}`。
- `tools` `object[]` (可选) — OpenAI-compatible Responses shape 的工具定义。
- `stream` `boolean` (可选) — 当模型支持时，返回 response events stream。
- `max_output_tokens` `integer` (可选) — 生成输出 token 的上限。

## Content parts

- `input_text` `content part` — 发送给模型的文本内容。
- `input_image` `content part` — 图片内容。Lazu 可以解引用 purpose 为 `vision` 的上传文件。
- `input_file` `content part` — 上传文件引用。Lazu 会在服务端读取文件内容后再转发给上游。

## File 解引用

先通过 [Files](https://lazu.ai/docs/zh/endpoints/files) 上传文件，再引用返回的 `file_id`。
如果请求中发生了解引用，Lazu 会添加 `X-Lazu-File-Dereference: 1`。

限制：

- 单文件仍受 purpose 对应大小限制。
- 单次 Responses 调用中解引用的文件总大小必须低于 64 MB。
- Chat completions 不会自动解引用 `file_id`。

## 无状态兼容桥接

部分 catalog 条目会通过无损 Chat 桥接提供 Responses；可查看
`supported_endpoints[].mode`。走这类路由时，省略
`store` 可以正常请求，并返回
`X-Lazu-Warning: stateless_bridge`；显式
`store: false` 正常请求且不产生 warning。显式
`store: true`、无法保真的状态字段或未知跨协议字段会在请求上游前返回
`400 protocol_bridge_unsupported`。标准 Responses body 不会增加
Lazu 私有字段。

## 响应

- `id` `string` — Response ID。
- `output` `object[]` — 输出消息、reasoning items、tool calls 或其它 response events。
- `usage.input_tokens` `integer` (可选) — 上游返回 usage 时的输入 token 数。
- `usage.output_tokens` `integer` (可选) — 上游返回 usage 时的输出 token 数。
- `usage.input_tokens_details.cached_tokens` `integer` (可选) — 支持 response-level cache usage 的 provider 返回的 cache read tokens。

完整对账请使用同一个 API Key 调用：

`GET /api/usage/requests/{request_id}`

## 相关页面

- [Files API](https://lazu.ai/docs/zh/endpoints/files)
- [Chat completions](https://lazu.ai/docs/zh/endpoints/chat)
- [模型目录](https://lazu.ai/docs/zh/models/catalog)

## 完整工具续轮示例

先从当前 Key 的目录选择支持 Responses 和函数工具的模型，再设置 `LAZU_API_KEY`、`LAZU_MODEL`。无状态续轮要保留全部 output item（包括 reasoning），再用原 `call_id` 追加工具结果。桥接无法保留的加密或供应商私有 reasoning 状态仍只能走原生路径。

```python
import json
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ.get("LAZU_BASE_URL", "https://api.lazu.ai/v1"),
    max_retries=0,
)
model = os.environ["LAZU_MODEL"]
tools = [{"type": "function", "name": "add", "description": "Add two integers",
          "parameters": {"type": "object", "properties": {
              "a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"], "additionalProperties": False}}]
history = [{"role": "user", "content": "Use add to calculate 2 + 3."}]
try:
    first = client.responses.create(model=model, input=history, tools=tools,
        tool_choice={"type": "function", "name": "add"}, store=False,
        max_output_tokens=1024)
    history.extend(item.model_dump(exclude_unset=True) for item in first.output)
    for item in first.output:
        if item.type == "function_call":
            if item.name != "add":
                raise ValueError("Unexpected tool")
            args = json.loads(item.arguments)
            history.append({"type": "function_call_output", "call_id": item.call_id,
                            "output": json.dumps({"result": args["a"] + args["b"]})})
    final = client.responses.create(model=model, input=history, tools=tools,
        tool_choice="none", store=False, max_output_tokens=1024)
    print(final.output_text)
except APIStatusError as exc:
    print(exc.status_code, exc.response.headers.get("x-lazu-request-id"), exc.body)
    raise
```

收到输出后不要自动重放。413 `request_body_too_large` 应缩小请求；503 `gateway_overloaded` 可稍后退避重试，它不表示供应商故障。部分用量通过请求详情对账。

---

# Responses API

**POST** `/v1/responses`

Responses 適合 reasoning 模型、多模態輸入和 Lazu file\_id 解引用。上傳檔案或使用較新的 OpenAI response 特性時，優先使用這個 endpoint。

## 請求範例

```bash
curl https://api.lazu.ai/v1/responses \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Say hi"}
      ]
    }]
  }'
```

## 回應範例

```json
{
  "id": "resp_01ABCDEF",
  "model": "gpt-6-luna",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hi!" }]
    }
  ],
  "usage": { "input_tokens": 9, "output_tokens": 2 }
}
```

## 何時使用

- **使用 Responses** — 上傳檔案、reasoning 控制、文件 workflow，以及需要服務端標準化的多模態輸入。
- **使用 Chat completions** — 簡單聊天、SDK 相容、tool calling，以及已經圍繞
  `/v1/chat/completions` 建構的應用。

## 請求 Body

- `model` `string` (必填) — 來自 `/api/models/catalog` 的模型 ID。優先選擇
  `supported_endpoints` 包含 `/v1/responses` 路径 的模型。
- `input` `string | object[]` (必填) — 文字輸入，或 response input messages 陣列。
- `instructions` `string` (可選) — response 的系統級 instructions。
- `reasoning` `object` (可選) — 支援 reasoning 的模型可使用 effort 控制，例如
  `{"effort":"medium"}`。
- `tools` `object[]` (可選) — OpenAI-compatible Responses shape 的工具定義。
- `stream` `boolean` (可選) — 當模型支援時，返回 response events stream。
- `max_output_tokens` `integer` (可選) — 生成輸出 token 的上限。

## File 解引用

先透過 [Files](https://lazu.ai/docs/zh-TW/endpoints/files) 上傳檔案，再引用返回的

`file_id`。如果請求中發生了解引用，Lazu 會加入
`X-Lazu-File-Dereference: 1`。

限制：

- 單檔案仍受 purpose 對應大小限制。
- 單次 Responses 呼叫中解引用的檔案總大小必須低於 64 MB。
- Chat completions 不會自動解引用 `file_id`。

## 無狀態相容橋接

部分 catalog 項目會透過無損 Chat 橋接提供 Responses；可查看
`supported_endpoints[].mode`。走這類路由時，省略
`store` 可以正常請求，並回傳
`X-Lazu-Warning: stateless_bridge`；明確指定
`store: false` 正常請求且不產生 warning。明確指定
`store: true`、無法保真的狀態欄位或未知跨協議欄位，會在呼叫上游前回傳
`400 protocol_bridge_unsupported`。標準 Responses body 不會增加
Lazu 私有欄位。

## 響應

- `id` `string` — Response ID。
- `output` `object[]` — 輸出訊息、reasoning items、tool calls 或其它 response events。
- `usage.input_tokens` `integer` (可選) — 上游返回 usage 時的輸入 token 數。
- `usage.output_tokens` `integer` (可選) — 上游返回 usage 時的輸出 token 數。
- `usage.input_tokens_details.cached_tokens` `integer` (可選) — 支援 response-level cache usage 的 provider 返回的 cache read tokens。

完整對帳請使用同一把 API Key 呼叫：

`GET /api/usage/requests/{request_id}`

## 相關頁面

- [Files API](https://lazu.ai/docs/zh-TW/endpoints/files)
- [Chat completions](https://lazu.ai/docs/zh-TW/endpoints/chat)
- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)

## 完整工具續輪範例

先從目前 Key 的目錄選擇支援 Responses 和函式工具的模型，再設定 `LAZU_API_KEY`、`LAZU_MODEL`。無狀態續輪要保留全部 output item（包括 reasoning），再用原 `call_id` 附加工具結果。橋接無法保留的加密或供應商私有 reasoning 狀態仍只能走原生路徑。

```python
import json
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ.get("LAZU_BASE_URL", "https://api.lazu.ai/v1"),
    max_retries=0,
)
model = os.environ["LAZU_MODEL"]
tools = [{"type": "function", "name": "add", "description": "Add two integers",
          "parameters": {"type": "object", "properties": {
              "a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"], "additionalProperties": False}}]
history = [{"role": "user", "content": "Use add to calculate 2 + 3."}]
try:
    first = client.responses.create(model=model, input=history, tools=tools,
        tool_choice={"type": "function", "name": "add"}, store=False,
        max_output_tokens=1024)
    history.extend(item.model_dump(exclude_unset=True) for item in first.output)
    for item in first.output:
        if item.type == "function_call":
            if item.name != "add":
                raise ValueError("Unexpected tool")
            args = json.loads(item.arguments)
            history.append({"type": "function_call_output", "call_id": item.call_id,
                            "output": json.dumps({"result": args["a"] + args["b"]})})
    final = client.responses.create(model=model, input=history, tools=tools,
        tool_choice="none", store=False, max_output_tokens=1024)
    print(final.output_text)
except APIStatusError as exc:
    print(exc.status_code, exc.response.headers.get("x-lazu-request-id"), exc.body)
    raise
```

收到輸出後不要自動重播。413 `request_body_too_large` 應縮小請求；503 `gateway_overloaded` 可稍後退避重試，它不表示供應商故障。部分用量透過請求詳情對帳。

---

# Responses API

**POST** `/v1/responses`

Responses は reasoning models、multimodal input、Lazu file\_id dereferencing に適しています。uploaded files や新しい OpenAI response features が必要な場合に推奨します。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/responses \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Say hi"}
      ]
    }]
  }'
```

## レスポンス例

```json
{
  "id": "resp_01ABCDEF",
  "model": "gpt-6-luna",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hi!" }]
    }
  ],
  "usage": { "input_tokens": 9, "output_tokens": 2 }
}
```

## 使い分け

- **Responses を使う** — uploaded files、reasoning controls、document workflows、server-side
  normalized multimodal inputs。
- **Chat completions を使う** — simple chat、SDK compatibility、tool calling、既存の
  `/v1/chat/completions` ベースのアプリ。

## Request body

- `model` `string` (必須) — `/api/models/catalog` の model ID。
  `supported_endpoints` に `/v1/responses` のパスを含む model
  を優先してください。
- `input` `string | object[]` (必須) — text input または response input messages array。
- `instructions` `string` (任意) — response の system-level instructions。
- `reasoning` `object` (任意) — supported models で reasoning effort を制御します。例：
  `{"effort":"medium"}`。
- `tools` `object[]` (任意) — OpenAI-compatible Responses shape の tool definitions。
- `stream` `boolean` (任意) — model が対応する場合、response events stream を返します。
- `max_output_tokens` `integer` (任意) — generated output tokens の上限。

## File dereferencing

[Files](https://lazu.ai/docs/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 しません。

## Stateless compatibility bridge

一部の catalog entry は lossless Chat bridge 経由で Responses を提供します。
`supported_endpoints[].mode` で確認できます。この route では
`store` 省略時は成功し
`X-Lazu-Warning: stateless_bridge` を返し、
`store: false` は warning なしで成功します。明示的な
`store: true`、保持できない state field、未知の cross-protocol
field は upstream call 前に `400 protocol_bridge_unsupported`
になります。標準 Responses body に Lazu 独自 field は追加しません。

## Response

- `id` `string` — Response ID。
- `output` `object[]` — output messages、reasoning items、tool calls、その他 response events。
- `usage.input_tokens` `integer` (任意) — upstream が usage を返す場合の input token count。
- `usage.output_tokens` `integer` (任意) — upstream が usage を返す場合の output token count。

完全な照合には同じ API Key で

`GET /api/usage/requests/{request_id}` を使ってください。

## ツール結果を含む完全な往復

キーのカタログから Responses と関数ツールに対応するモデルを選び、`LAZU_API_KEY` と `LAZU_MODEL` を設定します。ステートレスな継続では reasoning を含む全 output item を保持し、同じ `call_id` でツール結果を追加します。ブリッジで保持できない暗号化状態やプロバイダー固有状態はネイティブ経路が必要です。

```python
import json
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ.get("LAZU_BASE_URL", "https://api.lazu.ai/v1"),
    max_retries=0,
)
model = os.environ["LAZU_MODEL"]
tools = [{"type": "function", "name": "add", "description": "Add two integers",
          "parameters": {"type": "object", "properties": {
              "a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"], "additionalProperties": False}}]
history = [{"role": "user", "content": "Use add to calculate 2 + 3."}]
try:
    first = client.responses.create(model=model, input=history, tools=tools,
        tool_choice={"type": "function", "name": "add"}, store=False,
        max_output_tokens=1024)
    history.extend(item.model_dump(exclude_unset=True) for item in first.output)
    for item in first.output:
        if item.type == "function_call":
            if item.name != "add":
                raise ValueError("Unexpected tool")
            args = json.loads(item.arguments)
            history.append({"type": "function_call_output", "call_id": item.call_id,
                            "output": json.dumps({"result": args["a"] + args["b"]})})
    final = client.responses.create(model=model, input=history, tools=tools,
        tool_choice="none", store=False, max_output_tokens=1024)
    print(final.output_text)
except APIStatusError as exc:
    print(exc.status_code, exc.response.headers.get("x-lazu-request-id"), exc.body)
    raise
```

出力を受信した後は自動再送しないでください。413 `request_body_too_large` はリクエストを縮小し、503 `gateway_overloaded` は時間を置いて再試行します。後者はプロバイダー障害を意味しません。部分用量はリクエスト詳細で照合できます。

---

# Search

**POST** `/v1/search`

Run provider-neutral web or news search through Lazu. Hosted api.lazu.ai currently enables Tavily, Serper and Jina; self-hosted operators can add Exa or Brave through the same search-backend system.

## Example request

```bash
curl https://api.lazu.ai/v1/search \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest OpenAI web search API changes",
    "type": "web",
    "max_results": 5,
    "backend": "auto"
  }'
```

## Example response

```json
{
  "query": "latest OpenAI web search API changes",
  "results": [
    {
      "title": "OpenAI ships web search API",
      "url": "https://example.com/news",
      "snippet": "…",
      "score": 0.92,
      "source": "tavily"
    }
  ],
  "usage": {
    "web_search_requests": 1,
    "web_search_billable_units": 1
  },
  "provider_trace": { "backend": "tavily" },
  "route_receipt": {
    "selection": "auto",
    "selected_backend": "search_tavily",
    "chose_provider": "tavily",
    "candidates": ["search_tavily"],
    "decision_reason": "matched web_search capability"
  }
}
```

## What it returns

- **Normalized results** — Every backend maps into `title`, `url`,
  `snippet`, optional `content`,
  `published_at`, `score` and `source`.
- **Auditable routing** — 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

- `query` `string` (required) — Search query. The MVP supports one query per request.
- `type` `string` (optional) — Search vertical. Defaults to `web`. One of: `web`, `news`
- `backend` `string` (optional) — `auto`, a provider name such as `tavily` or&#x20;
  `serper`, or a configured backend ID/name. Defaults to&#x20;
  `auto`.
- `region` `string` (optional) — Region hint. Serper maps this to `gl`; other providers may ignore
  unsupported regions.
- `language` `string` (optional) — Language hint such as `en` or `zh-CN`.
- `time_range` `string` (optional) — Freshness hint. Providers that cannot map the value may ignore it. One of: `day`, `week`, `month`, `year`
- `max_results` `integer` (optional) — Number of results to return. Defaults to `10` and is capped by
  the selected backend policy.
- `search_depth` `string` (optional) — Provider depth hint. Tavily `advanced` uses two billable credits. One of: `basic`, `advanced`
- `include_answer` `boolean` (optional) — Include a provider answer when the selected backend returns one. Lazu does
  not generate its own final answer in this endpoint.
- `include_raw_content` `boolean` (optional) — Include raw or cleaned content when the provider returns it. Defaults to
  `false`.
- `include_domains` `string[]` (optional) — Restrict results to domains. Token-level domain allowlists still apply.
- `exclude_domains` `string[]` (optional) — Exclude domains when supported by the selected backend.
- `include_provider_payload` `boolean` (optional) — Return the provider-native payload for debugging. Defaults to
  `false`.
- `provider_options` `object` (optional) — Advanced provider passthrough. Only the selected provider's object is used,
  for example `{"serper":{"tbs":"qdr:d"}}`.

## Response

**Search response**

```json
{
"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"
}
}
```

- `results[]` `object[]` — Normalized search result list. `content` is only populated when
  raw content was requested and returned by the backend.
- `usage.web_search_requests` `integer` — Lazu search request count, normally `1`.
- `usage.web_search_billable_units` `integer` — 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.
- `provider_trace.backend` `string` — Actual provider selected after routing.
- `route_receipt` `object` (optional) — 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.

Check the currently displayed search price and reconcile the `web_search` line item in request details. Do not infer a free service from an old example or deployment configuration.

| 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](https://lazu.ai/docs/billing)
- [Request details](https://lazu.ai/docs/endpoints/usage-requests)
- [Model catalog](https://lazu.ai/docs/models/catalog)

---

# Search

**POST** `/v1/search`

通过 Lazu 统一调用 Web 或 News 搜索。托管版 api.lazu.ai 当前启用了 Tavily、Serper 和 Jina；自部署管理员也可以通过同一套 Search Backend 系统接入 Exa 或 Brave。

## 请求示例

```bash
curl https://api.lazu.ai/v1/search \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest OpenAI web search API changes",
    "type": "web",
    "max_results": 5,
    "backend": "auto"
  }'
```

## 响应示例

```json
{
  "query": "latest OpenAI web search API changes",
  "results": [
    {
      "title": "OpenAI ships web search API",
      "url": "https://example.com/news",
      "snippet": "…",
      "score": 0.92,
      "source": "tavily"
    }
  ],
  "usage": {
    "web_search_requests": 1,
    "web_search_billable_units": 1
  },
  "provider_trace": { "backend": "tavily" },
  "route_receipt": {
    "selection": "auto",
    "selected_backend": "search_tavily",
    "chose_provider": "tavily",
    "candidates": ["search_tavily"],
    "decision_reason": "matched web_search capability"
  }
}
```

## 返回什么

- **归一化结果** — 不同 provider 都会映射成 `title`、`url`、
  `snippet`、可选的 `content`、`published_at`
  、`score` 和 `source`。
- **可解释路由** — 响应会返回实际选中的 backend 和 route receipt。请求日志中也会保存同样的
  routing 元数据，便于排障和对账。

## 托管版配置

`/v1/search` 的实现支持 Tavily、Serper、Exa、Jina 和 Brave，但请查看当前展示的搜索价格，并在请求详情核对 `web_search` 计费明细；不要根据旧示例或部署配置推断搜索免费。

| 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` `string` (必填) — 搜索 query。当前 MVP 每次请求支持一个 query。
- `type` `string` (可选) — 搜索类型，默认 `web`。 取值: `web`, `news`
- `backend` `string` (可选) — `auto`、provider 名称如 `tavily` /`serper`
  ，或已配置的 backend ID/name。默认 `auto`。
- `region` `string` (可选) — 地区 hint。Serper 会映射到 `gl`。
- `language` `string` (可选) — 语言 hint，例如 `en` 或 `zh-CN`。
- `time_range` `string` (可选) — 时间范围 hint。provider 不支持时可能忽略。 取值: `day`, `week`, `month`, `year`
- `max_results` `integer` (可选) — 返回结果数。默认 `10`，并受 backend policy 上限约束。
- `search_depth` `string` (可选) — provider 深度 hint。Tavily `advanced` 会消耗 2 个计费 unit。 取值: `basic`, `advanced`
- `include_answer` `boolean` (可选) — selected backend 返回 answer 时一并返回。Lazu 不在这个 endpoint
  内生成最终答案。
- `include_raw_content` `boolean` (可选) — provider 返回原文或清洗正文时是否透出，默认 `false`。
- `include_domains` `string[]` (可选) — 限制搜索域名。token 级 domain allowlist 仍会生效。
- `exclude_domains` `string[]` (可选) — 排除域名，取决于 selected backend 是否支持。
- `include_provider_payload` `boolean` (可选) — 返回 provider 原始 payload，主要用于排障。默认 `false`。
- `provider_options` `object` (可选) — 高级 provider passthrough。只会使用当前 provider 对应对象，例如&#x20;
  `{"serper":{"tbs":"qdr:d"}}`。

## 响应

**Search response**

```json
{
"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"
}
}
```

- `results[]` `object[]` — 归一化搜索结果。只有请求了 raw content 且 backend 返回时，
  `content` 才会填充。
- `usage.web_search_requests` `integer` — Lazu 搜索请求次数，通常为 `1`。
- `usage.web_search_billable_units` `integer` — 实际计费用的 provider unit。Tavily basic 为 1，Tavily advanced 为 2， Serper
  和 Jina 通常为 1 个成功 query。
- `provider_trace.backend` `string` — 路由后实际选中的 provider。
- `route_receipt` `object` (可选) — 候选、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。

## 相关页面

- [计费规则](https://lazu.ai/docs/zh/billing)
- [请求详情](https://lazu.ai/docs/zh/endpoints/usage-requests)
- [模型目录](https://lazu.ai/docs/zh/models/catalog)

---

# Search

**POST** `/v1/search`

透過 Lazu 統一呼叫 Web 或 News 搜尋。託管版 api.lazu.ai 目前啟用了 Tavily、Serper 和 Jina；自部署管理員也可以透過同一套 Search Backend 系統接入 Exa 或 Brave。

## 請求範例

```bash
curl https://api.lazu.ai/v1/search \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest OpenAI web search API changes",
    "type": "web",
    "max_results": 5,
    "backend": "auto"
  }'
```

## 回應範例

```json
{
  "query": "latest OpenAI web search API changes",
  "results": [
    {
      "title": "OpenAI ships web search API",
      "url": "https://example.com/news",
      "snippet": "…",
      "score": 0.92,
      "source": "tavily"
    }
  ],
  "usage": {
    "web_search_requests": 1,
    "web_search_billable_units": 1
  },
  "provider_trace": { "backend": "tavily" },
  "route_receipt": {
    "selection": "auto",
    "selected_backend": "search_tavily",
    "chose_provider": "tavily",
    "candidates": ["search_tavily"],
    "decision_reason": "matched web_search capability"
  }
}
```

## 返回什麼

- **標準化結果** — 不同 provider 都會映射成 `title`、`url`、
  `snippet`、可選的 `content`、`published_at`
  、`score` 和 `source`。
- **可稽核路由** — 響應會返回實際選中的 backend 和 route receipt。請求日誌中也會保存同樣的
  routing metadata，方便排障和對帳。

## 託管版設定

`/v1/search` 的實作支援 Tavily、Serper、Exa、Jina 和 Brave，但請查看目前顯示的搜尋價格，並在請求詳情核對 `web_search` 計費明細；不要根據舊示例或部署設定推斷搜尋免費。

| 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` `string` (必填) — 搜尋 query。當前 MVP 每次請求支援一個 query。
- `type` `string` (可選) — 搜尋類型，預設 `web`。 取值: `web`, `news`
- `backend` `string` (可選) — `auto`、provider 名稱如 `tavily` 或&#x20;
  `serper`， 或已設定的 backend ID/name。預設 `auto`。
- `region` `string` (可選) — 地區 hint。Serper 會映射到 `gl`。
- `language` `string` (可選) — 語言 hint，例如 `en` 或 `zh-TW`。
- `time_range` `string` (可選) — 時間範圍 hint。provider 不支援時可能忽略。 取值: `day`, `week`, `month`, `year`
- `max_results` `integer` (可選) — 返回結果數。預設 `10`，並受 backend policy 上限約束。
- `search_depth` `string` (可選) — provider 深度 hint。Tavily `advanced` 會消耗 2 個計費 unit。 取值: `basic`, `advanced`
- `include_answer` `boolean` (可選) — selected backend 返回 answer 時一併返回。Lazu 不會在這個 endpoint
  內生成最終答案。
- `include_raw_content` `boolean` (可選) — provider 返回原文或清洗正文時是否透出，預設 `false`。
- `include_domains` `string[]` (可選) — 限制搜尋網域。token 級 domain allowlist 仍會生效。
- `exclude_domains` `string[]` (可選) — 排除網域，取決於 selected backend 是否支援。
- `include_provider_payload` `boolean` (可選) — 返回 provider 原始 payload，主要用於排障。預設 `false`。
- `provider_options` `object` (可選) — 進階 provider passthrough。只會使用當前 provider 對應物件，例如&#x20;
  `{"serper":{"tbs":"qdr:d"}}`。

## 響應

**Search response**

```json
{
"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"
}
}
```

- `results[]` `object[]` — 標準化搜尋結果。只有請求了 raw content 且 backend 返回時，
  `content` 才會填充。
- `usage.web_search_requests` `integer` — Lazu 搜尋請求次數，通常為 `1`。
- `usage.web_search_billable_units` `integer` — 實際計費使用的 provider unit。Tavily basic 為 1，Tavily advanced 為 2，
  Serper 和 Jina 通常為 1 個成功 query。
- `provider_trace.backend` `string` — 路由後實際選中的 provider。
- `route_receipt` `object` (可選) — 候選、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。

## 相關頁面

- [計費規則](https://lazu.ai/docs/zh-TW/billing)
- [請求詳情](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)
- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)

---

# Search

**POST** `/v1/search`

Lazu 経由で provider-neutral な web/news search を実行します。Hosted api.lazu.ai では現在 Tavily、Serper、Jina が有効です。self-hosted の operator は同じ Search Backend 仕組みで Exa や Brave も追加できます。

## リクエスト例

```bash
curl https://api.lazu.ai/v1/search \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest OpenAI web search API changes",
    "type": "web",
    "max_results": 5,
    "backend": "auto"
  }'
```

## レスポンス例

```json
{
  "query": "latest OpenAI web search API changes",
  "results": [
    {
      "title": "OpenAI ships web search API",
      "url": "https://example.com/news",
      "snippet": "…",
      "score": 0.92,
      "source": "tavily"
    }
  ],
  "usage": {
    "web_search_requests": 1,
    "web_search_billable_units": 1
  },
  "provider_trace": { "backend": "tavily" },
  "route_receipt": {
    "selection": "auto",
    "selected_backend": "search_tavily",
    "chose_provider": "tavily",
    "candidates": ["search_tavily"],
    "decision_reason": "matched web_search capability"
  }
}
```

## What it returns

- **Normalized results** — backend ごとに `title`、`url`、`snippet`、
  optional `content`、`published_at`、`score`
  、`source` へ mapping します。
- **Auditable routing** — response は selected backend と route receipt を含みます。同じ routing
  metadata が request logs に保存され、support と billing reconciliation
  に使えます。

## Hosted configuration

`/v1/search` の実装は Tavily、Serper、Exa、Jina、Brave を support しますが、
現在表示される検索価格と、リクエスト詳細の `web_search` 明細を照合してください。過去の例やデプロイ設定から無料と推測しないでください。

| 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

- `query` `string` (必須) — search query。MVP は 1 request につき 1 query を support します。
- `type` `string` (任意) — search vertical。default は `web`。 指定可能な値: `web`, `news`
- `backend` `string` (任意) — `auto`、provider name（例：`tavily`）、または
  configured backend ID/name。default は `auto`。
- `region` `string` (任意) — region hint。Serper は `gl` に mapping します。
- `language` `string` (任意) — language hint。例：`en`、`ja`。
- `time_range` `string` (任意) — freshness hint。provider が mapping できない value
  は無視されることがあります。 指定可能な値: `day`, `week`, `month`, `year`
- `max_results` `integer` (任意) — 結果数。default は `10` で、selected backend policy
  の上限が適用されます。
- `search_depth` `string` (任意) — provider depth hint。Tavily `advanced` は 2 billable credits。 指定可能な値: `basic`, `advanced`
- `include_answer` `boolean` (任意) — selected backend が answer を返す場合に含めます。Lazu はこの endpoint
  内で最終回答を生成しません。
- `include_raw_content` `boolean` (任意) — provider が raw content または cleaned content を返す場合に透過します。
  default は `false`。
- `include_domains` `string[]` (任意) — 検索対象 domain を制限します。token-level domain allowlist
  は引き続き適用されます。
- `exclude_domains` `string[]` (任意) — selected backend が support する場合に domain を除外します。
- `include_provider_payload` `boolean` (任意) — provider-native payload を debugging 用に返します。default は&#x20;
  `false`。
- `provider_options` `object` (任意) — advanced provider passthrough。selected provider の object
  だけが使われます。 例：`{"serper":{"tbs":"qdr:d"}}`。

## Response

**Search response**

```json
{
"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"
}
}
```

- `results[]` `object[]` — normalized search result list。raw content を request し、backend
  が返した場合だけ
  `content` が入ります。
- `usage.web_search_requests` `integer` — Lazu search request count。通常は `1`。
- `usage.web_search_billable_units` `integer` — charge に使われる provider unit。Tavily basic は 1、Tavily advanced は 2、
  Serper と Jina は通常 1 successful query です。
- `provider_trace.backend` `string` — routing 後に実際に選ばれた provider。
- `route_receipt` `object` (任意) — 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

- [料金体系](https://lazu.ai/docs/ja/billing)
- [リクエスト詳細](https://lazu.ai/docs/ja/endpoints/usage-requests)
- [モデルカタログ](https://lazu.ai/docs/ja/models/catalog)

---

# Request details

**GET** `/api/usage/requests/{request_id}`

Fetch the customer receipt for one completed request, including normalized usage dimensions, billing line items and public timing.

## Example request

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## Example response

```json
{
  "object": "usage.request",
  "id": "req_lazu_01ABCDEF",
  "created_at": 1765980000,
  "model": "gpt-6-luna",
  "endpoint": "/v1/chat/completions",
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 300,
    "total_tokens": 1500,
    "dimensions": [
      { "name": "input", "quantity": 1200, "unit": "token" },
      { "name": "cache_read", "quantity": 300, "unit": "token" },
      { "name": "output", "quantity": 300, "unit": "token" }
    ]
  },
  "billing": {
    "currency": "USD",
    "amount_microusd": 480,
    "pricing_version": 3,
    "line_items": [
      {
        "dimension": "input",
        "quantity": 1200,
        "unit_microusd": 150,
        "amount_microusd": 180
      }
    ]
  },
  "routing": {
    "status_code": 200,
    "total_duration_ms": 1840,
    "ttft_ms": 420,
    "was_streaming": true
  },
  "provider_usage": {
    "family": "openai",
    "raw_fields": { "prompt_tokens": 1200, "completion_tokens": 300 }
  },
  "log_id": "log_01ABCDEF"
}
```

## Path parameters

- `request_id` `string` (required) — Request ID for a request made by the same API key. Lazu rejects attempts to
  read another key's request details.

## Response fields

- `id` `string` — The requested request ID.
- `model` `string` — Requested model or route name.
- `usage.measurement` `object` (optional) — Input and output provenance: `provider`, `local_estimate`, or `unavailable`. This optional field is absent on historical or unclassified records; absence does not prove provider measurement.
- `usage.dimensions` `object[]` — Normalized dimensions such as `input`, `output`,
  `cache_read`, `cache_write_5m`,
  `cache_write_1h`, `cache_miss`, audio and image
  dimensions.
- `billing.line_items` `object[]` — Billable usage lines with price, quantity and total charge.
- `routing` `object` (optional) — Public status and timing only. Internal routing decisions and provider identities are not exposed.

## 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](https://lazu.ai/docs/billing)
- [Model catalog](https://lazu.ai/docs/models/catalog)
- [Chat completions](https://lazu.ai/docs/endpoints/chat)

---

# 请求详情

**GET** `/api/usage/requests/{request_id}`

查询已完成请求的客户凭据，包含标准化用量维度、计费明细和公开耗时。

## 请求示例

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## 响应示例

```json
{
  "object": "usage.request",
  "id": "req_lazu_01ABCDEF",
  "created_at": 1765980000,
  "model": "gpt-6-luna",
  "endpoint": "/v1/chat/completions",
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 300,
    "total_tokens": 1500,
    "dimensions": [
      { "name": "input", "quantity": 1200, "unit": "token" },
      { "name": "cache_read", "quantity": 300, "unit": "token" },
      { "name": "output", "quantity": 300, "unit": "token" }
    ]
  },
  "billing": {
    "currency": "USD",
    "amount_microusd": 480,
    "pricing_version": 3,
    "line_items": [
      {
        "dimension": "input",
        "quantity": 1200,
        "unit_microusd": 150,
        "amount_microusd": 180
      }
    ]
  },
  "routing": {
    "status_code": 200,
    "total_duration_ms": 1840,
    "ttft_ms": 420,
    "was_streaming": true
  },
  "provider_usage": {
    "family": "openai",
    "raw_fields": { "prompt_tokens": 1200, "completion_tokens": 300 }
  },
  "log_id": "log_01ABCDEF"
}
```

## 路径参数

- `request_id` `string` (必填) — 同一个 API key 发起的请求 ID。Lazu 不允许读取其它 key 的请求详情。

## 响应字段

- `id` `string` — 请求 ID。
- `model` `string` — 用户请求的模型或 route 名称。
- `usage.measurement` `object` (可选) — 分别表示输入和输出用量来源：`provider`（上游上报）、`local_estimate`（本地估算）、`unavailable`（无法确定）。历史或未分类记录可能没有该字段，缺省不能视为上游实测。
- `usage.dimensions` `object[]` — 标准化 usage 维度，例如 `input`、`output`、
  `cache_read`、`cache_write_5m`、
  `cache_write_1h`、`cache_miss`、audio/image 维度等。
- `billing.line_items` `object[]` — 计费明细。
- `routing` `object` (可选) — 仅返回公开状态和耗时，不暴露内部路由决策及供应商身份。

## 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 为准。

## 相关页面

- [计费规则](https://lazu.ai/docs/zh/billing)
- [模型目录](https://lazu.ai/docs/zh/models/catalog)
- [Chat completions](https://lazu.ai/docs/zh/endpoints/chat)

---

# 請求詳情

**GET** `/api/usage/requests/{request_id}`

查詢已完成請求的客戶憑據，包含標準化用量維度、計費明細和公開耗時。

## 請求範例

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## 回應範例

```json
{
  "object": "usage.request",
  "id": "req_lazu_01ABCDEF",
  "created_at": 1765980000,
  "model": "gpt-6-luna",
  "endpoint": "/v1/chat/completions",
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 300,
    "total_tokens": 1500,
    "dimensions": [
      { "name": "input", "quantity": 1200, "unit": "token" },
      { "name": "cache_read", "quantity": 300, "unit": "token" },
      { "name": "output", "quantity": 300, "unit": "token" }
    ]
  },
  "billing": {
    "currency": "USD",
    "amount_microusd": 480,
    "pricing_version": 3,
    "line_items": [
      {
        "dimension": "input",
        "quantity": 1200,
        "unit_microusd": 150,
        "amount_microusd": 180
      }
    ]
  },
  "routing": {
    "status_code": 200,
    "total_duration_ms": 1840,
    "ttft_ms": 420,
    "was_streaming": true
  },
  "provider_usage": {
    "family": "openai",
    "raw_fields": { "prompt_tokens": 1200, "completion_tokens": 300 }
  },
  "log_id": "log_01ABCDEF"
}
```

## 路徑參數

- `request_id` `string` (必填) — 同一把 API Key 發起的請求 ID。Lazu 不允許讀取其它 key 的請求詳情。

## 響應欄位

- `id` `string` — 請求 ID。
- `model` `string` — 使用者請求的模型或 route 名稱。
- `usage.measurement` `object` (可選) — 分別表示輸入和輸出用量來源：`provider`（上游回報）、`local_estimate`（本地估算）、`unavailable`（無法確定）。歷史或未分類記錄可能沒有此欄位，缺省不能視為上游實測。
- `usage.dimensions` `object[]` — 標準化 usage 維度，例如 `input`、`output`、
  `cache_read`、`cache_write_5m`、
  `cache_write_1h`、`cache_miss`。
- `billing.line_items` `object[]` — 計費明細。
- `routing` `object` (可選) — 僅返回公開狀態和耗時，不暴露內部路由決策及供應商身分。

## Cache 欄位

OpenAI-compatible 響應裡，cache read 可能出現在

`usage.prompt_tokens_details.cached_tokens` 或
`usage.input_tokens_details.cached_tokens`。cache write
只有在上游返回時才會出現。

如果要對帳或排查費用，以請求詳情 API 為準。

## 相關頁面

- [計費規則](https://lazu.ai/docs/zh-TW/billing)
- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)
- [Chat completions](https://lazu.ai/docs/zh-TW/endpoints/chat)

---

# リクエスト詳細

**GET** `/api/usage/requests/{request_id}`

完了したリクエストの使用量、請求明細、公開タイミングを確認します。

## リクエスト例

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
  -H "Authorization: Bearer $LAZU_API_KEY"
```

## レスポンス例

```json
{
  "object": "usage.request",
  "id": "req_lazu_01ABCDEF",
  "created_at": 1765980000,
  "model": "gpt-6-luna",
  "endpoint": "/v1/chat/completions",
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 300,
    "total_tokens": 1500,
    "dimensions": [
      { "name": "input", "quantity": 1200, "unit": "token" },
      { "name": "cache_read", "quantity": 300, "unit": "token" },
      { "name": "output", "quantity": 300, "unit": "token" }
    ]
  },
  "billing": {
    "currency": "USD",
    "amount_microusd": 480,
    "pricing_version": 3,
    "line_items": [
      {
        "dimension": "input",
        "quantity": 1200,
        "unit_microusd": 150,
        "amount_microusd": 180
      }
    ]
  },
  "routing": {
    "status_code": 200,
    "total_duration_ms": 1840,
    "ttft_ms": 420,
    "was_streaming": true
  },
  "provider_usage": {
    "family": "openai",
    "raw_fields": { "prompt_tokens": 1200, "completion_tokens": 300 }
  },
  "log_id": "log_01ABCDEF"
}
```

## Path parameters

- `request_id` `string` (必須) — 同じ API Key が発行した request ID。別 key の request details は読めません。

## Response fields

- `id` `string` — requested request ID。
- `model` `string` — requested model または route name。
- `usage.measurement` `object` (任意) — 入力と出力それぞれの根拠です。`provider` は報告値、`local_estimate` はローカル推計、`unavailable` は不明です。過去の記録などでは省略されます。省略を実測値の証拠と解釈しないでください。
- `usage.dimensions` `object[]` — normalized dimensions。例：`input`、`output`、
  `cache_read`、`cache_write_5m`、
  `cache_miss`。
- `billing.line_items` `object[]` — price、quantity、total charge を含む billable usage lines。
- `routing` `object` (任意) — 公開ステータスとタイミングのみ。内部ルーティング判断やプロバイダーの識別情報は公開しません。

## 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

- [料金体系](https://lazu.ai/docs/ja/billing)
- [モデルカタログ](https://lazu.ai/docs/ja/models/catalog)
- [Chat completions](https://lazu.ai/docs/ja/endpoints/chat)

---

# Errors

Every error Lazu returns has three stable identifiers: a Lazu error number
(`LZ-3101`), a `code` (`insufficient_quota`) and a `type`
(`insufficient_quota`). The HTTP status is always real; an error is never
sent with 200.

## Response shape

OpenAI-compatible routes keep OpenAI's error object and add Lazu's fields
next to it. SDKs that only know OpenAI's fields keep working.

```json
{
  "error": {
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101",
    "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX",
    "details": {}
  }
}
```

Anthropic-compatible routes (`/v1/messages`) use Anthropic's shape and types:

```json
{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101"
  },
  "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX"
}
```

| Field        | Meaning                                                               |
| ------------ | --------------------------------------------------------------------- |
| `code`       | What happened. Stable; branch on this.                                |
| `type`       | What to do next (see below). Stable.                                  |
| `lazu`       | Lazu error number. Stable; quote it to support.                       |
| `message`    | English sentence for developers. May change; never parse it.          |
| `param`      | The request field at fault, when there is one.                        |
| `details`    | Structured values, such as `field`, `model` or `retry_after_seconds`. |
| `request_id` | The request this error belongs to.                                    |
| `docs`       | Link to the row for this number below.                                |

Every error response also carries the `X-Lazu-Request-Id` and
`X-Lazu-Error` headers.

## Types

| Type                             | HTTP     | What to do                                                                                       |
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `invalid_request_error`          | 400, 413 | Fix the request. Do not retry unchanged.                                                         |
| `authentication_error`           | 401      | Fix the API key: invalid, expired and disabled keys have their own codes.                        |
| `permission_error`               | 403      | The key or account may not do this: IP, model, vendor or project scope.                          |
| `not_found_error`                | 404      | Wrong path, model or ID.                                                                         |
| `insufficient_quota`             | 429      | Balance or a budget ran out. Top up or raise the budget; retrying will not help.                 |
| `rate_limit_error`               | 429      | Wait for `Retry-After`, then retry.                                                              |
| `content_policy_violation_error` | 400      | The model refused the content. Change the content.                                               |
| `overloaded_error`               | 503      | Busy. Retry later with backoff.                                                                  |
| `timeout_error`                  | 504      | No answer in time. The outcome is unknown; check before replaying.                               |
| `api_connection_error`           | 502      | The connection dropped. The outcome is unknown; check before replaying.                          |
| `api_error`                      | 500, 502 | Lazu or the model failed. Retry idempotent requests; report persistent ones with the request ID. |

On `/v1/messages`, `insufficient_quota` is sent as Anthropic's
`billing_error`, and `timeout_error` / `api_connection_error` as `api_error`.

## Retry strategy

Only retry a replay-safe request before any output was received. For 429, distinguish a temporary rate limit from `insufficient_quota`: insufficient balance requires action, not repeated retries. Respect `Retry-After` when present; use bounded backoff for transient gateway/upstream failures. SDK automatic retries can create another model invocation when execution is uncertain; configure them deliberately. Gateway failover and client retries are separate decisions.

## Streams

Once a stream has started, the HTTP status cannot change. Lazu ends the
stream with the protocol's own error frame carrying the same error object
(`data: {"error": {...}}` then `data: [DONE]` for Chat Completions, an
`error` event for Responses and Messages). Keep any partial output and check
request details before replaying. For 413 `request_body_too_large`, reduce the
request; for 503 `gateway_overloaded`, retry later with backoff.

## Include the request ID in support tickets

Every Lazu response, success or error, includes:

```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```

Paste it, with the `LZ-` number, into any support ticket. We can trace the
full request path through routing, upstream call and billing.

> Some errors describe a problem on Lazu's side, such as a model route that is
> temporarily broken. Those answer with a neutral "temporarily unavailable"
> message; the cause is recorded against the request ID.

## Error reference

### LZ-1xxx · The request

| Number    | Code                          | HTTP | Type                    | What it means and what to do                                                                                            |
| --------- | ----------------------------- | ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `LZ-1001` | `invalid_request`             | 400  | `invalid_request_error` | The request is invalid. Check the values you entered and try again.                                                     |
| `LZ-1002` | `bad_request_body`            | 400  | `invalid_request_error` | The model rejected the request body as malformed. Check the request parameters.                                         |
| `LZ-1003` | `model_name_required`         | 400  | `invalid_request_error` | The request does not name a model. Fill in the model parameter.                                                         |
| `LZ-1004` | `request_body_too_large`      | 413  | `invalid_request_error` | The request is too large. Shorten it or split it into smaller requests.                                                 |
| `LZ-1005` | `context_length_exceeded`     | 400  | `invalid_request_error` | The input is longer than this model's context window. Shorten the conversation or choose a model with a longer context. |
| `LZ-1006` | `protocol_bridge_unsupported` | 400  | `invalid_request_error` | This route cannot pass a feature of the request to the selected model. Choose a model that supports it natively.        |
| `LZ-1007` | `capability_unsupported`      | 400  | `invalid_request_error` | The selected model does not support a feature this request uses. Choose a model that supports it.                       |
| `LZ-1008` | `convert_request_failed`      | 400  | `invalid_request_error` | The request could not be converted for the selected model. Check the parameters or choose another model.                |
| `LZ-1009` | `missing_required_parameter`  | 400  | `invalid_request_error` | A required parameter is missing. Check the endpoint reference and add it.                                               |
| `LZ-1010` | `endpoint_not_supported`      | 404  | `not_found_error`       | This endpoint is not supported. Check the request URL.                                                                  |
| `LZ-1011` | `tokenization_error`          | 500  | `api_error`             | The input tokens could not be counted. Check that the input is complete.                                                |
| `LZ-1012` | `resource_not_found`          | 404  | `not_found_error`       | This item was not found. It may have been deleted; refresh and try again.                                               |
| `LZ-1013` | `version_conflict`            | 409  | `conflict_error`        | This record changed after you opened it. Refresh and make your change again.                                            |
| `LZ-1014` | `state_conflict`              | 409  | `conflict_error`        | This action does not apply in the current state. Refresh to see the latest state.                                       |
| `LZ-1901` | `client_canceled`             | 499  | `api_connection_error`  | The request was canceled.                                                                                               |

### LZ-20xx · API keys

| Number    | Code                          | HTTP | Type                   | What it means and what to do                                                                                            |
| --------- | ----------------------------- | ---- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `LZ-2001` | `invalid_api_key`             | 401  | `authentication_error` | The API key is invalid. Check that it was copied in full, or create a new key in the console.                           |
| `LZ-2002` | `token_expired`               | 401  | `authentication_error` | This API key has expired. Extend its expiry in the console or create a new key.                                         |
| `LZ-2003` | `token_disabled`              | 401  | `authentication_error` | This API key is disabled. Enable it in the console or use another key.                                                  |
| `LZ-2004` | `ephemeral_credential_denied` | 403  | `permission_error`     | This temporary credential cannot be used for this request. Use it only with the models and endpoints it was issued for. |
| `LZ-2005` | `proxy_signature_invalid`     | 401  | `authentication_error` | The request origin could not be verified. Try again later; contact support if this continues.                           |

### LZ-21xx · Console sessions

| Number    | Code                    | HTTP | Type                   | What it means and what to do                                               |
| --------- | ----------------------- | ---- | ---------------------- | -------------------------------------------------------------------------- |
| `LZ-2101` | `session_required`      | 401  | `authentication_error` | Sign in to continue.                                                       |
| `LZ-2102` | `session_expired`       | 401  | `authentication_error` | Your session has expired. Sign in again.                                   |
| `LZ-2103` | `session_invalid`       | 401  | `authentication_error` | Your session is no longer valid. Sign in again.                            |
| `LZ-2104` | `session_user_mismatch` | 401  | `authentication_error` | This page belongs to a different signed-in account. Reload the page.       |
| `LZ-2105` | `access_token_invalid`  | 401  | `authentication_error` | The access token is invalid. Generate a new access token in your settings. |

### LZ-22xx · Sign-in and registration

| Number    | Code                                   | HTTP | Type                    | What it means and what to do                                                                 |
| --------- | -------------------------------------- | ---- | ----------------------- | -------------------------------------------------------------------------------------------- |
| `LZ-2201` | `password_login_disabled`              | 403  | `permission_error`      | Password sign-in is turned off. Use another sign-in method.                                  |
| `LZ-2202` | `invalid_credentials`                  | 401  | `authentication_error`  | The username or password is incorrect, or the account is disabled. Check them and try again. |
| `LZ-2203` | `registration_closed`                  | 403  | `permission_error`      | New registrations are closed. Contact the administrator if you need an account.              |
| `LZ-2204` | `password_registration_disabled`       | 403  | `permission_error`      | Signing up with a password is turned off. Sign up with an email code or a linked account.    |
| `LZ-2205` | `email_verification_required`          | 400  | `invalid_request_error` | A verified email address is required. Enter your email and its verification code.            |
| `LZ-2206` | `verification_code_invalid`            | 400  | `invalid_request_error` | The verification code is incorrect or has expired. Check it, or request a new one.           |
| `LZ-2207` | `verification_code_attempts_exhausted` | 429  | `rate_limit_error`      | Too many incorrect attempts, so this code no longer works. Request a new code.               |
| `LZ-2210` | `email_code_auth_disabled`             | 403  | `permission_error`      | Email code sign-in is turned off. Use another sign-in method.                                |
| `LZ-2211` | `email_transport_unavailable`          | 503  | `api_error`             | Email codes cannot be sent right now. Use another sign-in method.                            |
| `LZ-2215` | `original_password_incorrect`          | 400  | `invalid_request_error` | The current password is incorrect. Check it and try again.                                   |
| `LZ-2216` | `oauth_provider_not_configured`        | 404  | `not_found_error`       | This sign-in method is not available. Use another one.                                       |
| `LZ-2217` | `oauth_cancelled`                      | 400  | `invalid_request_error` | Authorization was cancelled, so you were not signed in.                                      |
| `LZ-2218` | `oauth_provider_error`                 | 502  | `api_error`             | The sign-in provider returned an error. Try again later.                                     |
| `LZ-2219` | `oauth_state_invalid`                  | 400  | `invalid_request_error` | This sign-in attempt has expired. Start signing in again.                                    |
| `LZ-2220` | `oauth_exchange_failed`                | 502  | `api_error`             | Sign-in could not be completed with the provider. Try again later.                           |
| `LZ-2221` | `oauth_identity_invalid`               | 401  | `authentication_error`  | Your identity from the sign-in provider could not be verified. Try again later.              |
| `LZ-2222` | `oauth_login_failed`                   | 500  | `api_error`             | Sign-in did not complete. Try again later.                                                   |
| `LZ-2223` | `oauth_email_unverified`               | 403  | `permission_error`      | That account has no verified email address. Verify one with the provider, then try again.    |
| `LZ-2224` | `oauth_email_conflict`                 | 409  | `conflict_error`        | This email address matches more than one account. Contact the administrator.                 |
| `LZ-2225` | `oauth_identity_conflict`              | 409  | `conflict_error`        | This provider account is already linked to another user. Sign in as that user instead.       |

### LZ-23xx · Access

| Number    | Code                       | HTTP | Type               | What it means and what to do                                                                         |
| --------- | -------------------------- | ---- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `LZ-2301` | `access_denied`            | 403  | `permission_error` | You don't have permission to do this. Ask an administrator for access.                               |
| `LZ-2302` | `ip_not_allowed`           | 403  | `permission_error` | This API key does not accept requests from your current IP address. Check the key's IP restrictions. |
| `LZ-2303` | `user_banned`              | 403  | `permission_error` | This account has been disabled. Contact an administrator if you have questions.                      |
| `LZ-2304` | `group_access_denied`      | 403  | `permission_error` | This account cannot use the requested lane. Choose another lane.                                     |
| `LZ-2305` | `channel_selection_denied` | 403  | `permission_error` | Only administrators can pin a request to a specific channel.                                         |
| `LZ-2306` | `project_access_suspended` | 403  | `permission_error` | Your access to this project is suspended. Contact a project admin.                                   |
| `LZ-2307` | `address_not_enabled`      | 403  | `permission_error` | This API address is not enabled for your account. Switch back to the default API address.            |

### LZ-26xx · Decisions

| Number    | Code                             | HTTP | Type                    | What it means and what to do                                                   |
| --------- | -------------------------------- | ---- | ----------------------- | ------------------------------------------------------------------------------ |
| `LZ-2601` | `missing_questions`              | 400  | `invalid_request_error` | Supply questions or enable automatic question generation.                      |
| `LZ-2602` | `invalid_decision_state`         | 400  | `invalid_request_error` | Supply text or JSON state, or embedded images.                                 |
| `LZ-2603` | `invalid_decision_questions`     | 400  | `invalid_request_error` | The decision questions are invalid.                                            |
| `LZ-2604` | `unsupported_question_type`      | 400  | `invalid_request_error` | This question type is not supported.                                           |
| `LZ-2605` | `unsupported_decision_input`     | 400  | `invalid_request_error` | This input is not supported by the decision model.                             |
| `LZ-2606` | `unsupported_decision_parameter` | 400  | `invalid_request_error` | This parameter is not supported. Decisions do not support streaming.           |
| `LZ-2607` | `question_generation_failed`     | 502  | `api_error`             | Question generation failed validation. The generation charge will be refunded. |
| `LZ-2608` | `upstream_decision_invalid`      | 502  | `api_error`             | The decision provider returned an invalid response.                            |
| `LZ-2609` | `upstream_capacity`              | 429  | `rate_limit_error`      | Upstream capacity is exhausted. Retry after the indicated delay.               |

### LZ-3xxx · Wallet and budgets

| Number    | Code                             | HTTP | Type                 | What it means and what to do                                                                                        |
| --------- | -------------------------------- | ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `LZ-3101` | `insufficient_quota`             | 429  | `insufficient_quota` | Your wallet balance is too low for this request. Top up to continue.                                                |
| `LZ-3201` | `key_budget_exceeded`            | 429  | `insufficient_quota` | This API key's budget cannot cover the request, so it was not sent. Raise the key budget or lower the output limit. |
| `LZ-3202` | `pre_consume_token_quota_failed` | 429  | `insufficient_quota` | This API key's remaining allowance cannot cover the request. Raise the allowance or use another key.                |
| `LZ-3301` | `member_budget_exceeded`         | 429  | `insufficient_quota` | Your monthly member budget is used up. Ask a project admin to adjust it.                                            |
| `LZ-3401` | `project_budget_exceeded`        | 429  | `insufficient_quota` | The project budget is used up. Ask a project admin to adjust it.                                                    |
| `LZ-3501` | `platform_budget_exceeded`       | 429  | `insufficient_quota` | The platform spending limit has been reached. Contact the platform administrator.                                   |
| `LZ-3601` | `pricing_not_configured`         | 503  | `api_error`          | This model has no price on the selected lane yet, so it can't be used. Choose another model.                        |

### LZ-4xxx · Models and routes

| Number    | Code                         | HTTP | Type                             | What it means and what to do                                                                                                                     |
| --------- | ---------------------------- | ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `LZ-4001` | `model_not_found`            | 404  | `not_found_error`                | This model is not in the model catalog. Check the model name.                                                                                    |
| `LZ-4002` | `model_not_allowed`          | 403  | `permission_error`               | This API key is not allowed to use the requested model. Check the key's model scope.                                                             |
| `LZ-4003` | `token_vendor_denied`        | 403  | `permission_error`               | This API key is not allowed to use models from this vendor. Check the key's vendor scope.                                                        |
| `LZ-4101` | `no_available_channel`       | 503  | `overloaded_error`               | No route can serve this model right now. Try again later or choose another model.                                                                |
| `LZ-4102` | `invalid_channel_id`         | 400  | `invalid_request_error`          | The requested channel ID is invalid.                                                                                                             |
| `LZ-4103` | `channel_disabled`           | 403  | `permission_error`               | The requested channel is disabled.                                                                                                               |
| `LZ-4104` | `channel_config_invalid`     | 503  | `api_error`                      | This model is temporarily unavailable and the request was not completed. Try again later.                                                        |
| `LZ-4105` | `channel_no_available_key`   | 503  | `overloaded_error`               | This model is temporarily unavailable and the request was not completed. Try again later.                                                        |
| `LZ-4106` | `preferred_lane_unavailable` | 503  | `overloaded_error`               | This model is not available on the lane this API key is pinned to, and automatic fallback is off. Choose another model or change the key's lane. |
| `LZ-4301` | `prompt_blocked`             | 400  | `content_policy_violation_error` | The model refused this content under its content policy. Revise the content and try again.                                                       |

### LZ-5xxx · Rate and capacity

| Number    | Code                                | HTTP | Type               | What it means and what to do                                                                   |
| --------- | ----------------------------------- | ---- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `LZ-5001` | `token_rate_limit_exceeded`         | 429  | `rate_limit_error` | This API key is sending requests too quickly. Wait for the Retry-After interval and try again. |
| `LZ-5002` | `request_rate_limit_exceeded`       | 429  | `rate_limit_error` | Too many requests. Wait a moment and try again.                                                |
| `LZ-5003` | `total_request_rate_limit_exceeded` | 429  | `rate_limit_error` | The total request limit has been reached. Wait a moment and try again.                         |
| `LZ-5101` | `gateway_overloaded`                | 503  | `overloaded_error` | The gateway is busy right now. Try again shortly.                                              |
| `LZ-5201` | `upstream_rate_limited`             | 429  | `rate_limit_error` | This model is limiting requests right now. Try again shortly.                                  |
| `LZ-5301` | `too_many_attempts`                 | 429  | `rate_limit_error` | Too many attempts. Wait a moment and try again.                                                |

### LZ-6xxx · Upstream providers

| Number    | Code                        | HTTP | Type                   | What it means and what to do                                                                             |
| --------- | --------------------------- | ---- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `LZ-6001` | `upstream_error`            | 502  | `api_error`            | The model returned an error. Try again later.                                                            |
| `LZ-6002` | `upstream_invalid_response` | 502  | `api_error`            | The model's response could not be used. Check whether a result was produced before you retry.            |
| `LZ-6003` | `upstream_stream_failed`    | 502  | `api_error`            | The model stopped with an error while streaming. Check the partial output before you retry.              |
| `LZ-6101` | `upstream_timeout`          | 504  | `timeout_error`        | The model did not respond in time, so the outcome is unconfirmed. Check your usage log before resending. |
| `LZ-6201` | `upstream_network_error`    | 502  | `api_connection_error` | The connection to the model failed. Try again shortly.                                                   |
| `LZ-6202` | `upstream_overloaded`       | 503  | `overloaded_error`     | The model is busy right now. Try again shortly.                                                          |
| `LZ-6301` | `upstream_auth_failed`      | 502  | `api_error`            | This model is temporarily unavailable and the request was not completed. Try again later.                |
| `LZ-6302` | `upstream_billing_failed`   | 502  | `api_error`            | This model is temporarily unavailable and the request was not completed. Try again later.                |

### LZ-7xxx · Console

| Number    | Code                                     | HTTP | Type                    | What it means and what to do                                                                                                                           |
| --------- | ---------------------------------------- | ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `LZ-7001` | `user_not_found`                         | 404  | `not_found_error`       | The user was not found. It may have been deleted; refresh the list.                                                                                    |
| `LZ-7002` | `user_exists`                            | 409  | `conflict_error`        | This username or email is already registered, or belonged to a deleted account. Choose another.                                                        |
| `LZ-7003` | `user_manage_forbidden`                  | 403  | `permission_error`      | You cannot manage an account whose role is equal to or higher than yours.                                                                              |
| `LZ-7004` | `user_role_elevation_forbidden`          | 403  | `permission_error`      | You cannot give an account a role equal to or higher than your own.                                                                                    |
| `LZ-7005` | `root_user_protected`                    | 403  | `permission_error`      | This admin can't be disabled, deleted or demoted: you can't demote yourself or remove the last admin.                                                  |
| `LZ-7006` | `user_role_unchanged`                    | 409  | `conflict_error`        | This account already has that role.                                                                                                                    |
| `LZ-7007` | `balance_adjustment_reason_required`     | 400  | `invalid_request_error` | Enter a reason for the balance adjustment.                                                                                                             |
| `LZ-7008` | `balance_adjustment_amount_zero`         | 400  | `invalid_request_error` | The adjustment amount cannot be zero. Enter a positive or negative amount.                                                                             |
| `LZ-7009` | `username_invalid`                       | 400  | `invalid_request_error` | Usernames are 2–20 letters, digits, underscores or hyphens, starting with a letter or digit.                                                           |
| `LZ-7010` | `username_unavailable`                   | 409  | `conflict_error`        | This username is taken or reserved. Choose another.                                                                                                    |
| `LZ-7011` | `username_change_cooldown`               | 429  | `rate_limit_error`      | A username can be changed once every {{cooldown\_days}} days. Try again after the waiting period.                                                      |
| `LZ-7012` | `identity_unlink_unavailable`            | 403  | `permission_error`      | Linked sign-in methods cannot be removed yet.                                                                                                          |
| `LZ-7101` | `topup_order_not_found`                  | 404  | `not_found_error`       | No top-up order has this trade number. Check the number and try again.                                                                                 |
| `LZ-7102` | `topup_order_not_pending`                | 409  | `conflict_error`        | This top-up order is no longer pending, so it can't be completed manually. Refresh the list to see its status.                                         |
| `LZ-7103` | `topup_method_unsupported`               | 400  | `invalid_request_error` | Only Stripe top-up orders can be completed manually.                                                                                                   |
| `LZ-7104` | `topup_credit_invalid`                   | 409  | `conflict_error`        | This top-up order has no amount to credit, so it can't be completed. Check the order in Stripe.                                                        |
| `LZ-7105` | `topup_search_keyword_invalid`           | 400  | `invalid_request_error` | A search needs at least 2 characters other than %, \_ and !. Enter a longer order number.                                                              |
| `LZ-7106` | `invalid_amount`                         | 400  | `invalid_request_error` | The top-up amount must be a whole number of dollars within the allowed range. Change the amount and try again.                                         |
| `LZ-7107` | `payment_not_found`                      | 404  | `not_found_error`       | This payment was not found. It may belong to another account; check the link.                                                                          |
| `LZ-7108` | `invoice_unavailable`                    | 404  | `not_found_error`       | The invoice or receipt for this payment isn't ready yet. Try again in a few minutes.                                                                   |
| `LZ-7109` | `payment_provider_unavailable`           | 503  | `api_error`             | The payment service is temporarily unavailable. Try again in a few minutes.                                                                            |
| `LZ-7110` | `no_billing_customer`                    | 409  | `conflict_error`        | This project has no billing profile yet. It's created with the first payment.                                                                          |
| `LZ-7111` | `wallet_ledger_range_invalid`            | 400  | `invalid_request_error` | This date range can't be shown. Choose a range of at most 32 days.                                                                                     |
| `LZ-7112` | `dispute_still_open`                     | 409  | `conflict_error`        | Stripe hasn't closed this dispute with that outcome yet. Record the outcome after Stripe closes it.                                                    |
| `LZ-7113` | `dispute_resolution_failed`              | 409  | `conflict_error`        | The dispute outcome could not be recorded for this top-up. Check the top-up and dispute ID.                                                            |
| `LZ-7114` | `payment_document_reconcile_failed`      | 503  | `api_error`             | The invoice and receipt could not be reconciled with Stripe. Try again later.                                                                          |
| `LZ-7121` | `referral_unavailable`                   | 500  | `invalid_request_error` | Referral details are temporarily unavailable. Retry later.                                                                                             |
| `LZ-7122` | `referral_code_invalid`                  | 400  | `invalid_request_error` | Use 3–20 lowercase letters, digits or hyphens, not starting or ending with a hyphen.                                                                   |
| `LZ-7123` | `referral_code_reserved`                 | 400  | `invalid_request_error` | That name isn't available. Try another.                                                                                                                |
| `LZ-7124` | `referral_code_taken`                    | 409  | `invalid_request_error` | Someone already uses that name.                                                                                                                        |
| `LZ-7125` | `referral_code_limit`                    | 409  | `invalid_request_error` | You've used all your renames.                                                                                                                          |
| `LZ-7126` | `promotion_unavailable`                  | 500  | `invalid_request_error` | Promotion settings are temporarily unavailable. Retry later.                                                                                           |
| `LZ-7127` | `promotion_config_invalid`               | 400  | `invalid_request_error` | Check the promotion percentages, caps and time windows.                                                                                                |
| `LZ-7128` | `referral_status_invalid`                | 400  | `invalid_request_error` | This referral status filter is invalid.                                                                                                                |
| `LZ-7129` | `referral_search_invalid`                | 400  | `invalid_request_error` | This referral search is invalid.                                                                                                                       |
| `LZ-7130` | `referral_not_found`                     | 400  | `invalid_request_error` | The referral reward was not found.                                                                                                                     |
| `LZ-7131` | `referral_not_pending`                   | 409  | `invalid_request_error` | This referral reward is no longer pending.                                                                                                             |
| `LZ-7201` | `key_name_too_long`                      | 400  | `invalid_request_error` | This API key name is too long. Keep it within {{max\_length}} characters.                                                                              |
| `LZ-7202` | `key_enable_blocked`                     | 409  | `conflict_error`        | This API key has expired or used up its allowance, so it can't be enabled. Extend its expiry or raise its allowance first.                             |
| `LZ-7203` | `key_limit_reached`                      | 409  | `conflict_error`        | You already hold {{limit}} API keys in this project, the most allowed. Delete a key you no longer use, then create a new one.                          |
| `LZ-7204` | `secret_unavailable`                     | 409  | `conflict_error`        | Only a fingerprint of this API key was kept, so the full key can't be shown. Create a new key if you need the full value.                              |
| `LZ-7205` | `key_not_found`                          | 404  | `not_found_error`       | This API key no longer exists. It may have been deleted. Refresh the page.                                                                             |
| `LZ-7301` | `channel_not_found`                      | 404  | `not_found_error`       | This channel no longer exists. It may have been deleted; refresh the list.                                                                             |
| `LZ-7302` | `channel_search_backend_managed`         | 409  | `conflict_error`        | This channel is a search backend, so it cannot be changed here. Manage it on the Search backends page.                                                 |
| `LZ-7303` | `channel_lane_invalid`                   | 400  | `invalid_request_error` | Lane “{{lane}}” does not exist. A channel belongs to exactly one existing lane; pick one from the list.                                                |
| `LZ-7304` | `channel_settings_invalid`               | 400  | `invalid_request_error` | The channel's extra settings could not be read, so nothing was saved. Check the JSON format and values.                                                |
| `LZ-7305` | `channel_model_name_too_long`            | 400  | `invalid_request_error` | A model name is longer than 255 characters, so the channel was not saved. Shorten or remove it.                                                        |
| `LZ-7306` | `channel_not_multi_key`                  | 409  | `conflict_error`        | This channel uses a single key, so its keys cannot be managed one by one.                                                                              |
| `LZ-7307` | `channel_key_index_invalid`              | 400  | `invalid_request_error` | That key is no longer in this channel. Refresh the key list and try again.                                                                             |
| `LZ-7308` | `channel_last_key`                       | 409  | `conflict_error`        | This is the channel's last key, so it cannot be deleted. Add another key first, or delete the channel.                                                 |
| `LZ-7309` | `channel_keys_none_eligible`             | 409  | `conflict_error`        | No key matches this action, so nothing changed.                                                                                                        |
| `LZ-7310` | `channel_balance_unsupported`            | 400  | `invalid_request_error` | Balance lookup is not available for this channel type or for multi-key channels.                                                                       |
| `LZ-7311` | `channel_balance_query_failed`           | 502  | `api_error`             | The upstream did not return a balance. Check the channel's key and base URL, then try again.                                                           |
| `LZ-7312` | `channel_upstream_models_failed`         | 502  | `api_error`             | The upstream did not return a model list. Check the key and base URL, or add models by hand.                                                           |
| `LZ-7313` | `channel_task_running`                   | 409  | `conflict_error`        | The same maintenance task is already running, so a new one was not started. Try again when it finishes.                                                |
| `LZ-7314` | `channel_test_failed`                    | 502  | `api_error`             | The channel test failed: the upstream returned an error. Check the key, base URL and test model, then test again.                                      |
| `LZ-7315` | `channel_test_not_sent`                  | 422  | `invalid_request_error` | The test could not be built for this channel, so nothing was sent upstream. Check its type, model mapping and pricing.                                 |
| `LZ-7316` | `channel_route_not_found`                | 404  | `not_found_error`       | This channel does not serve that model in that lane. Refresh the page to see its current routes.                                                       |
| `LZ-7317` | `route_observation_incomplete`           | 409  | `conflict_error`        | This source is still under observation. It can go live after seven days, once every check has passed.                                                  |
| `LZ-7318` | `route_observation_none`                 | 404  | `not_found_error`       | This source has no models under observation. Refresh the page to see its current state.                                                                |
| `LZ-7401` | `setting_invalid`                        | 400  | `invalid_request_error` | A setting value was not accepted, so it was not saved. Check its format and value, then save again.                                                    |
| `LZ-7402` | `content_limit_exceeded`                 | 400  | `invalid_request_error` | This list can hold at most {{limit}} items. Remove some and save again.                                                                                |
| `LZ-7403` | `announcement_not_found`                 | 404  | `not_found_error`       | This announcement no longer exists. Refresh the list.                                                                                                  |
| `LZ-7404` | `email_test_failed`                      | 502  | `api_error`             | The test email could not be sent. Check the SMTP settings; the mail server's reply is in the server log.                                               |
| `LZ-7405` | `email_test_recipient_missing`           | 400  | `invalid_request_error` | Your account has no email address, so there is nowhere to send the test. Add an email address to your account first.                                   |
| `LZ-7406` | `email_recipients_required`              | 400  | `invalid_request_error` | No recipients were chosen, so nothing was sent. Choose users or send to everyone.                                                                      |
| `LZ-7407` | `announcement_email_content_missing`     | 400  | `invalid_request_error` | There is no announcement to send. Enter a title and content, or publish an announcement first.                                                         |
| `LZ-7408` | `translation_token_missing`              | 400  | `invalid_request_error` | Translation needs an API key of your own, and you have none that works. Create or enable a key, then try again.                                        |
| `LZ-7409` | `feedback_request_not_found`             | 404  | `not_found_error`       | No request with this ID was found for your account. Check the request ID.                                                                              |
| `LZ-7410` | `database_unreachable`                   | 503  | `api_error`             | The server cannot reach its database. Check the database service and try again.                                                                        |
| `LZ-7411` | `email_domain_not_allowed`               | 400  | `invalid_request_error` | This email domain is not accepted here. Use an address from an allowed domain.                                                                         |
| `LZ-7412` | `email_alias_not_allowed`                | 400  | `invalid_request_error` | Addresses with “+” or “.” before the @ are not accepted. Use your plain address.                                                                       |
| `LZ-7413` | `password_invalid`                       | 400  | `invalid_request_error` | The password must be 8 to 64 characters and no more than 72 bytes. Choose another password.                                                            |
| `LZ-7414` | `password_reset_link_invalid`            | 400  | `invalid_request_error` | This reset link is invalid or has expired. Request a new one.                                                                                          |
| `LZ-7415` | `password_reset_client_upgrade_required` | 400  | `invalid_request_error` | This page is out of date and your link has not been used. Reload the page and set the password again.                                                  |
| `LZ-7421` | `mail_not_found`                         | 404  | `invalid_request_error` | The archived mail was not found.                                                                                                                       |
| `LZ-7422` | `mail_resend_failed`                     | 400  | `invalid_request_error` | The archived mail could not be resent. Check the delivery details.                                                                                     |
| `LZ-7423` | `admin_email_missing`                    | 400  | `invalid_request_error` | Add an email address to your account before sending a preview.                                                                                         |
| `LZ-7424` | `mail_regenerate_failed`                 | 400  | `invalid_request_error` | The mail could not be regenerated. Regenerate drafts from the usage digest page.                                                                       |
| `LZ-7425` | `digest_settings_invalid`                | 400  | `invalid_request_error` | The digest settings are invalid.                                                                                                                       |
| `LZ-7426` | `mail_send_failed`                       | 400  | `invalid_request_error` | The mail could not be sent. Check the delivery details.                                                                                                |
| `LZ-7501` | `model_name_taken`                       | 409  | `conflict_error`        | A model named {{model}} already exists. Choose another name or edit the existing model.                                                                |
| `LZ-7502` | `vendor_name_taken`                      | 409  | `conflict_error`        | A vendor named {{vendor}} already exists. Choose another name or edit the existing vendor.                                                             |
| `LZ-7503` | `prefill_group_name_taken`               | 409  | `conflict_error`        | A prefill group named {{name}} already exists. Choose another name.                                                                                    |
| `LZ-7504` | `model_sync_not_configured`              | 503  | `api_error`             | Model metadata sync is not set up on this server. Set the metadata endpoint URLs in the server environment and restart it.                             |
| `LZ-7505` | `model_sync_source_unavailable`          | 502  | `api_error`             | The {{source}} catalog could not be read, so nothing was synced. Try again later.                                                                      |
| `LZ-7510` | `lane_not_found`                         | 404  | `not_found_error`       | Lane {{lane}} does not exist. Refresh to see the current lanes.                                                                                        |
| `LZ-7511` | `lane_builtin_locked`                    | 409  | `conflict_error`        | Lane {{lane}} is built in, so it cannot be stopped or deleted.                                                                                         |
| `LZ-7512` | `lane_ever_enabled`                      | 409  | `conflict_error`        | Lane {{lane}} has carried traffic before, so it cannot be deleted. Stop it instead.                                                                    |
| `LZ-7513` | `lane_has_no_sources`                    | 409  | `conflict_error`        | Lane {{lane}} has no sources yet; enabling it would drop every request sent to it. Move a source into it first.                                        |
| `LZ-7514` | `lane_in_use`                            | 409  | `conflict_error`        | Lane {{lane}} still has sources, prices or discounts. Move or remove them before deleting the lane.                                                    |
| `LZ-7520` | `tier_not_found`                         | 404  | `not_found_error`       | Tier {{tier}} does not exist. Refresh to see the current tiers.                                                                                        |
| `LZ-7521` | `tier_exists`                            | 409  | `conflict_error`        | A tier named {{tier}} already exists. Choose another name or edit that tier.                                                                           |
| `LZ-7522` | `tier_builtin_locked`                    | 409  | `conflict_error`        | Tier {{tier}} is built in, so it cannot be deleted.                                                                                                    |
| `LZ-7523` | `tier_has_accounts`                      | 409  | `conflict_error`        | Tier {{tier}} still has accounts in it. Move them to another tier on the Users page, then delete it.                                                   |
| `LZ-7530` | `sell_price_missing`                     | 400  | `invalid_request_error` | No sell price was entered. Enter at least one price before saving.                                                                                     |
| `LZ-7531` | `sell_price_model_listed`                | 409  | `conflict_error`        | {{model}} is still listed, so its price cannot be removed. Unlist the model first.                                                                     |
| `LZ-7532` | `sell_price_model_served`                | 409  | `conflict_error`        | Enabled channels still serve {{model}}; without a price its requests would be refused. Disable those channels first.                                   |
| `LZ-7533` | `sell_price_model_discounted`            | 409  | `conflict_error`        | {{model}} still has an active discount. Remove the discount before removing the price.                                                                 |
| `LZ-7534` | `model_listing_unpriced`                 | 409  | `conflict_error`        | These models have no sell price on any lane and would be billed at $0: {{models}}. Set a price before listing them.                                    |
| `LZ-7535` | `model_listing_no_source`                | 409  | `conflict_error`        | These models have no enabled source on lane {{lane}}: {{models}}. Add a source before listing them.                                                    |
| `LZ-7601` | `feature_unavailable`                    | 403  | `permission_error`      | Team projects are not enabled for this account.                                                                                                        |
| `LZ-7602` | `project_context_mismatch`               | 400  | `invalid_request_error` | The project on this page does not match the project in the request. Reload the page.                                                                   |
| `LZ-7603` | `project_not_found`                      | 404  | `not_found_error`       | This project was not found, or you are no longer a member.                                                                                             |
| `LZ-7604` | `project_member_not_found`               | 404  | `not_found_error`       | This person is not a member of the project. Refresh the member list.                                                                                   |
| `LZ-7605` | `invite_not_found`                       | 404  | `not_found_error`       | This invitation link is not valid. Ask for a new invitation.                                                                                           |
| `LZ-7606` | `budget_request_not_found`               | 404  | `not_found_error`       | This budget request no longer exists. Refresh the list.                                                                                                |
| `LZ-7607` | `undo_expired`                           | 409  | `conflict_error`        | The 10 minutes to undo have passed. Invite the person again.                                                                                           |
| `LZ-7608` | `invalid_budget`                         | 400  | `invalid_request_error` | The budget must be zero or more, or left empty for no limit. Check the amount and save again.                                                          |
| `LZ-7609` | `invalid_effort_cap`                     | 400  | `invalid_request_error` | This reasoning effort cap is not an available level. Choose one from the list.                                                                         |
| `LZ-7610` | `invalid_settings`                       | 400  | `invalid_request_error` | A project setting has an invalid value. Check the settings and save again.                                                                             |
| `LZ-7611` | `cannot_edit_own_budget`                 | 403  | `permission_error`      | You can't change your own budget. Ask another admin to change it.                                                                                      |
| `LZ-7612` | `cannot_change_owner`                    | 403  | `permission_error`      | The owner's role and status can't be changed.                                                                                                          |
| `LZ-7613` | `confirm_mismatch`                       | 400  | `invalid_request_error` | The project name doesn't match. Type the name exactly as shown.                                                                                        |
| `LZ-7614` | `resend_too_soon`                        | 429  | `rate_limit_error`      | This invitation was just sent. Wait a minute before resending.                                                                                         |
| `LZ-7615` | `request_pending`                        | 409  | `conflict_error`        | A budget request is already pending. Wait for it to be handled, or withdraw it first.                                                                  |
| `LZ-7616` | `invalid_pagination`                     | 400  | `invalid_request_error` | This page of the list can't be shown. Refresh the page.                                                                                                |
| `LZ-7617` | `already_member`                         | 409  | `conflict_error`        | This person is already a member.                                                                                                                       |
| `LZ-7618` | `already_invited`                        | 409  | `conflict_error`        | This address already has a pending invitation. Resend that invitation instead.                                                                         |
| `LZ-7619` | `invite_expired`                         | 409  | `conflict_error`        | This invitation has expired. Ask for a new one.                                                                                                        |
| `LZ-7620` | `invite_revoked`                         | 409  | `conflict_error`        | This invitation was revoked. Ask for a new one if you still need access.                                                                               |
| `LZ-7621` | `invite_email_mismatch`                  | 403  | `permission_error`      | This invitation was sent to a different email address. Sign in with that address to accept it.                                                         |
| `LZ-7622` | `invite_email_unverified`                | 403  | `permission_error`      | Verify your email address before accepting this invitation.                                                                                            |
| `LZ-7623` | `invitee_feature_unavailable`            | 403  | `permission_error`      | That account cannot join a project yet. Try a different email, or check again later.                                                                   |
| `LZ-7624` | `invite_email_invalid`                   | 400  | `invalid_request_error` | This email address is not valid. Check it and try again.                                                                                               |
| `LZ-7625` | `invite_role_invalid`                    | 400  | `invalid_request_error` | Choose admin or member as the role.                                                                                                                    |
| `LZ-7626` | `project_name_invalid`                   | 400  | `invalid_request_error` | The project name can't be empty or longer than 191 characters.                                                                                         |
| `LZ-7627` | `project_deletion_dependency`            | 409  | `conflict_error`        | This account still owns or belongs to a team project whose members, payments or Keys depend on it. Resolve those projects before deleting the account. |
| `LZ-7701` | `usage_range_invalid`                    | 400  | `invalid_request_error` | The end of the time range is earlier than its start. Adjust the range and try again.                                                                   |
| `LZ-7702` | `usage_range_too_long`                   | 400  | `invalid_request_error` | The time range is longer than {{max\_days}} days. Choose a shorter range.                                                                              |
| `LZ-7703` | `invalid_usage_summary_window`           | 400  | `invalid_request_error` | The usage summary window is invalid. Check since, until and granularity.                                                                               |
| `LZ-7704` | `request_not_found`                      | 404  | `not_found_error`       | No request with this ID was found for this API key. Check the request ID.                                                                              |
| `LZ-7705` | `log_session_not_found`                  | 404  | `not_found_error`       | This session was not found in the logs you can view. Refresh the page.                                                                                 |
| `LZ-7706` | `usage_export_format_unsupported`        | 400  | `invalid_request_error` | This export format is not supported. Export as CSV or XLSX.                                                                                            |
| `LZ-7707` | `log_cleanup_cutoff_too_recent`          | 400  | `invalid_request_error` | Logs from the last {{min\_days}} days are kept for model rankings. Choose an earlier cutoff date.                                                      |
| `LZ-7708` | `spend_budget_not_found`                 | 404  | `not_found_error`       | This spend budget no longer exists. It may have been deleted. Refresh the page.                                                                        |
| `LZ-7801` | `purpose_not_supported`                  | 400  | `invalid_request_error` | This file purpose is not supported. Upload it as user\_data or vision.                                                                                 |
| `LZ-7802` | `invalid_file`                           | 400  | `invalid_request_error` | The file was not accepted. Check its type and contents, then upload it again.                                                                          |
| `LZ-7803` | `file_too_large`                         | 413  | `invalid_request_error` | The file is larger than the size limit. Upload a smaller file.                                                                                         |
| `LZ-7804` | `file_not_found`                         | 404  | `not_found_error`       | This file was not found or you can't access it. Check the file ID.                                                                                     |
| `LZ-7805` | `file_expired`                           | 400  | `invalid_request_error` | This file has expired and can no longer be used. Upload it again.                                                                                      |
| `LZ-7806` | `file_dereference_failed`                | 502  | `api_error`             | The file could not be loaded from storage, so the request was not sent. Try again shortly.                                                             |
| `LZ-7807` | `file_storage_failed`                    | 502  | `api_error`             | File storage did not finish the operation. Try again shortly.                                                                                          |
| `LZ-7808` | `storage_not_configured`                 | 503  | `api_error`             | File storage is not set up on this site, so files can't be saved or read. Contact the administrator.                                                   |
| `LZ-7809` | `storage_quota_exceeded`                 | 429  | `insufficient_quota`    | Your file storage budget is used up. Delete files you no longer need, or ask to have the budget raised.                                                |
| `LZ-7821` | `unsupported_media_kind`                 | 400  | `invalid_request_error` | This media type is not supported. Choose image or video.                                                                                               |
| `LZ-7822` | `unsupported_media_status`               | 400  | `invalid_request_error` | This status filter is not supported. Use pending, running, succeeded or failed.                                                                        |
| `LZ-7823` | `media_job_not_found`                    | 404  | `not_found_error`       | This media job was not found. Check the job ID.                                                                                                        |
| `LZ-7824` | `artifact_file_not_found`                | 404  | `not_found_error`       | The artifact file was not found. Check the file ID, or upload the file again.                                                                          |
| `LZ-7825` | `video_not_found`                        | 404  | `not_found_error`       | This video job was not found. Check the job ID.                                                                                                        |
| `LZ-7826` | `invalid_studio_media_job`               | 400  | `invalid_request_error` | The Studio job in this request does not match it. Start the generation again from Studio.                                                              |
| `LZ-7827` | `artifact_too_large`                     | 502  | `api_error`             | The generated file is larger than the size that can be stored, so the result was not kept. Try a smaller size or shorter duration.                     |
| `LZ-7828` | `video_artifact_missing`                 | 502  | `api_error`             | The video finished without a file to download. Generate it again.                                                                                      |
| `LZ-7841` | `studio_disabled`                        | 404  | `not_found_error`       | Studio is not enabled on this site.                                                                                                                    |
| `LZ-7842` | `studio_generation_not_found`            | 404  | `not_found_error`       | This creation was not found, or it is no longer visible to you. Refresh the page.                                                                      |
| `LZ-7843` | `studio_project_not_found`               | 404  | `not_found_error`       | This Studio project or canvas item was not found. It may have been deleted; refresh the page.                                                          |
| `LZ-7844` | `studio_artifact_not_found`              | 404  | `not_found_error`       | The file for this creation is missing or has expired. Generate it again.                                                                               |
| `LZ-7845` | `studio_artifact_unsupported`            | 415  | `invalid_request_error` | This file is not a supported image or video. Choose a PNG, JPEG, GIF, WebP or video file.                                                              |
| `LZ-7846` | `studio_key_unavailable`                 | 400  | `invalid_request_error` | The selected API key is disabled or no longer exists. Choose another key.                                                                              |
| `LZ-7847` | `studio_key_required`                    | 400  | `invalid_request_error` | Generating on your account balance only works from a signed-in browser. Choose an API key instead.                                                     |
| `LZ-7848` | `studio_creator_not_found`               | 404  | `not_found_error`       | No creator with this name has public works yet. Check the link, or browse the latest works.                                                            |
| `LZ-7849` | `studio_sign_in_required`                | 401  | `authentication_error`  | Sign in to continue. Searching, downloading originals and browsing further need an account.                                                            |
| `LZ-7850` | `studio_download_limit_reached`          | 429  | `rate_limit_error`      | You've used today's original downloads. The allowance resets at midnight in your time zone; previews can still be downloaded.                          |
| `LZ-7851` | `studio_free_unavailable`                | 409  | `conflict_error`        | Today's free image isn't available. It may already be used, or your account needs a verified e-mail.                                                   |
| `LZ-7852` | `studio_not_favoritable`                 | 409  | `conflict_error`        | Only published works can be added to favorites.                                                                                                        |
| `LZ-7853` | `studio_signature_invalid`               | 403  | `permission_error`      | This download link is invalid or has expired. Start the download again.                                                                                |
| `LZ-7861` | `search_backend_not_found`               | 404  | `not_found_error`       | This search backend was not found. Refresh the list.                                                                                                   |
| `LZ-7862` | `search_backend_provider_invalid`        | 400  | `invalid_request_error` | This search provider is not supported or does not match the channel type. Choose a listed provider.                                                    |
| `LZ-7863` | `poster_draft_not_found`                 | 404  | `not_found_error`       | This poster draft was not found. Refresh the list.                                                                                                     |
| `LZ-7864` | `upload_file_not_found`                  | 404  | `not_found_error`       | This data file was not found on the server. Check the file path.                                                                                       |
| `LZ-7865` | `upload_key_not_allowed`                 | 400  | `invalid_request_error` | This path can't be uploaded. Directories and configuration files are excluded; choose a regular data file.                                             |
| `LZ-7866` | `upload_failed`                          | 502  | `api_error`             | Object storage did not accept the upload. Check the storage settings and try again.                                                                    |
| `LZ-7867` | `blog_validation_failed`                 | 400  | `invalid_request_error` | The blog request is invalid: {reason\|check the values}.                                                                                               |
| `LZ-7868` | `blog_publish_blocked`                   | 422  | `invalid_request_error` | The post does not pass its publish checks.                                                                                                             |

### LZ-9xxx · Internal

| Number    | Code              | HTTP | Type        | What it means and what to do                                                                             |
| --------- | ----------------- | ---- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `LZ-9001` | `internal_error`  | 500  | `api_error` | The service could not complete this request. If it keeps happening, contact support with the request ID. |
| `LZ-9002` | `not_implemented` | 501  | `api_error` | This feature is not available yet.                                                                       |

## See also

- [Rate limits](https://lazu.ai/docs/limits)
- [Authentication](https://lazu.ai/docs/authentication)
- [Request details](https://lazu.ai/docs/endpoints/usage-requests)

---

# 错误码

Lazu 返回的每个错误都有三个稳定标识：Lazu 错误编号（`LZ-3101`）、`code`（`insufficient_quota`）和 `type`（`insufficient_quota`）。HTTP 状态码始终是真实的，错误不会以 200 返回。

## 响应结构

OpenAI 兼容接口保留 OpenAI 的错误对象，Lazu 的字段加在旁边。只认识 OpenAI 字段的 SDK 照常工作。

```json
{
  "error": {
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101",
    "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX",
    "details": {}
  }
}
```

Anthropic 兼容接口（`/v1/messages`）使用 Anthropic 的结构和类型：

```json
{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101"
  },
  "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX"
}
```

| 字段           | 含义                                              |
| ------------ | ----------------------------------------------- |
| `code`       | 发生了什么。稳定，程序按它分支。                                |
| `type`       | 下一步该做什么（见下表）。稳定。                                |
| `lazu`       | Lazu 错误编号。稳定，联系支持时提供它。                          |
| `message`    | 给开发者看的英文说明。可能调整，不要解析它。                          |
| `param`      | 出问题的请求字段（如有）。                                   |
| `details`    | 结构化的值，例如 `field`、`model`、`retry_after_seconds`。 |
| `request_id` | 这个错误所属的请求。                                      |
| `docs`       | 指向本页对应编号的链接。                                    |

每个错误响应还带有 `X-Lazu-Request-Id` 和 `X-Lazu-Error` 响应头。

## 错误类型

| 类型                               | HTTP    | 处理方式                               |
| -------------------------------- | ------- | ---------------------------------- |
| `invalid_request_error`          | 400、413 | 修正请求，原样重试没有用。                      |
| `authentication_error`           | 401     | 修正 API Key：无效、过期、停用各有自己的 code。     |
| `permission_error`               | 403     | Key 或账号不允许这个操作：IP、模型、供应商或项目范围。     |
| `not_found_error`                | 404     | 路径、模型或 ID 不对。                      |
| `insufficient_quota`             | 429     | 余额或某项预算用完。充值或调高预算，重试无效。            |
| `rate_limit_error`               | 429     | 等待 `Retry-After` 后再试。              |
| `content_policy_violation_error` | 400     | 模型拒绝了内容，需要修改内容。                    |
| `overloaded_error`               | 503     | 繁忙，稍后退避重试。                         |
| `timeout_error`                  | 504     | 没有及时返回，结果未知；重放前先确认。                |
| `api_connection_error`           | 502     | 连接中断，结果未知；重放前先确认。                  |
| `api_error`                      | 500、502 | Lazu 或模型出错。幂等请求可重试；持续出现请带请求编号联系支持。 |

在 `/v1/messages` 上，`insufficient_quota` 以 Anthropic 的 `billing_error` 返回，`timeout_error` 和 `api_connection_error` 以 `api_error` 返回。

## 重试策略

只在尚未收到输出、且请求可以安全重放时重试。429 要区分临时限流和 `insufficient_quota`：余额不足需要处理额度，不能靠重试解决。有 `Retry-After` 时遵循它；临时网关/上游故障采用有限次退避。执行状态不明时，SDK 自动重试可能产生另一次调用，应明确配置。网关切换渠道和客户端重试是两个决定。

## 流式响应

流开始后 HTTP 状态码不能再改变。Lazu 会用协议自己的错误帧结束流，帧里是同样的错误对象（Chat Completions 为 `data: {"error": {...}}` 加 `data: [DONE]`，Responses 和 Messages 为 `error` 事件）。请保留已收到的部分输出，重放前先查看请求详情。遇到 413 `request_body_too_large` 请缩小请求；遇到 503 `gateway_overloaded` 请稍后退避重试。

## 提交支持工单

每个 Lazu 响应（成功或失败）都带有：

```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```

把它和 `LZ-` 编号一起贴进支持工单，我们可以追踪完整的路由、上游调用和计费过程。

> 有些错误是 Lazu 这一侧的问题，比如某条模型线路暂时故障。这类错误只返回中性的「暂时不可用」说明，具体原因记录在请求编号下。

## 错误编号速查

### LZ-1xxx · 请求本身

| 编号        | Code                          | HTTP | 类型                      | 含义与处理                                 |
| --------- | ----------------------------- | ---- | ----------------------- | ------------------------------------- |
| `LZ-1001` | `invalid_request`             | 400  | `invalid_request_error` | 请求内容不正确。请检查填写的内容后再试。                  |
| `LZ-1002` | `bad_request_body`            | 400  | `invalid_request_error` | 请求体格式不正确，模型没有接受。请检查请求参数。              |
| `LZ-1003` | `model_name_required`         | 400  | `invalid_request_error` | 请求中缺少模型名称。请填写 model 参数。               |
| `LZ-1004` | `request_body_too_large`      | 413  | `invalid_request_error` | 请求内容过大。请缩减内容或拆分后再发送。                  |
| `LZ-1005` | `context_length_exceeded`     | 400  | `invalid_request_error` | 输入超出了模型的上下文长度。请缩短对话，或换用上下文更长的模型。      |
| `LZ-1006` | `protocol_bridge_unsupported` | 400  | `invalid_request_error` | 当前线路无法把请求中的某项功能转交给所选模型。请换用原生支持该功能的模型。 |
| `LZ-1007` | `capability_unsupported`      | 400  | `invalid_request_error` | 所选模型不支持这次请求用到的功能。请换用支持该功能的模型。         |
| `LZ-1008` | `convert_request_failed`      | 400  | `invalid_request_error` | 请求无法转换成所选模型的格式。请检查参数，或换用其他模型。         |
| `LZ-1009` | `missing_required_parameter`  | 400  | `invalid_request_error` | 请求缺少必填参数。请对照接口文档补齐。                   |
| `LZ-1010` | `endpoint_not_supported`      | 404  | `not_found_error`       | 不支持这个接口。请检查请求地址。                      |
| `LZ-1011` | `tokenization_error`          | 500  | `api_error`             | 无法计算输入的 token 数。请检查输入内容是否完整。          |
| `LZ-1012` | `resource_not_found`          | 404  | `not_found_error`       | 找不到要操作的内容，它可能已被删除。请刷新后再试。             |
| `LZ-1013` | `version_conflict`            | 409  | `conflict_error`        | 这条记录在你打开后被修改过。请刷新后重新操作。               |
| `LZ-1014` | `state_conflict`              | 409  | `conflict_error`        | 当前状态下不能执行这个操作。请刷新查看最新状态。              |
| `LZ-1901` | `client_canceled`             | 499  | `api_connection_error`  | 请求已取消。                                |

### LZ-20xx · API Key

| 编号        | Code                          | HTTP | 类型                     | 含义与处理                                |
| --------- | ----------------------------- | ---- | ---------------------- | ------------------------------------ |
| `LZ-2001` | `invalid_api_key`             | 401  | `authentication_error` | API Key 无效。请检查 Key 是否复制完整，或在控制台新建一把。 |
| `LZ-2002` | `token_expired`               | 401  | `authentication_error` | 这把 API Key 已过期。请在控制台延长有效期，或新建一把 Key。 |
| `LZ-2003` | `token_disabled`              | 401  | `authentication_error` | 这把 API Key 已停用。请在控制台启用它，或换用其他 Key。   |
| `LZ-2004` | `ephemeral_credential_denied` | 403  | `permission_error`     | 这个临时凭证不能用于本次请求。请只在签发时限定的模型和接口上使用。    |
| `LZ-2005` | `proxy_signature_invalid`     | 401  | `authentication_error` | 无法确认请求来源。请稍后再试；如果持续出现，请联系支持。         |

### LZ-21xx · 控制台登录状态

| 编号        | Code                    | HTTP | 类型                     | 含义与处理                  |
| --------- | ----------------------- | ---- | ---------------------- | ---------------------- |
| `LZ-2101` | `session_required`      | 401  | `authentication_error` | 请先登录。                  |
| `LZ-2102` | `session_expired`       | 401  | `authentication_error` | 登录已过期，请重新登录。           |
| `LZ-2103` | `session_invalid`       | 401  | `authentication_error` | 登录状态已失效，请重新登录。         |
| `LZ-2104` | `session_user_mismatch` | 401  | `authentication_error` | 当前页面属于另一个已登录的账号。请刷新页面。 |
| `LZ-2105` | `access_token_invalid`  | 401  | `authentication_error` | 访问令牌无效。请在个人设置中重新生成。    |

### LZ-22xx · 登录与注册

| 编号        | Code                                   | HTTP | 类型                      | 含义与处理                           |
| --------- | -------------------------------------- | ---- | ----------------------- | ------------------------------- |
| `LZ-2201` | `password_login_disabled`              | 403  | `permission_error`      | 密码登录已关闭。请换用其他登录方式。              |
| `LZ-2202` | `invalid_credentials`                  | 401  | `authentication_error`  | 用户名或密码错误，或账号已被停用。请检查后再试。        |
| `LZ-2203` | `registration_closed`                  | 403  | `permission_error`      | 目前不开放注册新账号。如需账号，请联系管理员。         |
| `LZ-2204` | `password_registration_disabled`       | 403  | `permission_error`      | 已关闭密码注册。请用邮箱验证码或第三方账号注册。        |
| `LZ-2205` | `email_verification_required`          | 400  | `invalid_request_error` | 注册需要验证邮箱。请填写邮箱地址和验证码。           |
| `LZ-2206` | `verification_code_invalid`            | 400  | `invalid_request_error` | 验证码错误或已过期。请检查，或重新获取。            |
| `LZ-2207` | `verification_code_attempts_exhausted` | 429  | `rate_limit_error`      | 验证码错误次数过多，已失效。请重新获取验证码。         |
| `LZ-2210` | `email_code_auth_disabled`             | 403  | `permission_error`      | 邮箱验证码登录已关闭。请换用其他登录方式。           |
| `LZ-2211` | `email_transport_unavailable`          | 503  | `api_error`             | 暂时无法发送邮箱验证码。请换用其他登录方式。          |
| `LZ-2215` | `original_password_incorrect`          | 400  | `invalid_request_error` | 当前密码不正确。请检查后再试。                 |
| `LZ-2216` | `oauth_provider_not_configured`        | 404  | `not_found_error`       | 这个登录方式暂不可用。请换用其他方式。             |
| `LZ-2217` | `oauth_cancelled`                      | 400  | `invalid_request_error` | 你取消了授权，登录没有完成。                  |
| `LZ-2218` | `oauth_provider_error`                 | 502  | `api_error`             | 登录服务商返回了错误。请稍后再试。               |
| `LZ-2219` | `oauth_state_invalid`                  | 400  | `invalid_request_error` | 这次登录已失效。请重新发起登录。                |
| `LZ-2220` | `oauth_exchange_failed`                | 502  | `api_error`             | 没能和登录服务商完成登录。请稍后再试。             |
| `LZ-2221` | `oauth_identity_invalid`               | 401  | `authentication_error`  | 无法验证你在登录服务商的身份。请稍后再试。           |
| `LZ-2222` | `oauth_login_failed`                   | 500  | `api_error`             | 登录没有完成。请稍后再试。                   |
| `LZ-2223` | `oauth_email_unverified`               | 403  | `permission_error`      | 这个账号没有已验证的邮箱。请先在对应平台验证邮箱，再重新登录。 |
| `LZ-2224` | `oauth_email_conflict`                 | 409  | `conflict_error`        | 这个邮箱对应多个账号。请联系管理员处理。            |
| `LZ-2225` | `oauth_identity_conflict`              | 409  | `conflict_error`        | 这个第三方账号已绑定其他用户。请用那个用户登录。        |

### LZ-23xx · 访问权限

| 编号        | Code                       | HTTP | 类型                 | 含义与处理                                       |
| --------- | -------------------------- | ---- | ------------------ | ------------------------------------------- |
| `LZ-2301` | `access_denied`            | 403  | `permission_error` | 你没有执行这个操作的权限。如需开通，请联系管理员。                   |
| `LZ-2302` | `ip_not_allowed`           | 403  | `permission_error` | 这把 API Key 不接受来自你当前 IP 的请求。请检查 Key 的 IP 限制。 |
| `LZ-2303` | `user_banned`              | 403  | `permission_error` | 这个账号已被停用。如有疑问，请联系管理员。                       |
| `LZ-2304` | `group_access_denied`      | 403  | `permission_error` | 当前账号不能使用所请求的线路。请换用其他线路。                     |
| `LZ-2305` | `channel_selection_denied` | 403  | `permission_error` | 只有管理员可以把请求指定到某个渠道。                          |
| `LZ-2306` | `project_access_suspended` | 403  | `permission_error` | 你在这个项目的访问已暂停。请联系项目管理员。                      |
| `LZ-2307` | `address_not_enabled`      | 403  | `permission_error` | 你的账户没有开通这个接入地址。请换回默认地址。                     |

### LZ-26xx · 判别模型

| 编号        | Code                             | HTTP | 类型                      | 含义与处理                      |
| --------- | -------------------------------- | ---- | ----------------------- | -------------------------- |
| `LZ-2601` | `missing_questions`              | 400  | `invalid_request_error` | 请提供 questions，或开启自动生成判别问题。 |
| `LZ-2602` | `invalid_decision_state`         | 400  | `invalid_request_error` | 请提供文本或 JSON 材料，或嵌入图片。      |
| `LZ-2603` | `invalid_decision_questions`     | 400  | `invalid_request_error` | 判别问题格式不正确。                 |
| `LZ-2604` | `unsupported_question_type`      | 400  | `invalid_request_error` | 暂不支持这种问题类型。                |
| `LZ-2605` | `unsupported_decision_input`     | 400  | `invalid_request_error` | 该判别模型不支持这种输入。              |
| `LZ-2606` | `unsupported_decision_parameter` | 400  | `invalid_request_error` | 暂不支持这个参数。判别接口不支持流式输出。      |
| `LZ-2607` | `question_generation_failed`     | 502  | `api_error`             | 生成的问题未通过校验，生成费用将退回。        |
| `LZ-2608` | `upstream_decision_invalid`      | 502  | `api_error`             | 判别模型返回的结果格式不正确。            |
| `LZ-2609` | `upstream_capacity`              | 429  | `rate_limit_error`      | 上游容量已满，请按提示时间稍后重试。         |

### LZ-3xxx · 钱包与预算

| 编号        | Code                             | HTTP | 类型                   | 含义与处理                                            |
| --------- | -------------------------------- | ---- | -------------------- | ------------------------------------------------ |
| `LZ-3101` | `insufficient_quota`             | 429  | `insufficient_quota` | 钱包余额不足，无法完成这次请求。请充值后继续。                          |
| `LZ-3201` | `key_budget_exceeded`            | 429  | `insufficient_quota` | 这把 API Key 的预算不够覆盖本次请求，请求没有发出。请调高 Key 预算或降低输出上限。 |
| `LZ-3202` | `pre_consume_token_quota_failed` | 429  | `insufficient_quota` | 这把 API Key 的剩余额度不够本次请求。请调高额度或换用其他 Key。           |
| `LZ-3301` | `member_budget_exceeded`         | 429  | `insufficient_quota` | 你本月的成员预算已用完。请联系项目管理员调整。                          |
| `LZ-3401` | `project_budget_exceeded`        | 429  | `insufficient_quota` | 项目预算已用完。请联系项目管理员调整。                              |
| `LZ-3501` | `platform_budget_exceeded`       | 429  | `insufficient_quota` | 平台支出已达到上限。请联系平台管理员。                              |
| `LZ-3601` | `pricing_not_configured`         | 503  | `api_error`          | 这个模型在所选线路上还没有定价，暂时无法使用。请换用其他模型。                  |

### LZ-4xxx · 模型与线路

| 编号        | Code                         | HTTP | 类型                               | 含义与处理                                              |
| --------- | ---------------------------- | ---- | -------------------------------- | -------------------------------------------------- |
| `LZ-4001` | `model_not_found`            | 404  | `not_found_error`                | 模型目录里没有这个模型。请检查模型名称。                               |
| `LZ-4002` | `model_not_allowed`          | 403  | `permission_error`               | 这把 API Key 不能使用所请求的模型。请检查 Key 的模型范围。               |
| `LZ-4003` | `token_vendor_denied`        | 403  | `permission_error`               | 这把 API Key 不能使用这个供应商的模型。请检查 Key 的供应商范围。            |
| `LZ-4101` | `no_available_channel`       | 503  | `overloaded_error`               | 暂时没有线路能服务这个模型。请稍后再试，或换用其他模型。                       |
| `LZ-4102` | `invalid_channel_id`         | 400  | `invalid_request_error`          | 指定的渠道编号无效。                                         |
| `LZ-4103` | `channel_disabled`           | 403  | `permission_error`               | 指定的渠道已停用。                                          |
| `LZ-4104` | `channel_config_invalid`     | 503  | `api_error`                      | 这个模型暂时不可用，请求没有完成。请稍后再试。                            |
| `LZ-4105` | `channel_no_available_key`   | 503  | `overloaded_error`               | 这个模型暂时不可用，请求没有完成。请稍后再试。                            |
| `LZ-4106` | `preferred_lane_unavailable` | 503  | `overloaded_error`               | 这个模型在 Key 固定的线路上不可用，且没有开启自动切换。请换用其他模型，或调整 Key 的线路。 |
| `LZ-4301` | `prompt_blocked`             | 400  | `content_policy_violation_error` | 模型按内容政策拒绝了这段内容。请修改后再试。                             |

### LZ-5xxx · 速率与容量

| 编号        | Code                                | HTTP | 类型                 | 含义与处理                                       |
| --------- | ----------------------------------- | ---- | ------------------ | ------------------------------------------- |
| `LZ-5001` | `token_rate_limit_exceeded`         | 429  | `rate_limit_error` | 这把 API Key 请求过于频繁。请按 Retry-After 提示的时间稍后再试。 |
| `LZ-5002` | `request_rate_limit_exceeded`       | 429  | `rate_limit_error` | 请求过于频繁。请稍后再试。                               |
| `LZ-5003` | `total_request_rate_limit_exceeded` | 429  | `rate_limit_error` | 请求总量超出限制。请稍后再试。                             |
| `LZ-5101` | `gateway_overloaded`                | 503  | `overloaded_error` | 网关暂时繁忙。请稍后再试。                               |
| `LZ-5201` | `upstream_rate_limited`             | 429  | `rate_limit_error` | 模型当前正在限流。请稍后再试。                             |
| `LZ-5301` | `too_many_attempts`                 | 429  | `rate_limit_error` | 操作过于频繁。请稍等片刻再试。                             |

### LZ-6xxx · 上游模型服务

| 编号        | Code                        | HTTP | 类型                     | 含义与处理                             |
| --------- | --------------------------- | ---- | ---------------------- | --------------------------------- |
| `LZ-6001` | `upstream_error`            | 502  | `api_error`            | 模型返回了错误。请稍后再试。                    |
| `LZ-6002` | `upstream_invalid_response` | 502  | `api_error`            | 模型返回的结果无法使用。请先确认是否已有结果，再决定是否重试。   |
| `LZ-6003` | `upstream_stream_failed`    | 502  | `api_error`            | 模型在输出过程中出错并中断。请先查看已输出的内容，再决定是否重试。 |
| `LZ-6101` | `upstream_timeout`          | 504  | `timeout_error`        | 模型响应超时，结果尚未确认。请先查看用量记录，再决定是否重发。   |
| `LZ-6201` | `upstream_network_error`    | 502  | `api_connection_error` | 连接模型失败。请稍后再试。                     |
| `LZ-6202` | `upstream_overloaded`       | 503  | `overloaded_error`     | 模型当前繁忙。请稍后再试。                     |
| `LZ-6301` | `upstream_auth_failed`      | 502  | `api_error`            | 这个模型暂时不可用，请求没有完成。请稍后再试。           |
| `LZ-6302` | `upstream_billing_failed`   | 502  | `api_error`            | 这个模型暂时不可用，请求没有完成。请稍后再试。           |

### LZ-7xxx · 控制台

| 编号        | Code                                     | HTTP | 类型                      | 含义与处理                                                  |
| --------- | ---------------------------------------- | ---- | ----------------------- | ------------------------------------------------------ |
| `LZ-7001` | `user_not_found`                         | 404  | `not_found_error`       | 找不到这个用户，可能已被删除。请刷新列表。                                  |
| `LZ-7002` | `user_exists`                            | 409  | `conflict_error`        | 用户名或邮箱已被注册，或属于已注销的账号。请换一个。                             |
| `LZ-7003` | `user_manage_forbidden`                  | 403  | `permission_error`      | 你不能管理与你同级或更高级别的账号。                                     |
| `LZ-7004` | `user_role_elevation_forbidden`          | 403  | `permission_error`      | 你不能把账号设为与你同级或更高的角色。                                    |
| `LZ-7005` | `root_user_protected`                    | 403  | `permission_error`      | 不能停用、删除或降级这个管理员：不能降级自己，也不能去掉最后一个管理员。                   |
| `LZ-7006` | `user_role_unchanged`                    | 409  | `conflict_error`        | 这个账号已经是该角色。                                            |
| `LZ-7007` | `balance_adjustment_reason_required`     | 400  | `invalid_request_error` | 请填写余额调整原因。                                             |
| `LZ-7008` | `balance_adjustment_amount_zero`         | 400  | `invalid_request_error` | 调整金额不能为 0。请输入正数或负数。                                    |
| `LZ-7009` | `username_invalid`                       | 400  | `invalid_request_error` | 用户名需为 2–20 个字符，只能包含字母、数字、下划线和短横线，且以字母或数字开头。            |
| `LZ-7010` | `username_unavailable`                   | 409  | `conflict_error`        | 这个用户名已被占用或为系统保留。请换一个。                                  |
| `LZ-7011` | `username_change_cooldown`               | 429  | `rate_limit_error`      | 用户名每 {{cooldown\_days}} 天只能修改一次。请到期后再改。                |
| `LZ-7012` | `identity_unlink_unavailable`            | 403  | `permission_error`      | 暂不支持解除已绑定的登录方式。                                        |
| `LZ-7101` | `topup_order_not_found`                  | 404  | `not_found_error`       | 没有找到这个交易号对应的充值订单。核对交易号后再试。                             |
| `LZ-7102` | `topup_order_not_pending`                | 409  | `conflict_error`        | 这笔充值订单已不是待支付状态，不能手动补单。刷新列表查看最新状态。                      |
| `LZ-7103` | `topup_method_unsupported`               | 400  | `invalid_request_error` | 只有 Stripe 充值订单可以手动补单。                                  |
| `LZ-7104` | `topup_credit_invalid`                   | 409  | `conflict_error`        | 这笔充值订单没有可入账的金额，不能补单。请在 Stripe 中核对订单。                   |
| `LZ-7105` | `topup_search_keyword_invalid`           | 400  | `invalid_request_error` | 搜索至少需要 2 个除 %、\_、! 以外的字符。请输入更长的订单号。                    |
| `LZ-7106` | `invalid_amount`                         | 400  | `invalid_request_error` | 充值金额必须是允许范围内的整数美元。调整金额后再试。                             |
| `LZ-7107` | `payment_not_found`                      | 404  | `not_found_error`       | 没有找到这笔付款，它可能属于其他账号。请检查链接。                              |
| `LZ-7108` | `invoice_unavailable`                    | 404  | `not_found_error`       | 这笔付款的发票或收据还没有准备好。几分钟后再试。                               |
| `LZ-7109` | `payment_provider_unavailable`           | 503  | `api_error`             | 支付服务暂时不可用。几分钟后再试。                                      |
| `LZ-7110` | `no_billing_customer`                    | 409  | `conflict_error`        | 这个项目还没有账单资料，首次付款时会自动创建。                                |
| `LZ-7111` | `wallet_ledger_range_invalid`            | 400  | `invalid_request_error` | 无法显示这个日期范围。请选择不超过 32 天的范围。                             |
| `LZ-7112` | `dispute_still_open`                     | 409  | `conflict_error`        | Stripe 尚未按这个结果关闭争议。等 Stripe 关闭后再记录结果。                  |
| `LZ-7113` | `dispute_resolution_failed`              | 409  | `conflict_error`        | 无法为这笔充值记录争议结果。核对充值单号和争议 ID。                            |
| `LZ-7114` | `payment_document_reconcile_failed`      | 503  | `api_error`             | 无法与 Stripe 核对这笔充值的发票和收据。稍后再试。                          |
| `LZ-7121` | `referral_unavailable`                   | 500  | `invalid_request_error` | 推荐记录暂时不可用，请稍后重试。                                       |
| `LZ-7122` | `referral_code_invalid`                  | 400  | `invalid_request_error` | 名字只能用 3–20 位小写字母、数字或连字符，不能以连字符开头或结尾。                   |
| `LZ-7123` | `referral_code_reserved`                 | 400  | `invalid_request_error` | 这个名字不能用，换一个试试。                                         |
| `LZ-7124` | `referral_code_taken`                    | 409  | `invalid_request_error` | 这个名字已经被别人用了。                                           |
| `LZ-7125` | `referral_code_limit`                    | 409  | `invalid_request_error` | 改名次数已经用完。                                              |
| `LZ-7126` | `promotion_unavailable`                  | 500  | `invalid_request_error` | 活动配置暂时不可用，请稍后重试。                                       |
| `LZ-7127` | `promotion_config_invalid`               | 400  | `invalid_request_error` | 请检查活动比例、金额上限和时间范围。                                     |
| `LZ-7128` | `referral_status_invalid`                | 400  | `invalid_request_error` | 推荐状态筛选条件无效。                                            |
| `LZ-7129` | `referral_search_invalid`                | 400  | `invalid_request_error` | 推荐记录搜索条件无效。                                            |
| `LZ-7130` | `referral_not_found`                     | 400  | `invalid_request_error` | 未找到这笔推荐奖励。                                             |
| `LZ-7131` | `referral_not_pending`                   | 409  | `invalid_request_error` | 这笔推荐奖励已不在待处理状态。                                        |
| `LZ-7201` | `key_name_too_long`                      | 400  | `invalid_request_error` | Key 名称过长，最多 {{max\_length}} 个字符。请缩短后再保存。               |
| `LZ-7202` | `key_enable_blocked`                     | 409  | `conflict_error`        | 这把 Key 已过期或额度已用完，暂时不能启用。请先延长有效期或调高额度。                  |
| `LZ-7203` | `key_limit_reached`                      | 409  | `conflict_error`        | 你在这个项目里已有 {{limit}} 把 Key，达到上限。请删除不再使用的 Key 后再新建。      |
| `LZ-7204` | `secret_unavailable`                     | 409  | `conflict_error`        | 这把 Key 只保存了摘要，无法显示完整密钥。如需完整密钥，请新建一把。                   |
| `LZ-7205` | `key_not_found`                          | 404  | `not_found_error`       | 找不到这把 Key，它可能已被删除。请刷新页面。                               |
| `LZ-7301` | `channel_not_found`                      | 404  | `not_found_error`       | 这个渠道已不存在，可能已被删除。请刷新列表。                                 |
| `LZ-7302` | `channel_search_backend_managed`         | 409  | `conflict_error`        | 这个渠道是检索后端，不能在这里修改。请到「检索后端」页面管理。                        |
| `LZ-7303` | `channel_lane_invalid`                   | 400  | `invalid_request_error` | 档位「{{lane}}」不存在。每个渠道只属于一个已有档位，请从列表中选择。                 |
| `LZ-7304` | `channel_settings_invalid`               | 400  | `invalid_request_error` | 渠道额外设置无法解析，没有保存。请检查 JSON 格式和取值。                        |
| `LZ-7305` | `channel_model_name_too_long`            | 400  | `invalid_request_error` | 有模型名称超过 255 个字符，渠道没有保存。请缩短或删除它。                        |
| `LZ-7306` | `channel_not_multi_key`                  | 409  | `conflict_error`        | 这个渠道只有一个密钥，不能逐个管理密钥。                                   |
| `LZ-7307` | `channel_key_index_invalid`              | 400  | `invalid_request_error` | 这个密钥已不在渠道里。请刷新密钥列表后再试。                                 |
| `LZ-7308` | `channel_last_key`                       | 409  | `conflict_error`        | 这是渠道的最后一个密钥，不能删除。请先添加其他密钥，或直接删除渠道。                     |
| `LZ-7309` | `channel_keys_none_eligible`             | 409  | `conflict_error`        | 没有符合这个操作的密钥，渠道没有变化。                                    |
| `LZ-7310` | `channel_balance_unsupported`            | 400  | `invalid_request_error` | 这类渠道或多密钥渠道不支持查询余额。                                     |
| `LZ-7311` | `channel_balance_query_failed`           | 502  | `api_error`             | 上游没有返回余额。请检查渠道密钥和地址后再试。                                |
| `LZ-7312` | `channel_upstream_models_failed`         | 502  | `api_error`             | 上游没有返回模型列表。请检查密钥和地址，或手动填写模型。                           |
| `LZ-7313` | `channel_task_running`                   | 409  | `conflict_error`        | 同类维护任务正在运行，这次没有启动。请等它完成后再试。                            |
| `LZ-7314` | `channel_test_failed`                    | 502  | `api_error`             | 渠道测试没有通过，上游返回了错误。请检查密钥、地址和测试模型后再测一次。                   |
| `LZ-7315` | `channel_test_not_sent`                  | 422  | `invalid_request_error` | 无法为这个渠道构造测试请求，没有发往上游。请检查渠道类型、模型映射和定价。                  |
| `LZ-7316` | `channel_route_not_found`                | 404  | `not_found_error`       | 这个渠道没有在该档位下服务这个模型。请刷新页面查看最新线路。                         |
| `LZ-7317` | `route_observation_incomplete`           | 409  | `conflict_error`        | 这个来源还在观察期。满 7 天且各项检查都通过后才能上线。                          |
| `LZ-7318` | `route_observation_none`                 | 404  | `not_found_error`       | 这个来源没有观察中的模型。请刷新页面查看最新状态。                              |
| `LZ-7401` | `setting_invalid`                        | 400  | `invalid_request_error` | 有一项设置的值不符合要求，这次没有保存。请检查它的格式和取值后再保存。                    |
| `LZ-7402` | `content_limit_exceeded`                 | 400  | `invalid_request_error` | 这个列表最多只能有 {{limit}} 项。请删掉一些后再保存。                       |
| `LZ-7403` | `announcement_not_found`                 | 404  | `not_found_error`       | 这条公告已不存在。请刷新列表。                                        |
| `LZ-7404` | `email_test_failed`                      | 502  | `api_error`             | 测试邮件没有发出。请检查 SMTP 设置；邮件服务器的回复已记入服务端日志。                 |
| `LZ-7405` | `email_test_recipient_missing`           | 400  | `invalid_request_error` | 你的账号还没有邮箱，测试邮件无处可发。请先为账号绑定邮箱。                          |
| `LZ-7406` | `email_recipients_required`              | 400  | `invalid_request_error` | 还没有选择收件人，邮件没有发出。请选择用户，或选择发送给全部用户。                      |
| `LZ-7407` | `announcement_email_content_missing`     | 400  | `invalid_request_error` | 没有可以发送的公告。请填写标题和内容，或先发布一条公告。                           |
| `LZ-7408` | `translation_token_missing`              | 400  | `invalid_request_error` | 翻译需要用你自己的 API Key 调用模型，但你名下没有可用的 Key。请新建或启用一把 Key 后再试。 |
| `LZ-7409` | `feedback_request_not_found`             | 404  | `not_found_error`       | 你的账号下没有这个请求编号。请检查请求编号。                                 |
| `LZ-7410` | `database_unreachable`                   | 503  | `api_error`             | 服务器连不上数据库。请检查数据库服务后再试。                                 |
| `LZ-7411` | `email_domain_not_allowed`               | 400  | `invalid_request_error` | 这个邮箱域名不在允许范围内。请换用允许域名下的邮箱。                             |
| `LZ-7412` | `email_alias_not_allowed`                | 400  | `invalid_request_error` | 不接受 @ 前带有「+」或「.」的邮箱地址。请使用不带别名的邮箱。                      |
| `LZ-7413` | `password_invalid`                       | 400  | `invalid_request_error` | 密码需为 8 到 64 个字符，且不超过 72 字节。请换一个密码。                     |
| `LZ-7414` | `password_reset_link_invalid`            | 400  | `invalid_request_error` | 重置链接无效或已过期。请重新申请一封重置邮件。                                |
| `LZ-7415` | `password_reset_client_upgrade_required` | 400  | `invalid_request_error` | 页面版本过旧，重置链接尚未使用。请刷新页面后重新设置密码。                          |
| `LZ-7421` | `mail_not_found`                         | 404  | `invalid_request_error` | 未找到归档邮件。                                               |
| `LZ-7422` | `mail_resend_failed`                     | 400  | `invalid_request_error` | 归档邮件重发失败，请查看投递详情。                                      |
| `LZ-7423` | `admin_email_missing`                    | 400  | `invalid_request_error` | 发送预览前，请先为账户添加邮箱。                                       |
| `LZ-7424` | `mail_regenerate_failed`                 | 400  | `invalid_request_error` | 邮件重新生成失败；草稿请从用量回顾页面重新生成。                               |
| `LZ-7425` | `digest_settings_invalid`                | 400  | `invalid_request_error` | 用量回顾设置无效。                                              |
| `LZ-7426` | `mail_send_failed`                       | 400  | `invalid_request_error` | 邮件发送失败，请查看投递详情。                                        |
| `LZ-7501` | `model_name_taken`                       | 409  | `conflict_error`        | 已有名为 {{model}} 的模型。请换一个名称，或直接编辑已有模型。                   |
| `LZ-7502` | `vendor_name_taken`                      | 409  | `conflict_error`        | 已有名为 {{vendor}} 的供应商。请换一个名称，或直接编辑已有供应商。                |
| `LZ-7503` | `prefill_group_name_taken`               | 409  | `conflict_error`        | 已有名为 {{name}} 的预填组。请换一个名称。                             |
| `LZ-7504` | `model_sync_not_configured`              | 503  | `api_error`             | 这台服务器没有配置模型元数据同步。请在服务器环境变量中设置元数据地址后重启。                 |
| `LZ-7505` | `model_sync_source_unavailable`          | 502  | `api_error`             | 无法读取 {{source}} 模型目录，这次没有同步任何内容。请稍后再试。                 |
| `LZ-7510` | `lane_not_found`                         | 404  | `not_found_error`       | 档位 {{lane}} 不存在。请刷新查看当前档位。                             |
| `LZ-7511` | `lane_builtin_locked`                    | 409  | `conflict_error`        | 档位 {{lane}} 是内置档位，不能停用或删除。                             |
| `LZ-7512` | `lane_ever_enabled`                      | 409  | `conflict_error`        | 档位 {{lane}} 曾经承载过流量，不能删除。请改为停用。                        |
| `LZ-7513` | `lane_has_no_sources`                    | 409  | `conflict_error`        | 档位 {{lane}} 还没有来源，启用后发往它的请求都会失败。请先在来源页把来源挪进来。          |
| `LZ-7514` | `lane_in_use`                            | 409  | `conflict_error`        | 档位 {{lane}} 仍有来源、价格或折扣记录。请先移走这些记录再删除。                  |
| `LZ-7520` | `tier_not_found`                         | 404  | `not_found_error`       | 等级 {{tier}} 不存在。请刷新查看当前等级。                             |
| `LZ-7521` | `tier_exists`                            | 409  | `conflict_error`        | 已有名为 {{tier}} 的等级。请换一个名称，或直接编辑该等级。                     |
| `LZ-7522` | `tier_builtin_locked`                    | 409  | `conflict_error`        | 等级 {{tier}} 是内置等级，不能删除。                                |
| `LZ-7523` | `tier_has_accounts`                      | 409  | `conflict_error`        | 等级 {{tier}} 里还有账号。请先在用户页把他们挪到别的等级，再删除。                 |
| `LZ-7530` | `sell_price_missing`                     | 400  | `invalid_request_error` | 没有填写售价。请至少填写一项价格再保存。                                   |
| `LZ-7531` | `sell_price_model_listed`                | 409  | `conflict_error`        | {{model}} 还在上架中，不能删除它的价格。请先下架。                         |
| `LZ-7532` | `sell_price_model_served`                | 409  | `conflict_error`        | 还有启用的渠道在提供 {{model}}，删掉价格后它的请求会被拒绝。请先停用这些渠道。           |
| `LZ-7533` | `sell_price_model_discounted`            | 409  | `conflict_error`        | {{model}} 还挂着生效中的折扣。请先撤掉折扣再删除价格。                       |
| `LZ-7534` | `model_listing_unpriced`                 | 409  | `conflict_error`        | 以下模型在任何档位都没有售价，上架会按 $0 计费：{{models}}。请先设置售价。           |
| `LZ-7535` | `model_listing_no_source`                | 409  | `conflict_error`        | 以下模型在档位 {{lane}} 上没有已启用的来源：{{models}}。请先添加来源再上架。       |
| `LZ-7601` | `feature_unavailable`                    | 403  | `permission_error`      | 当前账号还没有开通团队项目。                                         |
| `LZ-7602` | `project_context_mismatch`               | 400  | `invalid_request_error` | 页面上的项目与请求中的项目不一致。请刷新页面。                                |
| `LZ-7603` | `project_not_found`                      | 404  | `not_found_error`       | 找不到这个项目，或你已不是成员。                                       |
| `LZ-7604` | `project_member_not_found`               | 404  | `not_found_error`       | 这个人不是项目成员。刷新成员列表后再试。                                   |
| `LZ-7605` | `invite_not_found`                       | 404  | `not_found_error`       | 这个邀请链接无效。请对方重新发送邀请。                                    |
| `LZ-7606` | `budget_request_not_found`               | 404  | `not_found_error`       | 这条预算申请已不存在。刷新列表查看最新状态。                                 |
| `LZ-7607` | `undo_expired`                           | 409  | `conflict_error`        | 10 分钟的撤销时间已过。需要重新邀请。                                   |
| `LZ-7608` | `invalid_budget`                         | 400  | `invalid_request_error` | 预算必须是 0 或更大的金额，留空表示不限。检查金额后再保存。                        |
| `LZ-7609` | `invalid_effort_cap`                     | 400  | `invalid_request_error` | 这个推理强度上限不是可选档位。请从列表中选择。                                |
| `LZ-7610` | `invalid_settings`                       | 400  | `invalid_request_error` | 有一项项目设置的值无效。检查设置后再保存。                                  |
| `LZ-7611` | `cannot_edit_own_budget`                 | 403  | `permission_error`      | 不能改自己的预算。请另一位管理员修改。                                    |
| `LZ-7612` | `cannot_change_owner`                    | 403  | `permission_error`      | 所有者的角色和状态不能改。                                          |
| `LZ-7613` | `confirm_mismatch`                       | 400  | `invalid_request_error` | 项目名不匹配。请按显示的名称原样输入。                                    |
| `LZ-7614` | `resend_too_soon`                        | 429  | `rate_limit_error`      | 邀请刚发过。等一分钟再重发。                                         |
| `LZ-7615` | `request_pending`                        | 409  | `conflict_error`        | 已经有一个预算申请在等处理。等它处理完，或先撤回。                              |
| `LZ-7616` | `invalid_pagination`                     | 400  | `invalid_request_error` | 无法显示这一页列表。刷新页面后再试。                                     |
| `LZ-7617` | `already_member`                         | 409  | `conflict_error`        | 这个人已经是成员。                                              |
| `LZ-7618` | `already_invited`                        | 409  | `conflict_error`        | 这个邮箱已经有待接受的邀请。可以重发那封邀请。                                |
| `LZ-7619` | `invite_expired`                         | 409  | `conflict_error`        | 邀请已过期。请对方重新发送邀请。                                       |
| `LZ-7620` | `invite_revoked`                         | 409  | `conflict_error`        | 邀请已被撤回。如仍需加入，请对方重新邀请。                                  |
| `LZ-7621` | `invite_email_mismatch`                  | 403  | `permission_error`      | 这封邀请发给的不是你登录的邮箱。请用收到邀请的邮箱登录后再接受。                       |
| `LZ-7622` | `invite_email_unverified`                | 403  | `permission_error`      | 先验证你的邮箱，再接受邀请。                                         |
| `LZ-7623` | `invitee_feature_unavailable`            | 403  | `permission_error`      | 对方的账号暂时无法加入项目。可以换一个邮箱，或稍后再试。                           |
| `LZ-7624` | `invite_email_invalid`                   | 400  | `invalid_request_error` | 邮箱格式不对。检查后再试。                                          |
| `LZ-7625` | `invite_role_invalid`                    | 400  | `invalid_request_error` | 角色只能选管理员或成员。                                           |
| `LZ-7626` | `project_name_invalid`                   | 400  | `invalid_request_error` | 项目名不能为空，且不超过 191 个字符。                                  |
| `LZ-7627` | `project_deletion_dependency`            | 409  | `conflict_error`        | 这个账号仍拥有或加入了团队项目，项目中的成员、付款或 Key 依赖它。先处理这些项目，再删除账号。      |
| `LZ-7701` | `usage_range_invalid`                    | 400  | `invalid_request_error` | 时间范围的结束早于开始。请调整时间范围后再试。                                |
| `LZ-7702` | `usage_range_too_long`                   | 400  | `invalid_request_error` | 时间范围超过了 {{max\_days}} 天。请缩短时间范围。                       |
| `LZ-7703` | `invalid_usage_summary_window`           | 400  | `invalid_request_error` | 用量汇总的时间窗口无效。请检查 since、until 和 granularity 参数。          |
| `LZ-7704` | `request_not_found`                      | 404  | `not_found_error`       | 这把 Key 下没有找到这个请求。请检查请求 ID。                             |
| `LZ-7705` | `log_session_not_found`                  | 404  | `not_found_error`       | 在你可查看的日志里找不到这个会话。请刷新页面。                                |
| `LZ-7706` | `usage_export_format_unsupported`        | 400  | `invalid_request_error` | 不支持这种导出格式。请导出为 CSV 或 XLSX。                             |
| `LZ-7707` | `log_cleanup_cutoff_too_recent`          | 400  | `invalid_request_error` | 最近 {{min\_days}} 天的日志要用于模型排行，不能清理。请选择更早的截止日期。          |
| `LZ-7708` | `spend_budget_not_found`                 | 404  | `not_found_error`       | 找不到这条支出预算，它可能已被删除。请刷新页面。                               |
| `LZ-7801` | `purpose_not_supported`                  | 400  | `invalid_request_error` | 不支持这个文件用途。请以 user\_data 或 vision 上传。                   |
| `LZ-7802` | `invalid_file`                           | 400  | `invalid_request_error` | 文件没有被接受。请检查文件类型和内容后重新上传。                               |
| `LZ-7803` | `file_too_large`                         | 413  | `invalid_request_error` | 文件超出了大小上限。请上传更小的文件。                                    |
| `LZ-7804` | `file_not_found`                         | 404  | `not_found_error`       | 找不到这个文件，或你无权访问。请检查文件 ID。                               |
| `LZ-7805` | `file_expired`                           | 400  | `invalid_request_error` | 这个文件已过期，不能再使用。请重新上传。                                   |
| `LZ-7806` | `file_dereference_failed`                | 502  | `api_error`             | 无法从存储读取文件，请求没有发出。请稍后再试。                                |
| `LZ-7807` | `file_storage_failed`                    | 502  | `api_error`             | 文件存储没有完成这次操作。请稍后再试。                                    |
| `LZ-7808` | `storage_not_configured`                 | 503  | `api_error`             | 本站尚未配置文件存储，暂时无法保存或读取文件。请联系管理员。                         |
| `LZ-7809` | `storage_quota_exceeded`                 | 429  | `insufficient_quota`    | 文件存储额度已用完。请删除不再需要的文件，或申请提高额度。                          |
| `LZ-7821` | `unsupported_media_kind`                 | 400  | `invalid_request_error` | 不支持这种媒体类型。请选择 image 或 video。                           |
| `LZ-7822` | `unsupported_media_status`               | 400  | `invalid_request_error` | 不支持这个状态筛选。请使用 pending、running、succeeded 或 failed。      |
| `LZ-7823` | `media_job_not_found`                    | 404  | `not_found_error`       | 找不到这个媒体任务。请检查任务 ID。                                    |
| `LZ-7824` | `artifact_file_not_found`                | 404  | `not_found_error`       | 找不到产物文件。请检查文件 ID，或重新上传。                                |
| `LZ-7825` | `video_not_found`                        | 404  | `not_found_error`       | 找不到这个视频任务。请检查任务 ID。                                    |
| `LZ-7826` | `invalid_studio_media_job`               | 400  | `invalid_request_error` | 请求中的 Studio 任务与本次请求不匹配。请从 Studio 重新发起生成。               |
| `LZ-7827` | `artifact_too_large`                     | 502  | `api_error`             | 生成的文件超出了可保存的大小，结果没有保留。请调小尺寸或缩短时长后再试。                   |
| `LZ-7828` | `video_artifact_missing`                 | 502  | `api_error`             | 视频已生成结束，但没有可下载的文件。请重新生成。                               |
| `LZ-7841` | `studio_disabled`                        | 404  | `not_found_error`       | 本站未开启 Studio。                                          |
| `LZ-7842` | `studio_generation_not_found`            | 404  | `not_found_error`       | 找不到这件作品，或你已无权查看。请刷新页面。                                 |
| `LZ-7843` | `studio_project_not_found`               | 404  | `not_found_error`       | 找不到这个 Studio 项目或画布条目，它可能已被删除。请刷新页面。                    |
| `LZ-7844` | `studio_artifact_not_found`              | 404  | `not_found_error`       | 这件作品的文件已丢失或过期。请重新生成。                                   |
| `LZ-7845` | `studio_artifact_unsupported`            | 415  | `invalid_request_error` | 这个文件不是支持的图片或视频。请选择 PNG、JPEG、GIF、WebP 或视频文件。            |
| `LZ-7846` | `studio_key_unavailable`                 | 400  | `invalid_request_error` | 所选 API Key 已停用或不存在。请换一把 Key。                           |
| `LZ-7847` | `studio_key_required`                    | 400  | `invalid_request_error` | 用账户余额生成只能在已登录的浏览器中进行。请改为选择一把 API Key。                  |
| `LZ-7848` | `studio_creator_not_found`               | 404  | `not_found_error`       | 没有找到这位创作者的公开作品。检查一下链接，或者去看看最新作品。                       |
| `LZ-7849` | `studio_sign_in_required`                | 401  | `authentication_error`  | 请先登录。搜索、下载原图和继续浏览需要账户。                                 |
| `LZ-7850` | `studio_download_limit_reached`          | 429  | `rate_limit_error`      | 今天的原图下载次数已用完，按你的时区零点重置；预览图仍可下载。                        |
| `LZ-7851` | `studio_free_unavailable`                | 409  | `conflict_error`        | 今天的免费生成不可用：可能已经用过，或账户还没有验证邮箱。                          |
| `LZ-7852` | `studio_not_favoritable`                 | 409  | `conflict_error`        | 只有已公开的作品可以收藏。                                          |
| `LZ-7853` | `studio_signature_invalid`               | 403  | `permission_error`      | 下载链接无效或已过期，请重新下载。                                      |
| `LZ-7861` | `search_backend_not_found`               | 404  | `not_found_error`       | 找不到这个搜索后端。请刷新列表。                                       |
| `LZ-7862` | `search_backend_provider_invalid`        | 400  | `invalid_request_error` | 不支持这个搜索服务商，或它与渠道类型不一致。请从列表中选择服务商。                      |
| `LZ-7863` | `poster_draft_not_found`                 | 404  | `not_found_error`       | 找不到这份海报草稿。请刷新列表。                                       |
| `LZ-7864` | `upload_file_not_found`                  | 404  | `not_found_error`       | 服务器上找不到这个数据文件。请检查文件路径。                                 |
| `LZ-7865` | `upload_key_not_allowed`                 | 400  | `invalid_request_error` | 这个路径不能上传。目录和配置文件不在上传范围内，请选择普通数据文件。                     |
| `LZ-7866` | `upload_failed`                          | 502  | `api_error`             | 对象存储没有接受这次上传。请检查存储配置后再试。                               |
| `LZ-7867` | `blog_validation_failed`                 | 400  | `invalid_request_error` | 博客请求无效：{reason\|请检查参数}。                                |
| `LZ-7868` | `blog_publish_blocked`                   | 422  | `invalid_request_error` | 文章未通过发布检查。                                             |

### LZ-9xxx · 内部错误

| 编号        | Code              | HTTP | 类型          | 含义与处理                          |
| --------- | ----------------- | ---- | ----------- | ------------------------------ |
| `LZ-9001` | `internal_error`  | 500  | `api_error` | 服务没能完成这个请求。如果反复出现，请带上请求编号联系支持。 |
| `LZ-9002` | `not_implemented` | 501  | `api_error` | 这个功能还没有开放。                     |

## 相关页面

- [请求频率限制](https://lazu.ai/docs/zh/limits)
- [鉴权](https://lazu.ai/docs/zh/authentication)
- [请求详情](https://lazu.ai/docs/zh/endpoints/usage-requests)

---

# 錯誤碼

Lazu 回傳的每個錯誤都有三個穩定識別：Lazu 錯誤編號（`LZ-3101`）、`code`（`insufficient_quota`）和 `type`（`insufficient_quota`）。HTTP 狀態碼一律是真實的，錯誤不會以 200 回傳。

## 回應結構

OpenAI 相容介面保留 OpenAI 的錯誤物件，Lazu 的欄位加在旁邊。只認得 OpenAI 欄位的 SDK 照常運作。

```json
{
  "error": {
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101",
    "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX",
    "details": {}
  }
}
```

Anthropic 相容介面（`/v1/messages`）使用 Anthropic 的結構與類型：

```json
{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101"
  },
  "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX"
}
```

| 欄位           | 含義                                              |
| ------------ | ----------------------------------------------- |
| `code`       | 發生了什麼。穩定，程式依它分支。                                |
| `type`       | 下一步該做什麼（見下表）。穩定。                                |
| `lazu`       | Lazu 錯誤編號。穩定，聯絡支援時提供它。                          |
| `message`    | 給開發者看的英文說明。可能調整，請勿解析。                           |
| `param`      | 出問題的請求欄位（如有）。                                   |
| `details`    | 結構化的值，例如 `field`、`model`、`retry_after_seconds`。 |
| `request_id` | 這個錯誤所屬的請求。                                      |
| `docs`       | 指向本頁對應編號的連結。                                    |

每個錯誤回應還帶有 `X-Lazu-Request-Id` 與 `X-Lazu-Error` 回應標頭。

## 錯誤類型

| 類型                               | HTTP    | 處理方式                               |
| -------------------------------- | ------- | ---------------------------------- |
| `invalid_request_error`          | 400、413 | 修正請求，原樣重試沒有用。                      |
| `authentication_error`           | 401     | 修正 API Key：無效、過期、停用各有自己的 code。     |
| `permission_error`               | 403     | Key 或帳號不允許這個操作：IP、模型、供應商或專案範圍。     |
| `not_found_error`                | 404     | 路徑、模型或 ID 不正確。                     |
| `insufficient_quota`             | 429     | 餘額或某項預算用完。儲值或調高預算，重試無效。            |
| `rate_limit_error`               | 429     | 等待 `Retry-After` 後再試。              |
| `content_policy_violation_error` | 400     | 模型拒絕了內容，需要修改內容。                    |
| `overloaded_error`               | 503     | 忙碌中，稍後退避重試。                        |
| `timeout_error`                  | 504     | 沒有及時回應，結果未知；重播前先確認。                |
| `api_connection_error`           | 502     | 連線中斷，結果未知；重播前先確認。                  |
| `api_error`                      | 500、502 | Lazu 或模型出錯。冪等請求可重試；持續出現請附請求編號聯絡支援。 |

在 `/v1/messages` 上，`insufficient_quota` 以 Anthropic 的 `billing_error` 回傳，`timeout_error` 與 `api_connection_error` 以 `api_error` 回傳。

## 重試策略

只在尚未收到輸出、且請求可安全重播時重試。429 要區分暫時限流與 `insufficient_quota`：餘額不足需要處理額度，不能靠重試解決。有 `Retry-After` 時遵循它；暫時性網關/上游故障採用有限次退避。執行狀態不明時，SDK 自動重試可能產生另一次呼叫，應明確設定。網關切換通道與客戶端重試是兩個決定。

## 串流回應

串流開始後 HTTP 狀態碼無法再變更。Lazu 會用協定自己的錯誤框結束串流，框內是同樣的錯誤物件（Chat Completions 為 `data: {"error": {...}}` 加 `data: [DONE]`，Responses 與 Messages 為 `error` 事件）。請保留已收到的部分輸出，重播前先查看請求詳情。遇到 413 `request_body_too_large` 請縮小請求；遇到 503 `gateway_overloaded` 請稍後退避重試。

## 提交支援工單

每個 Lazu 回應（成功或失敗）都帶有：

```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```

把它和 `LZ-` 編號一起貼進支援工單，我們可以追蹤完整的路由、上游呼叫與計費過程。

> 有些錯誤是 Lazu 這一側的問題，例如某條模型線路暫時故障。這類錯誤只回傳中性的「暫時無法使用」說明，具體原因記錄在請求編號下。

## 錯誤編號速查

### LZ-1xxx · 請求本身

| 編號        | Code                          | HTTP | 類型                      | 含義與處理                                 |
| --------- | ----------------------------- | ---- | ----------------------- | ------------------------------------- |
| `LZ-1001` | `invalid_request`             | 400  | `invalid_request_error` | 請求內容不正確。請檢查填寫的內容後再試。                  |
| `LZ-1002` | `bad_request_body`            | 400  | `invalid_request_error` | 請求本文格式不正確，模型沒有接受。請檢查請求參數。             |
| `LZ-1003` | `model_name_required`         | 400  | `invalid_request_error` | 請求中缺少模型名稱。請填寫 model 參數。               |
| `LZ-1004` | `request_body_too_large`      | 413  | `invalid_request_error` | 請求內容過大。請縮減內容或拆分後再傳送。                  |
| `LZ-1005` | `context_length_exceeded`     | 400  | `invalid_request_error` | 輸入超出了模型的上下文長度。請縮短對話，或改用上下文更長的模型。      |
| `LZ-1006` | `protocol_bridge_unsupported` | 400  | `invalid_request_error` | 目前線路無法把請求中的某項功能轉交給所選模型。請改用原生支援該功能的模型。 |
| `LZ-1007` | `capability_unsupported`      | 400  | `invalid_request_error` | 所選模型不支援這次請求用到的功能。請改用支援該功能的模型。         |
| `LZ-1008` | `convert_request_failed`      | 400  | `invalid_request_error` | 請求無法轉換成所選模型的格式。請檢查參數，或改用其他模型。         |
| `LZ-1009` | `missing_required_parameter`  | 400  | `invalid_request_error` | 請求缺少必填參數。請對照介面文件補齊。                   |
| `LZ-1010` | `endpoint_not_supported`      | 404  | `not_found_error`       | 不支援這個介面。請檢查請求網址。                      |
| `LZ-1011` | `tokenization_error`          | 500  | `api_error`             | 無法計算輸入的 token 數。請檢查輸入內容是否完整。          |
| `LZ-1012` | `resource_not_found`          | 404  | `not_found_error`       | 找不到要操作的內容，它可能已被刪除。請重新整理後再試。           |
| `LZ-1013` | `version_conflict`            | 409  | `conflict_error`        | 這筆記錄在你開啟後被修改過。請重新整理後重新操作。             |
| `LZ-1014` | `state_conflict`              | 409  | `conflict_error`        | 目前狀態下無法執行這個操作。請重新整理查看最新狀態。            |
| `LZ-1901` | `client_canceled`             | 499  | `api_connection_error`  | 請求已取消。                                |

### LZ-20xx · API Key

| 編號        | Code                          | HTTP | 類型                     | 含義與處理                                 |
| --------- | ----------------------------- | ---- | ---------------------- | ------------------------------------- |
| `LZ-2001` | `invalid_api_key`             | 401  | `authentication_error` | API Key 無效。請檢查 Key 是否複製完整，或在主控台新建一把。  |
| `LZ-2002` | `token_expired`               | 401  | `authentication_error` | 這把 API Key 已過期。請在主控台延長有效期限，或新建一把 Key。 |
| `LZ-2003` | `token_disabled`              | 401  | `authentication_error` | 這把 API Key 已停用。請在主控台啟用它，或改用其他 Key。    |
| `LZ-2004` | `ephemeral_credential_denied` | 403  | `permission_error`     | 這個臨時憑證不能用於本次請求。請只在簽發時限定的模型和介面上使用。     |
| `LZ-2005` | `proxy_signature_invalid`     | 401  | `authentication_error` | 無法確認請求來源。請稍後再試；如果持續出現，請聯絡支援。          |

### LZ-21xx · 主控台登入狀態

| 編號        | Code                    | HTTP | 類型                     | 含義與處理                    |
| --------- | ----------------------- | ---- | ---------------------- | ------------------------ |
| `LZ-2101` | `session_required`      | 401  | `authentication_error` | 請先登入。                    |
| `LZ-2102` | `session_expired`       | 401  | `authentication_error` | 登入已過期，請重新登入。             |
| `LZ-2103` | `session_invalid`       | 401  | `authentication_error` | 登入狀態已失效，請重新登入。           |
| `LZ-2104` | `session_user_mismatch` | 401  | `authentication_error` | 目前頁面屬於另一個已登入的帳號。請重新整理頁面。 |
| `LZ-2105` | `access_token_invalid`  | 401  | `authentication_error` | 存取權杖無效。請在個人設定中重新產生。      |

### LZ-22xx · 登入與註冊

| 編號        | Code                                   | HTTP | 類型                      | 含義與處理                               |
| --------- | -------------------------------------- | ---- | ----------------------- | ----------------------------------- |
| `LZ-2201` | `password_login_disabled`              | 403  | `permission_error`      | 密碼登入已關閉。請改用其他登入方式。                  |
| `LZ-2202` | `invalid_credentials`                  | 401  | `authentication_error`  | 使用者名稱或密碼錯誤，或帳號已停用。請檢查後再試。           |
| `LZ-2203` | `registration_closed`                  | 403  | `permission_error`      | 目前不開放註冊新帳號。如需帳號，請聯絡管理員。             |
| `LZ-2204` | `password_registration_disabled`       | 403  | `permission_error`      | 已關閉密碼註冊。請用電子郵件驗證碼或第三方帳號註冊。          |
| `LZ-2205` | `email_verification_required`          | 400  | `invalid_request_error` | 註冊需要驗證電子郵件。請填寫電子郵件地址和驗證碼。           |
| `LZ-2206` | `verification_code_invalid`            | 400  | `invalid_request_error` | 驗證碼錯誤或已過期。請檢查，或重新取得。                |
| `LZ-2207` | `verification_code_attempts_exhausted` | 429  | `rate_limit_error`      | 驗證碼錯誤次數過多，已失效。請重新取得驗證碼。             |
| `LZ-2210` | `email_code_auth_disabled`             | 403  | `permission_error`      | 電子郵件驗證碼登入已關閉。請改用其他登入方式。             |
| `LZ-2211` | `email_transport_unavailable`          | 503  | `api_error`             | 暫時無法寄送電子郵件驗證碼。請改用其他登入方式。            |
| `LZ-2215` | `original_password_incorrect`          | 400  | `invalid_request_error` | 目前的密碼不正確。請檢查後再試。                    |
| `LZ-2216` | `oauth_provider_not_configured`        | 404  | `not_found_error`       | 這個登入方式暫時無法使用。請改用其他方式。               |
| `LZ-2217` | `oauth_cancelled`                      | 400  | `invalid_request_error` | 你取消了授權，登入沒有完成。                      |
| `LZ-2218` | `oauth_provider_error`                 | 502  | `api_error`             | 登入服務商回傳了錯誤。請稍後再試。                   |
| `LZ-2219` | `oauth_state_invalid`                  | 400  | `invalid_request_error` | 這次登入已失效。請重新登入。                      |
| `LZ-2220` | `oauth_exchange_failed`                | 502  | `api_error`             | 沒能與登入服務商完成登入。請稍後再試。                 |
| `LZ-2221` | `oauth_identity_invalid`               | 401  | `authentication_error`  | 無法驗證你在登入服務商的身分。請稍後再試。               |
| `LZ-2222` | `oauth_login_failed`                   | 500  | `api_error`             | 登入沒有完成。請稍後再試。                       |
| `LZ-2223` | `oauth_email_unverified`               | 403  | `permission_error`      | 這個帳號沒有已驗證的電子郵件。請先在對應平台驗證電子郵件，再重新登入。 |
| `LZ-2224` | `oauth_email_conflict`                 | 409  | `conflict_error`        | 這個電子郵件對應多個帳號。請聯絡管理員處理。              |
| `LZ-2225` | `oauth_identity_conflict`              | 409  | `conflict_error`        | 這個第三方帳號已綁定其他使用者。請用那個使用者登入。          |

### LZ-23xx · 存取權限

| 編號        | Code                       | HTTP | 類型                 | 含義與處理                                       |
| --------- | -------------------------- | ---- | ------------------ | ------------------------------------------- |
| `LZ-2301` | `access_denied`            | 403  | `permission_error` | 你沒有執行這個操作的權限。如需開通，請聯絡管理員。                   |
| `LZ-2302` | `ip_not_allowed`           | 403  | `permission_error` | 這把 API Key 不接受來自你目前 IP 的請求。請檢查 Key 的 IP 限制。 |
| `LZ-2303` | `user_banned`              | 403  | `permission_error` | 這個帳號已被停用。如有疑問，請聯絡管理員。                       |
| `LZ-2304` | `group_access_denied`      | 403  | `permission_error` | 目前帳號不能使用所請求的線路。請改用其他線路。                     |
| `LZ-2305` | `channel_selection_denied` | 403  | `permission_error` | 只有管理員可以把請求指定到某個管道。                          |
| `LZ-2306` | `project_access_suspended` | 403  | `permission_error` | 你在這個專案的存取已暫停。請聯絡專案管理員。                      |
| `LZ-2307` | `address_not_enabled`      | 403  | `permission_error` | 你的帳戶沒有開通這個接入位址。請換回預設位址。                     |

### LZ-26xx · 判別模型

| 編號        | Code                             | HTTP | 類型                      | 含義與處理                      |
| --------- | -------------------------------- | ---- | ----------------------- | -------------------------- |
| `LZ-2601` | `missing_questions`              | 400  | `invalid_request_error` | 請提供 questions，或開啟自動生成判別問題。 |
| `LZ-2602` | `invalid_decision_state`         | 400  | `invalid_request_error` | 請提供文字或 JSON 材料，或嵌入圖片。      |
| `LZ-2603` | `invalid_decision_questions`     | 400  | `invalid_request_error` | 判別問題格式不正確。                 |
| `LZ-2604` | `unsupported_question_type`      | 400  | `invalid_request_error` | 暫不支援這種問題類型。                |
| `LZ-2605` | `unsupported_decision_input`     | 400  | `invalid_request_error` | 該判別模型不支援這種輸入。              |
| `LZ-2606` | `unsupported_decision_parameter` | 400  | `invalid_request_error` | 暫不支援這個參數。判別介面不支援串流輸出。      |
| `LZ-2607` | `question_generation_failed`     | 502  | `api_error`             | 生成的問題未通過驗證，生成費用將退回。        |
| `LZ-2608` | `upstream_decision_invalid`      | 502  | `api_error`             | 判別模型傳回的結果格式不正確。            |
| `LZ-2609` | `upstream_capacity`              | 429  | `rate_limit_error`      | 上游容量已滿，請按提示時間稍後重試。         |

### LZ-3xxx · 錢包與預算

| 編號        | Code                             | HTTP | 類型                   | 含義與處理                                             |
| --------- | -------------------------------- | ---- | -------------------- | ------------------------------------------------- |
| `LZ-3101` | `insufficient_quota`             | 429  | `insufficient_quota` | 錢包餘額不足，無法完成這次請求。請儲值後繼續。                           |
| `LZ-3201` | `key_budget_exceeded`            | 429  | `insufficient_quota` | 這把 API Key 的預算不足以涵蓋本次請求，請求沒有送出。請調高 Key 預算或降低輸出上限。 |
| `LZ-3202` | `pre_consume_token_quota_failed` | 429  | `insufficient_quota` | 這把 API Key 的剩餘額度不足以支應本次請求。請調高額度或改用其他 Key。         |
| `LZ-3301` | `member_budget_exceeded`         | 429  | `insufficient_quota` | 你本月的成員預算已用完。請聯絡專案管理員調整。                           |
| `LZ-3401` | `project_budget_exceeded`        | 429  | `insufficient_quota` | 專案預算已用完。請聯絡專案管理員調整。                               |
| `LZ-3501` | `platform_budget_exceeded`       | 429  | `insufficient_quota` | 平台支出已達上限。請聯絡平台管理員。                                |
| `LZ-3601` | `pricing_not_configured`         | 503  | `api_error`          | 這個模型在所選線路上還沒有定價，暫時無法使用。請改用其他模型。                   |

### LZ-4xxx · 模型與線路

| 編號        | Code                         | HTTP | 類型                               | 含義與處理                                               |
| --------- | ---------------------------- | ---- | -------------------------------- | --------------------------------------------------- |
| `LZ-4001` | `model_not_found`            | 404  | `not_found_error`                | 模型目錄裡沒有這個模型。請檢查模型名稱。                                |
| `LZ-4002` | `model_not_allowed`          | 403  | `permission_error`               | 這把 API Key 不能使用所請求的模型。請檢查 Key 的模型範圍。                |
| `LZ-4003` | `token_vendor_denied`        | 403  | `permission_error`               | 這把 API Key 不能使用這個供應商的模型。請檢查 Key 的供應商範圍。             |
| `LZ-4101` | `no_available_channel`       | 503  | `overloaded_error`               | 暫時沒有線路能服務這個模型。請稍後再試，或改用其他模型。                        |
| `LZ-4102` | `invalid_channel_id`         | 400  | `invalid_request_error`          | 指定的管道編號無效。                                          |
| `LZ-4103` | `channel_disabled`           | 403  | `permission_error`               | 指定的管道已停用。                                           |
| `LZ-4104` | `channel_config_invalid`     | 503  | `api_error`                      | 這個模型暫時無法使用，請求沒有完成。請稍後再試。                            |
| `LZ-4105` | `channel_no_available_key`   | 503  | `overloaded_error`               | 這個模型暫時無法使用，請求沒有完成。請稍後再試。                            |
| `LZ-4106` | `preferred_lane_unavailable` | 503  | `overloaded_error`               | 這個模型在 Key 固定的線路上無法使用，且沒有開啟自動切換。請改用其他模型，或調整 Key 的線路。 |
| `LZ-4301` | `prompt_blocked`             | 400  | `content_policy_violation_error` | 模型依內容政策拒絕了這段內容。請修改後再試。                              |

### LZ-5xxx · 速率與容量

| 編號        | Code                                | HTTP | 類型                 | 含義與處理                                       |
| --------- | ----------------------------------- | ---- | ------------------ | ------------------------------------------- |
| `LZ-5001` | `token_rate_limit_exceeded`         | 429  | `rate_limit_error` | 這把 API Key 請求過於頻繁。請依 Retry-After 提示的時間稍後再試。 |
| `LZ-5002` | `request_rate_limit_exceeded`       | 429  | `rate_limit_error` | 請求過於頻繁。請稍後再試。                               |
| `LZ-5003` | `total_request_rate_limit_exceeded` | 429  | `rate_limit_error` | 請求總量超出限制。請稍後再試。                             |
| `LZ-5101` | `gateway_overloaded`                | 503  | `overloaded_error` | 閘道暫時忙碌。請稍後再試。                               |
| `LZ-5201` | `upstream_rate_limited`             | 429  | `rate_limit_error` | 模型目前正在限流。請稍後再試。                             |
| `LZ-5301` | `too_many_attempts`                 | 429  | `rate_limit_error` | 操作過於頻繁。請稍等片刻再試。                             |

### LZ-6xxx · 上游模型服務

| 編號        | Code                        | HTTP | 類型                     | 含義與處理                             |
| --------- | --------------------------- | ---- | ---------------------- | --------------------------------- |
| `LZ-6001` | `upstream_error`            | 502  | `api_error`            | 模型回傳了錯誤。請稍後再試。                    |
| `LZ-6002` | `upstream_invalid_response` | 502  | `api_error`            | 模型回傳的結果無法使用。請先確認是否已有結果，再決定是否重試。   |
| `LZ-6003` | `upstream_stream_failed`    | 502  | `api_error`            | 模型在輸出過程中出錯並中斷。請先查看已輸出的內容，再決定是否重試。 |
| `LZ-6101` | `upstream_timeout`          | 504  | `timeout_error`        | 模型回應逾時，結果尚未確認。請先查看用量記錄，再決定是否重送。   |
| `LZ-6201` | `upstream_network_error`    | 502  | `api_connection_error` | 連線模型失敗。請稍後再試。                     |
| `LZ-6202` | `upstream_overloaded`       | 503  | `overloaded_error`     | 模型目前忙碌。請稍後再試。                     |
| `LZ-6301` | `upstream_auth_failed`      | 502  | `api_error`            | 這個模型暫時無法使用，請求沒有完成。請稍後再試。          |
| `LZ-6302` | `upstream_billing_failed`   | 502  | `api_error`            | 這個模型暫時無法使用，請求沒有完成。請稍後再試。          |

### LZ-7xxx · 主控台

| 編號        | Code                                     | HTTP | 類型                      | 含義與處理                                                  |
| --------- | ---------------------------------------- | ---- | ----------------------- | ------------------------------------------------------ |
| `LZ-7001` | `user_not_found`                         | 404  | `not_found_error`       | 找不到這個使用者，可能已被刪除。請重新整理列表。                               |
| `LZ-7002` | `user_exists`                            | 409  | `conflict_error`        | 使用者名稱或電子郵件已被註冊，或屬於已註銷的帳號。請換一個。                         |
| `LZ-7003` | `user_manage_forbidden`                  | 403  | `permission_error`      | 你不能管理與你同級或更高級別的帳號。                                     |
| `LZ-7004` | `user_role_elevation_forbidden`          | 403  | `permission_error`      | 你不能把帳號設為與你同級或更高的角色。                                    |
| `LZ-7005` | `root_user_protected`                    | 403  | `permission_error`      | 不能停用、刪除或降級這個管理員：不能降級自己，也不能去掉最後一個管理員。                   |
| `LZ-7006` | `user_role_unchanged`                    | 409  | `conflict_error`        | 這個帳號已經是該角色。                                            |
| `LZ-7007` | `balance_adjustment_reason_required`     | 400  | `invalid_request_error` | 請填寫餘額調整原因。                                             |
| `LZ-7008` | `balance_adjustment_amount_zero`         | 400  | `invalid_request_error` | 調整金額不能為 0。請輸入正數或負數。                                    |
| `LZ-7009` | `username_invalid`                       | 400  | `invalid_request_error` | 使用者名稱需為 2–20 個字元，只能包含字母、數字、底線和連字號，且以字母或數字開頭。           |
| `LZ-7010` | `username_unavailable`                   | 409  | `conflict_error`        | 這個使用者名稱已被使用或為系統保留。請換一個。                                |
| `LZ-7011` | `username_change_cooldown`               | 429  | `rate_limit_error`      | 使用者名稱每 {{cooldown\_days}} 天只能修改一次。請到期後再改。              |
| `LZ-7012` | `identity_unlink_unavailable`            | 403  | `permission_error`      | 暫不支援解除已綁定的登入方式。                                        |
| `LZ-7101` | `topup_order_not_found`                  | 404  | `not_found_error`       | 找不到這個交易編號對應的儲值訂單。確認交易編號後再試。                            |
| `LZ-7102` | `topup_order_not_pending`                | 409  | `conflict_error`        | 這筆儲值訂單已不是待付款狀態，無法手動補單。重新整理列表查看最新狀態。                    |
| `LZ-7103` | `topup_method_unsupported`               | 400  | `invalid_request_error` | 只有 Stripe 儲值訂單可以手動補單。                                  |
| `LZ-7104` | `topup_credit_invalid`                   | 409  | `conflict_error`        | 這筆儲值訂單沒有可入帳的金額，無法補單。請在 Stripe 中確認訂單。                   |
| `LZ-7105` | `topup_search_keyword_invalid`           | 400  | `invalid_request_error` | 搜尋至少需要 2 個 %、\_、! 以外的字元。請輸入更長的訂單編號。                    |
| `LZ-7106` | `invalid_amount`                         | 400  | `invalid_request_error` | 儲值金額必須是允許範圍內的整數美元。調整金額後再試。                             |
| `LZ-7107` | `payment_not_found`                      | 404  | `not_found_error`       | 找不到這筆付款，它可能屬於其他帳號。請檢查連結。                               |
| `LZ-7108` | `invoice_unavailable`                    | 404  | `not_found_error`       | 這筆付款的發票或收據尚未準備好。幾分鐘後再試。                                |
| `LZ-7109` | `payment_provider_unavailable`           | 503  | `api_error`             | 付款服務暫時無法使用。幾分鐘後再試。                                     |
| `LZ-7110` | `no_billing_customer`                    | 409  | `conflict_error`        | 這個專案還沒有帳單資料，首次付款時會自動建立。                                |
| `LZ-7111` | `wallet_ledger_range_invalid`            | 400  | `invalid_request_error` | 無法顯示這個日期範圍。請選擇不超過 32 天的範圍。                             |
| `LZ-7112` | `dispute_still_open`                     | 409  | `conflict_error`        | Stripe 尚未以這個結果結案。等 Stripe 結案後再記錄結果。                    |
| `LZ-7113` | `dispute_resolution_failed`              | 409  | `conflict_error`        | 無法為這筆儲值記錄爭議結果。請確認儲值單號與爭議 ID。                           |
| `LZ-7114` | `payment_document_reconcile_failed`      | 503  | `api_error`             | 無法與 Stripe 核對這筆儲值的發票與收據。稍後再試。                          |
| `LZ-7121` | `referral_unavailable`                   | 500  | `invalid_request_error` | 推薦記錄暫時不可用，請稍後重試。                                       |
| `LZ-7122` | `referral_code_invalid`                  | 400  | `invalid_request_error` | 名字只能用 3–20 位小寫字母、數字或連字號，不能以連字號開頭或結尾。                   |
| `LZ-7123` | `referral_code_reserved`                 | 400  | `invalid_request_error` | 這個名字不能用，換一個試試。                                         |
| `LZ-7124` | `referral_code_taken`                    | 409  | `invalid_request_error` | 這個名字已經被別人用了。                                           |
| `LZ-7125` | `referral_code_limit`                    | 409  | `invalid_request_error` | 改名次數已經用完。                                              |
| `LZ-7126` | `promotion_unavailable`                  | 500  | `invalid_request_error` | 活動設定暫時不可用，請稍後重試。                                       |
| `LZ-7127` | `promotion_config_invalid`               | 400  | `invalid_request_error` | 請檢查活動比例、金額上限和時間範圍。                                     |
| `LZ-7128` | `referral_status_invalid`                | 400  | `invalid_request_error` | 推薦狀態篩選條件無效。                                            |
| `LZ-7129` | `referral_search_invalid`                | 400  | `invalid_request_error` | 推薦記錄搜尋條件無效。                                            |
| `LZ-7130` | `referral_not_found`                     | 400  | `invalid_request_error` | 找不到這筆推薦獎勵。                                             |
| `LZ-7131` | `referral_not_pending`                   | 409  | `invalid_request_error` | 這筆推薦獎勵已不在待處理狀態。                                        |
| `LZ-7201` | `key_name_too_long`                      | 400  | `invalid_request_error` | Key 名稱過長，最多 {{max\_length}} 個字元。請縮短後再儲存。               |
| `LZ-7202` | `key_enable_blocked`                     | 409  | `conflict_error`        | 這把 Key 已過期或額度已用完，暫時無法啟用。請先延長有效期限或調高額度。                 |
| `LZ-7203` | `key_limit_reached`                      | 409  | `conflict_error`        | 你在這個專案裡已有 {{limit}} 把 Key，已達上限。請刪除不再使用的 Key 後再新增。      |
| `LZ-7204` | `secret_unavailable`                     | 409  | `conflict_error`        | 這把 Key 只保存了摘要，無法顯示完整金鑰。如需完整金鑰，請新增一把。                   |
| `LZ-7205` | `key_not_found`                          | 404  | `not_found_error`       | 找不到這把 Key，它可能已被刪除。請重新整理頁面。                             |
| `LZ-7301` | `channel_not_found`                      | 404  | `not_found_error`       | 這個渠道已不存在，可能已被刪除。請重新整理列表。                               |
| `LZ-7302` | `channel_search_backend_managed`         | 409  | `conflict_error`        | 這個渠道是檢索後端，不能在這裡修改。請到「檢索後端」頁面管理。                        |
| `LZ-7303` | `channel_lane_invalid`                   | 400  | `invalid_request_error` | 檔位「{{lane}}」不存在。每個渠道只屬於一個既有檔位，請從列表中選擇。                 |
| `LZ-7304` | `channel_settings_invalid`               | 400  | `invalid_request_error` | 渠道額外設定無法解析，沒有儲存。請檢查 JSON 格式和取值。                        |
| `LZ-7305` | `channel_model_name_too_long`            | 400  | `invalid_request_error` | 有模型名稱超過 255 個字元，渠道沒有儲存。請縮短或刪除它。                        |
| `LZ-7306` | `channel_not_multi_key`                  | 409  | `conflict_error`        | 這個渠道只有一個金鑰，不能逐一管理金鑰。                                   |
| `LZ-7307` | `channel_key_index_invalid`              | 400  | `invalid_request_error` | 這個金鑰已不在渠道中。請重新整理金鑰列表後再試。                               |
| `LZ-7308` | `channel_last_key`                       | 409  | `conflict_error`        | 這是渠道的最後一個金鑰，不能刪除。請先新增其他金鑰，或直接刪除渠道。                     |
| `LZ-7309` | `channel_keys_none_eligible`             | 409  | `conflict_error`        | 沒有符合這個操作的金鑰，渠道沒有變化。                                    |
| `LZ-7310` | `channel_balance_unsupported`            | 400  | `invalid_request_error` | 這類渠道或多金鑰渠道不支援查詢餘額。                                     |
| `LZ-7311` | `channel_balance_query_failed`           | 502  | `api_error`             | 上游沒有回傳餘額。請檢查渠道金鑰和位址後再試。                                |
| `LZ-7312` | `channel_upstream_models_failed`         | 502  | `api_error`             | 上游沒有回傳模型列表。請檢查金鑰和位址，或手動填寫模型。                           |
| `LZ-7313` | `channel_task_running`                   | 409  | `conflict_error`        | 同類維護工作正在執行，這次沒有啟動。請等它完成後再試。                            |
| `LZ-7314` | `channel_test_failed`                    | 502  | `api_error`             | 渠道測試沒有通過，上游回傳了錯誤。請檢查金鑰、位址和測試模型後再測一次。                   |
| `LZ-7315` | `channel_test_not_sent`                  | 422  | `invalid_request_error` | 無法為這個渠道建立測試請求，沒有送往上游。請檢查渠道類型、模型對應和定價。                  |
| `LZ-7316` | `channel_route_not_found`                | 404  | `not_found_error`       | 這個渠道沒有在該檔位下提供這個模型。請重新整理頁面查看最新線路。                       |
| `LZ-7317` | `route_observation_incomplete`           | 409  | `conflict_error`        | 這個來源還在觀察期。滿 7 天且各項檢查都通過後才能上線。                          |
| `LZ-7318` | `route_observation_none`                 | 404  | `not_found_error`       | 這個來源沒有觀察中的模型。請重新整理頁面查看最新狀態。                            |
| `LZ-7401` | `setting_invalid`                        | 400  | `invalid_request_error` | 有一項設定的值不符合要求，這次沒有儲存。請檢查它的格式和取值後再儲存。                    |
| `LZ-7402` | `content_limit_exceeded`                 | 400  | `invalid_request_error` | 這個清單最多只能有 {{limit}} 項。請刪掉一些後再儲存。                       |
| `LZ-7403` | `announcement_not_found`                 | 404  | `not_found_error`       | 這則公告已不存在。請重新整理清單。                                      |
| `LZ-7404` | `email_test_failed`                      | 502  | `api_error`             | 測試郵件沒有寄出。請檢查 SMTP 設定；郵件伺服器的回覆已記入伺服器日誌。                 |
| `LZ-7405` | `email_test_recipient_missing`           | 400  | `invalid_request_error` | 你的帳號還沒有電子郵件，測試郵件無處可寄。請先為帳號綁定電子郵件。                      |
| `LZ-7406` | `email_recipients_required`              | 400  | `invalid_request_error` | 還沒有選擇收件人，郵件沒有寄出。請選擇使用者，或選擇寄給全部使用者。                     |
| `LZ-7407` | `announcement_email_content_missing`     | 400  | `invalid_request_error` | 沒有可以寄送的公告。請填寫標題和內容，或先發布一則公告。                           |
| `LZ-7408` | `translation_token_missing`              | 400  | `invalid_request_error` | 翻譯需要用你自己的 API Key 呼叫模型，但你名下沒有可用的 Key。請新增或啟用一把 Key 後再試。 |
| `LZ-7409` | `feedback_request_not_found`             | 404  | `not_found_error`       | 你的帳號下沒有這個請求編號。請檢查請求編號。                                 |
| `LZ-7410` | `database_unreachable`                   | 503  | `api_error`             | 伺服器連不上資料庫。請檢查資料庫服務後再試。                                 |
| `LZ-7411` | `email_domain_not_allowed`               | 400  | `invalid_request_error` | 這個電子郵件網域不在允許範圍內。請改用允許網域下的電子郵件。                         |
| `LZ-7412` | `email_alias_not_allowed`                | 400  | `invalid_request_error` | 不接受 @ 前帶有「+」或「.」的電子郵件地址。請使用不帶別名的地址。                    |
| `LZ-7413` | `password_invalid`                       | 400  | `invalid_request_error` | 密碼需為 8 到 64 個字元，且不超過 72 位元組。請換一組密碼。                    |
| `LZ-7414` | `password_reset_link_invalid`            | 400  | `invalid_request_error` | 重設連結無效或已過期。請重新申請一封重設郵件。                                |
| `LZ-7415` | `password_reset_client_upgrade_required` | 400  | `invalid_request_error` | 頁面版本過舊，重設連結尚未使用。請重新整理頁面後重新設定密碼。                        |
| `LZ-7421` | `mail_not_found`                         | 404  | `invalid_request_error` | 找不到封存郵件。                                               |
| `LZ-7422` | `mail_resend_failed`                     | 400  | `invalid_request_error` | 封存郵件重發失敗，請查看投遞詳情。                                      |
| `LZ-7423` | `admin_email_missing`                    | 400  | `invalid_request_error` | 傳送預覽前，請先為帳戶新增電子郵件地址。                                   |
| `LZ-7424` | `mail_regenerate_failed`                 | 400  | `invalid_request_error` | 郵件重新產生失敗；草稿請從用量回顧頁面重新產生。                               |
| `LZ-7425` | `digest_settings_invalid`                | 400  | `invalid_request_error` | 用量回顧設定無效。                                              |
| `LZ-7426` | `mail_send_failed`                       | 400  | `invalid_request_error` | 郵件傳送失敗，請查看投遞詳情。                                        |
| `LZ-7501` | `model_name_taken`                       | 409  | `conflict_error`        | 已有名為 {{model}} 的模型。請換一個名稱，或直接編輯既有模型。                   |
| `LZ-7502` | `vendor_name_taken`                      | 409  | `conflict_error`        | 已有名為 {{vendor}} 的供應商。請換一個名稱，或直接編輯既有供應商。                |
| `LZ-7503` | `prefill_group_name_taken`               | 409  | `conflict_error`        | 已有名為 {{name}} 的預填組。請換一個名稱。                             |
| `LZ-7504` | `model_sync_not_configured`              | 503  | `api_error`             | 這台伺服器沒有設定模型中繼資料同步。請在伺服器環境變數中設定中繼資料位址後重新啟動。             |
| `LZ-7505` | `model_sync_source_unavailable`          | 502  | `api_error`             | 無法讀取 {{source}} 模型目錄，這次沒有同步任何內容。請稍後再試。                 |
| `LZ-7510` | `lane_not_found`                         | 404  | `not_found_error`       | 檔位 {{lane}} 不存在。請重新整理查看目前的檔位。                          |
| `LZ-7511` | `lane_builtin_locked`                    | 409  | `conflict_error`        | 檔位 {{lane}} 是內建檔位，不能停用或刪除。                             |
| `LZ-7512` | `lane_ever_enabled`                      | 409  | `conflict_error`        | 檔位 {{lane}} 曾經承載過流量，不能刪除。請改為停用。                        |
| `LZ-7513` | `lane_has_no_sources`                    | 409  | `conflict_error`        | 檔位 {{lane}} 還沒有來源，啟用後送往它的請求都會失敗。請先在來源頁把來源移進來。          |
| `LZ-7514` | `lane_in_use`                            | 409  | `conflict_error`        | 檔位 {{lane}} 仍有來源、價格或折扣紀錄。請先移除這些紀錄再刪除。                  |
| `LZ-7520` | `tier_not_found`                         | 404  | `not_found_error`       | 等級 {{tier}} 不存在。請重新整理查看目前的等級。                          |
| `LZ-7521` | `tier_exists`                            | 409  | `conflict_error`        | 已有名為 {{tier}} 的等級。請換一個名稱，或直接編輯該等級。                     |
| `LZ-7522` | `tier_builtin_locked`                    | 409  | `conflict_error`        | 等級 {{tier}} 是內建等級，不能刪除。                                |
| `LZ-7523` | `tier_has_accounts`                      | 409  | `conflict_error`        | 等級 {{tier}} 裡還有帳號。請先在使用者頁把他們移到其他等級，再刪除。                |
| `LZ-7530` | `sell_price_missing`                     | 400  | `invalid_request_error` | 沒有填寫售價。請至少填寫一項價格再儲存。                                   |
| `LZ-7531` | `sell_price_model_listed`                | 409  | `conflict_error`        | {{model}} 仍在上架中，不能刪除它的價格。請先下架。                         |
| `LZ-7532` | `sell_price_model_served`                | 409  | `conflict_error`        | 還有啟用的管道在提供 {{model}}，刪除價格後它的請求會被拒絕。請先停用這些管道。           |
| `LZ-7533` | `sell_price_model_discounted`            | 409  | `conflict_error`        | {{model}} 還有生效中的折扣。請先撤除折扣再刪除價格。                        |
| `LZ-7534` | `model_listing_unpriced`                 | 409  | `conflict_error`        | 以下模型在任何檔位都沒有售價，上架會以 $0 計費：{{models}}。請先設定售價。           |
| `LZ-7535` | `model_listing_no_source`                | 409  | `conflict_error`        | 以下模型在檔位 {{lane}} 上沒有已啟用的來源：{{models}}。請先新增來源再上架。       |
| `LZ-7601` | `feature_unavailable`                    | 403  | `permission_error`      | 目前帳號尚未開通團隊專案。                                          |
| `LZ-7602` | `project_context_mismatch`               | 400  | `invalid_request_error` | 頁面上的專案與請求中的專案不一致。請重新整理頁面。                              |
| `LZ-7603` | `project_not_found`                      | 404  | `not_found_error`       | 找不到這個專案，或你已不是成員。                                       |
| `LZ-7604` | `project_member_not_found`               | 404  | `not_found_error`       | 這個人不是專案成員。重新整理成員列表後再試。                                 |
| `LZ-7605` | `invite_not_found`                       | 404  | `not_found_error`       | 這個邀請連結無效。請對方重新寄送邀請。                                    |
| `LZ-7606` | `budget_request_not_found`               | 404  | `not_found_error`       | 這筆預算申請已不存在。重新整理列表查看最新狀態。                               |
| `LZ-7607` | `undo_expired`                           | 409  | `conflict_error`        | 10 分鐘的復原時間已過。需要重新邀請。                                   |
| `LZ-7608` | `invalid_budget`                         | 400  | `invalid_request_error` | 預算必須是 0 或更大的金額，留空表示不限。確認金額後再儲存。                        |
| `LZ-7609` | `invalid_effort_cap`                     | 400  | `invalid_request_error` | 這個推理強度上限不是可選的等級。請從列表中選擇。                               |
| `LZ-7610` | `invalid_settings`                       | 400  | `invalid_request_error` | 有一項專案設定的值無效。確認設定後再儲存。                                  |
| `LZ-7611` | `cannot_edit_own_budget`                 | 403  | `permission_error`      | 不能修改自己的預算。請另一位管理員修改。                                   |
| `LZ-7612` | `cannot_change_owner`                    | 403  | `permission_error`      | 所有者的角色和狀態不能修改。                                         |
| `LZ-7613` | `confirm_mismatch`                       | 400  | `invalid_request_error` | 專案名稱不符。請依顯示的名稱原樣輸入。                                    |
| `LZ-7614` | `resend_too_soon`                        | 429  | `rate_limit_error`      | 邀請剛寄出。等一分鐘再重寄。                                         |
| `LZ-7615` | `request_pending`                        | 409  | `conflict_error`        | 已經有一筆預算申請等待處理。等它處理完，或先撤回。                              |
| `LZ-7616` | `invalid_pagination`                     | 400  | `invalid_request_error` | 無法顯示這一頁列表。重新整理頁面後再試。                                   |
| `LZ-7617` | `already_member`                         | 409  | `conflict_error`        | 這個人已經是成員。                                              |
| `LZ-7618` | `already_invited`                        | 409  | `conflict_error`        | 這個電子郵件已經有待接受的邀請。可以重寄那封邀請。                              |
| `LZ-7619` | `invite_expired`                         | 409  | `conflict_error`        | 邀請已過期。請對方重新寄送邀請。                                       |
| `LZ-7620` | `invite_revoked`                         | 409  | `conflict_error`        | 邀請已被撤回。如仍需加入，請對方重新邀請。                                  |
| `LZ-7621` | `invite_email_mismatch`                  | 403  | `permission_error`      | 這封邀請寄給的不是你登入的電子郵件。請用收到邀請的信箱登入後再接受。                     |
| `LZ-7622` | `invite_email_unverified`                | 403  | `permission_error`      | 先驗證你的電子郵件，再接受邀請。                                       |
| `LZ-7623` | `invitee_feature_unavailable`            | 403  | `permission_error`      | 對方的帳號暫時無法加入專案。可以換一個信箱，或稍後再試。                           |
| `LZ-7624` | `invite_email_invalid`                   | 400  | `invalid_request_error` | 電子郵件格式不正確。確認後再試。                                       |
| `LZ-7625` | `invite_role_invalid`                    | 400  | `invalid_request_error` | 角色只能選管理員或成員。                                           |
| `LZ-7626` | `project_name_invalid`                   | 400  | `invalid_request_error` | 專案名稱不能空白，且不超過 191 個字元。                                 |
| `LZ-7627` | `project_deletion_dependency`            | 409  | `conflict_error`        | 這個帳號仍擁有或加入了團隊專案，專案中的成員、付款或 Key 依賴它。先處理這些專案，再刪除帳號。      |
| `LZ-7701` | `usage_range_invalid`                    | 400  | `invalid_request_error` | 時間範圍的結束早於開始。請調整時間範圍後再試。                                |
| `LZ-7702` | `usage_range_too_long`                   | 400  | `invalid_request_error` | 時間範圍超過了 {{max\_days}} 天。請縮短時間範圍。                       |
| `LZ-7703` | `invalid_usage_summary_window`           | 400  | `invalid_request_error` | 用量彙總的時間區間無效。請檢查 since、until 和 granularity 參數。          |
| `LZ-7704` | `request_not_found`                      | 404  | `not_found_error`       | 這把 Key 底下找不到這個請求。請檢查請求 ID。                             |
| `LZ-7705` | `log_session_not_found`                  | 404  | `not_found_error`       | 在你可檢視的日誌裡找不到這個工作階段。請重新整理頁面。                            |
| `LZ-7706` | `usage_export_format_unsupported`        | 400  | `invalid_request_error` | 不支援這種匯出格式。請匯出為 CSV 或 XLSX。                             |
| `LZ-7707` | `log_cleanup_cutoff_too_recent`          | 400  | `invalid_request_error` | 最近 {{min\_days}} 天的日誌要用於模型排行，無法清理。請選擇更早的截止日期。          |
| `LZ-7708` | `spend_budget_not_found`                 | 404  | `not_found_error`       | 找不到這筆支出預算，它可能已被刪除。請重新整理頁面。                             |
| `LZ-7801` | `purpose_not_supported`                  | 400  | `invalid_request_error` | 不支援這個檔案用途。請以 user\_data 或 vision 上傳。                   |
| `LZ-7802` | `invalid_file`                           | 400  | `invalid_request_error` | 檔案沒有被接受。請檢查檔案類型和內容後重新上傳。                               |
| `LZ-7803` | `file_too_large`                         | 413  | `invalid_request_error` | 檔案超出了大小上限。請上傳較小的檔案。                                    |
| `LZ-7804` | `file_not_found`                         | 404  | `not_found_error`       | 找不到這個檔案，或你沒有存取權限。請檢查檔案 ID。                             |
| `LZ-7805` | `file_expired`                           | 400  | `invalid_request_error` | 這個檔案已過期，無法再使用。請重新上傳。                                   |
| `LZ-7806` | `file_dereference_failed`                | 502  | `api_error`             | 無法從儲存空間讀取檔案，請求沒有送出。請稍後再試。                              |
| `LZ-7807` | `file_storage_failed`                    | 502  | `api_error`             | 檔案儲存沒有完成這次操作。請稍後再試。                                    |
| `LZ-7808` | `storage_not_configured`                 | 503  | `api_error`             | 本站尚未設定檔案儲存，暫時無法儲存或讀取檔案。請聯絡管理員。                         |
| `LZ-7809` | `storage_quota_exceeded`                 | 429  | `insufficient_quota`    | 檔案儲存額度已用完。請刪除不再需要的檔案，或申請提高額度。                          |
| `LZ-7821` | `unsupported_media_kind`                 | 400  | `invalid_request_error` | 不支援這種媒體類型。請選擇 image 或 video。                           |
| `LZ-7822` | `unsupported_media_status`               | 400  | `invalid_request_error` | 不支援這個狀態篩選。請使用 pending、running、succeeded 或 failed。      |
| `LZ-7823` | `media_job_not_found`                    | 404  | `not_found_error`       | 找不到這個媒體任務。請檢查任務 ID。                                    |
| `LZ-7824` | `artifact_file_not_found`                | 404  | `not_found_error`       | 找不到產出檔案。請檢查檔案 ID，或重新上傳。                                |
| `LZ-7825` | `video_not_found`                        | 404  | `not_found_error`       | 找不到這個影片任務。請檢查任務 ID。                                    |
| `LZ-7826` | `invalid_studio_media_job`               | 400  | `invalid_request_error` | 請求中的 Studio 任務與這次請求不符。請從 Studio 重新發起生成。                |
| `LZ-7827` | `artifact_too_large`                     | 502  | `api_error`             | 生成的檔案超出可儲存的大小，結果沒有保留。請調小尺寸或縮短長度後再試。                    |
| `LZ-7828` | `video_artifact_missing`                 | 502  | `api_error`             | 影片已生成結束，但沒有可下載的檔案。請重新生成。                               |
| `LZ-7841` | `studio_disabled`                        | 404  | `not_found_error`       | 本站未開啟 Studio。                                          |
| `LZ-7842` | `studio_generation_not_found`            | 404  | `not_found_error`       | 找不到這件作品，或你已無權檢視。請重新整理頁面。                               |
| `LZ-7843` | `studio_project_not_found`               | 404  | `not_found_error`       | 找不到這個 Studio 專案或畫布項目，它可能已被刪除。請重新整理頁面。                  |
| `LZ-7844` | `studio_artifact_not_found`              | 404  | `not_found_error`       | 這件作品的檔案已遺失或過期。請重新生成。                                   |
| `LZ-7845` | `studio_artifact_unsupported`            | 415  | `invalid_request_error` | 這個檔案不是支援的圖片或影片。請選擇 PNG、JPEG、GIF、WebP 或影片檔案。            |
| `LZ-7846` | `studio_key_unavailable`                 | 400  | `invalid_request_error` | 所選 API Key 已停用或不存在。請換一把 Key。                           |
| `LZ-7847` | `studio_key_required`                    | 400  | `invalid_request_error` | 使用帳號餘額生成只能在已登入的瀏覽器中進行。請改為選擇一把 API Key。                 |
| `LZ-7848` | `studio_creator_not_found`               | 404  | `not_found_error`       | 沒有找到這位創作者的公開作品。檢查一下連結，或者去看看最新作品。                       |
| `LZ-7849` | `studio_sign_in_required`                | 401  | `authentication_error`  | 請先登入。搜尋、下載原圖和繼續瀏覽需要帳戶。                                 |
| `LZ-7850` | `studio_download_limit_reached`          | 429  | `rate_limit_error`      | 今天的原圖下載次數已用完，依你的時區零點重設；預覽圖仍可下載。                        |
| `LZ-7851` | `studio_free_unavailable`                | 409  | `conflict_error`        | 今天的免費生成無法使用：可能已經用過，或帳戶尚未驗證電子郵件。                        |
| `LZ-7852` | `studio_not_favoritable`                 | 409  | `conflict_error`        | 只有已公開的作品可以收藏。                                          |
| `LZ-7853` | `studio_signature_invalid`               | 403  | `permission_error`      | 下載連結無效或已過期，請重新下載。                                      |
| `LZ-7861` | `search_backend_not_found`               | 404  | `not_found_error`       | 找不到這個搜尋後端。請重新整理列表。                                     |
| `LZ-7862` | `search_backend_provider_invalid`        | 400  | `invalid_request_error` | 不支援這個搜尋服務商，或它與渠道類型不一致。請從列表中選擇服務商。                      |
| `LZ-7863` | `poster_draft_not_found`                 | 404  | `not_found_error`       | 找不到這份海報草稿。請重新整理列表。                                     |
| `LZ-7864` | `upload_file_not_found`                  | 404  | `not_found_error`       | 伺服器上找不到這個資料檔案。請檢查檔案路徑。                                 |
| `LZ-7865` | `upload_key_not_allowed`                 | 400  | `invalid_request_error` | 這個路徑不能上傳。目錄和設定檔不在上傳範圍內，請選擇一般資料檔案。                      |
| `LZ-7866` | `upload_failed`                          | 502  | `api_error`             | 物件儲存沒有接受這次上傳。請檢查儲存設定後再試。                               |
| `LZ-7867` | `blog_validation_failed`                 | 400  | `invalid_request_error` | 部落格請求無效：{reason\|請檢查參數}。                               |
| `LZ-7868` | `blog_publish_blocked`                   | 422  | `invalid_request_error` | 文章未通過發布檢查。                                             |

### LZ-9xxx · 內部錯誤

| 編號        | Code              | HTTP | 類型          | 含義與處理                          |
| --------- | ----------------- | ---- | ----------- | ------------------------------ |
| `LZ-9001` | `internal_error`  | 500  | `api_error` | 服務沒能完成這個請求。如果反覆出現，請附上請求編號聯絡支援。 |
| `LZ-9002` | `not_implemented` | 501  | `api_error` | 這個功能尚未開放。                      |

## 相關頁面

- [請求頻率限制](https://lazu.ai/docs/zh-TW/limits)
- [認證](https://lazu.ai/docs/zh-TW/authentication)
- [請求詳情](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)

---

# エラーコード

Lazu が返すすべてのエラーには、3 つの安定した識別子があります。Lazu エラー番号（`LZ-3101`）、`code`（`insufficient_quota`）、`type`（`insufficient_quota`）です。HTTP ステータスは常に実際の値で、エラーが 200 で返ることはありません。

## レスポンスの形式

OpenAI 互換のルートは OpenAI のエラーオブジェクトをそのまま使い、その横に Lazu のフィールドを追加します。OpenAI のフィールドしか知らない SDK もそのまま動作します。

```json
{
  "error": {
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101",
    "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX",
    "details": {}
  }
}
```

Anthropic 互換のルート（`/v1/messages`）は Anthropic の形式とタイプを使います。

```json
{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Wallet balance is too low for this request. Top up to continue.",
    "code": "insufficient_quota",
    "lazu": "LZ-3101",
    "docs": "https://lazu.ai/docs/errors#lz-3101"
  },
  "request_id": "req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX"
}
```

| フィールド        | 意味                                                |
| ------------ | ------------------------------------------------- |
| `code`       | 何が起きたか。安定しており、分岐に使います。                            |
| `type`       | 次に何をすべきか（下表）。安定しています。                             |
| `lazu`       | Lazu エラー番号。安定しています。サポートへの問い合わせ時に伝えてください。          |
| `message`    | 開発者向けの英語の説明。変わることがあるため、解析しないでください。                |
| `param`      | 問題のあるリクエストのフィールド（ある場合）。                           |
| `details`    | `field`、`model`、`retry_after_seconds` などの構造化された値。 |
| `request_id` | このエラーが属するリクエスト。                                   |
| `docs`       | このページの該当番号へのリンク。                                  |

すべてのエラーレスポンスには `X-Lazu-Request-Id` と `X-Lazu-Error` ヘッダーも付きます。

## エラータイプ

| タイプ                              | HTTP    | 対処                                                         |
| -------------------------------- | ------- | ---------------------------------------------------------- |
| `invalid_request_error`          | 400、413 | リクエストを修正してください。そのまま再試行しても解決しません。                           |
| `authentication_error`           | 401     | API キーを修正してください。無効・期限切れ・無効化はそれぞれ別の code です。                |
| `permission_error`               | 403     | キーまたはアカウントにこの操作が許可されていません（IP、モデル、ベンダー、プロジェクトの範囲）。          |
| `not_found_error`                | 404     | パス、モデル、ID が正しくありません。                                       |
| `insufficient_quota`             | 429     | 残高または予算が尽きました。チャージするか予算を上げてください。再試行では解決しません。               |
| `rate_limit_error`               | 429     | `Retry-After` の時間を待ってから再試行してください。                          |
| `content_policy_violation_error` | 400     | モデルが内容を拒否しました。内容を変更してください。                                 |
| `overloaded_error`               | 503     | 混雑しています。バックオフして後で再試行してください。                                |
| `timeout_error`                  | 504     | 時間内に応答がなく、結果は不明です。再送前に確認してください。                            |
| `api_connection_error`           | 502     | 接続が切れ、結果は不明です。再送前に確認してください。                                |
| `api_error`                      | 500、502 | Lazu またはモデルが失敗しました。冪等なリクエストは再試行でき、続く場合はリクエスト ID を添えてサポートへ。 |

`/v1/messages` では、`insufficient_quota` は Anthropic の `billing_error` として、`timeout_error` と `api_connection_error` は `api_error` として返ります。

## retry 方針

出力をまだ受信しておらず、安全に再送できるリクエストだけを再試行してください。429 は一時的な制限と `insufficient_quota` を区別します。残高不足は再試行では解決しません。`Retry-After` があれば従い、一時障害には回数を制限したバックオフを使います。実行状態が不明な場合、SDK の自動再試行は別のモデル呼び出しになることがあります。ゲートウェイのフェイルオーバーとクライアントの再試行は別の判断です。

## ストリーム

ストリームが始まると HTTP ステータスは変更できません。Lazu はプロトコル固有のエラーフレームで、同じエラーオブジェクトを付けてストリームを終了します（Chat Completions は `data: {"error": {...}}` の後に `data: [DONE]`、Responses と Messages は `error` イベント）。途中までの出力を保持し、再送前にリクエスト詳細を確認してください。413 `request_body_too_large` はリクエストを小さくし、503 `gateway_overloaded` はバックオフして後で再試行してください。

## サポートへの問い合わせ

Lazu のすべてのレスポンス（成功・失敗とも）には次が含まれます。

```http
X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX
```

`LZ-` 番号と一緒にサポートチケットへ貼り付けてください。ルーティング、上流呼び出し、課金までの経路を追跡できます。

> Lazu 側の問題（一時的に壊れたモデルルートなど）を表すエラーは、中立的な「一時的に利用できません」という説明だけを返します。原因はリクエスト ID に記録されます。

## エラー番号一覧

### LZ-1xxx · リクエスト

| 番号        | Code                          | HTTP | タイプ                     | 意味と対処                                                         |
| --------- | ----------------------------- | ---- | ----------------------- | ------------------------------------------------------------- |
| `LZ-1001` | `invalid_request`             | 400  | `invalid_request_error` | リクエストの内容が正しくありません。入力内容を確認してもう一度お試しください。                       |
| `LZ-1002` | `bad_request_body`            | 400  | `invalid_request_error` | リクエスト本文の形式が正しくないため、モデルが受け付けませんでした。リクエストのパラメーターを確認してください。      |
| `LZ-1003` | `model_name_required`         | 400  | `invalid_request_error` | リクエストにモデル名がありません。model パラメーターを指定してください。                       |
| `LZ-1004` | `request_body_too_large`      | 413  | `invalid_request_error` | リクエストが大きすぎます。内容を減らすか、分割して送信してください。                            |
| `LZ-1005` | `context_length_exceeded`     | 400  | `invalid_request_error` | 入力がこのモデルのコンテキスト長を超えています。会話を短くするか、より長いコンテキストのモデルを選んでください。      |
| `LZ-1006` | `protocol_bridge_unsupported` | 400  | `invalid_request_error` | このルートでは、リクエストに含まれる機能を選択したモデルへ渡せません。その機能にネイティブ対応したモデルを選んでください。 |
| `LZ-1007` | `capability_unsupported`      | 400  | `invalid_request_error` | 選択したモデルは、このリクエストで使われている機能に対応していません。対応するモデルを選んでください。           |
| `LZ-1008` | `convert_request_failed`      | 400  | `invalid_request_error` | リクエストを選択したモデルの形式に変換できませんでした。パラメーターを確認するか、別のモデルを選んでください。       |
| `LZ-1009` | `missing_required_parameter`  | 400  | `invalid_request_error` | 必須パラメーターが不足しています。エンドポイントのリファレンスを確認して追加してください。                 |
| `LZ-1010` | `endpoint_not_supported`      | 404  | `not_found_error`       | このエンドポイントには対応していません。リクエスト URL を確認してください。                      |
| `LZ-1011` | `tokenization_error`          | 500  | `api_error`             | 入力のトークン数を数えられませんでした。入力内容が欠けていないか確認してください。                     |
| `LZ-1012` | `resource_not_found`          | 404  | `not_found_error`       | 対象が見つかりません。削除された可能性があります。再読み込みしてもう一度お試しください。                  |
| `LZ-1013` | `version_conflict`            | 409  | `conflict_error`        | このレコードは開いた後に変更されています。再読み込みしてからもう一度操作してください。                   |
| `LZ-1014` | `state_conflict`              | 409  | `conflict_error`        | 現在の状態ではこの操作を実行できません。再読み込みして最新の状態を確認してください。                    |
| `LZ-1901` | `client_canceled`             | 499  | `api_connection_error`  | リクエストはキャンセルされました。                                             |

### LZ-20xx · API キー

| 番号        | Code                          | HTTP | タイプ                    | 意味と対処                                                      |
| --------- | ----------------------------- | ---- | ---------------------- | ---------------------------------------------------------- |
| `LZ-2001` | `invalid_api_key`             | 401  | `authentication_error` | API キーが無効です。キーが最後までコピーされているか確認するか、コンソールで新しいキーを作成してください。    |
| `LZ-2002` | `token_expired`               | 401  | `authentication_error` | この API キーは有効期限が切れています。コンソールで有効期限を延長するか、新しいキーを作成してください。     |
| `LZ-2003` | `token_disabled`              | 401  | `authentication_error` | この API キーは無効化されています。コンソールで有効にするか、別のキーを使ってください。             |
| `LZ-2004` | `ephemeral_credential_denied` | 403  | `permission_error`     | この一時認証情報はこのリクエストには使えません。発行時に指定されたモデルとエンドポイントでのみ使用してください。   |
| `LZ-2005` | `proxy_signature_invalid`     | 401  | `authentication_error` | リクエストの送信元を確認できませんでした。しばらくしてからお試しください。続く場合はサポートにお問い合わせください。 |

### LZ-21xx · コンソールのセッション

| 番号        | Code                    | HTTP | タイプ                    | 意味と対処                                     |
| --------- | ----------------------- | ---- | ---------------------- | ----------------------------------------- |
| `LZ-2101` | `session_required`      | 401  | `authentication_error` | 続けるにはサインインしてください。                         |
| `LZ-2102` | `session_expired`       | 401  | `authentication_error` | セッションの有効期限が切れました。もう一度サインインしてください。         |
| `LZ-2103` | `session_invalid`       | 401  | `authentication_error` | セッションが無効になりました。もう一度サインインしてください。           |
| `LZ-2104` | `session_user_mismatch` | 401  | `authentication_error` | このページは別のサインイン中アカウントのものです。ページを再読み込みしてください。 |
| `LZ-2105` | `access_token_invalid`  | 401  | `authentication_error` | アクセストークンが無効です。設定で新しいアクセストークンを生成してください。    |

### LZ-22xx · サインインと登録

| 番号        | Code                                   | HTTP | タイプ                     | 意味と対処                                                       |
| --------- | -------------------------------------- | ---- | ----------------------- | ----------------------------------------------------------- |
| `LZ-2201` | `password_login_disabled`              | 403  | `permission_error`      | パスワードでのログインは無効になっています。別のログイン方法をご利用ください。                     |
| `LZ-2202` | `invalid_credentials`                  | 401  | `authentication_error`  | ユーザー名またはパスワードが正しくないか、アカウントが無効になっています。確認してもう一度お試しください。       |
| `LZ-2203` | `registration_closed`                  | 403  | `permission_error`      | 現在、新規アカウントの登録は受け付けていません。アカウントが必要な場合は管理者にお問い合わせください。         |
| `LZ-2204` | `password_registration_disabled`       | 403  | `permission_error`      | パスワードでの登録は無効になっています。メール認証コードまたは外部アカウントで登録してください。            |
| `LZ-2205` | `email_verification_required`          | 400  | `invalid_request_error` | 登録にはメールアドレスの確認が必要です。メールアドレスと認証コードを入力してください。                 |
| `LZ-2206` | `verification_code_invalid`            | 400  | `invalid_request_error` | 認証コードが正しくないか、有効期限が切れています。確認するか、新しいコードを取得してください。             |
| `LZ-2207` | `verification_code_attempts_exhausted` | 429  | `rate_limit_error`      | 誤入力が多すぎたため、このコードは無効になりました。新しいコードを取得してください。                  |
| `LZ-2210` | `email_code_auth_disabled`             | 403  | `permission_error`      | メール認証コードでのログインは無効になっています。別のログイン方法をご利用ください。                  |
| `LZ-2211` | `email_transport_unavailable`          | 503  | `api_error`             | 現在、メール認証コードを送信できません。別のログイン方法をご利用ください。                       |
| `LZ-2215` | `original_password_incorrect`          | 400  | `invalid_request_error` | 現在のパスワードが正しくありません。確認してもう一度お試しください。                          |
| `LZ-2216` | `oauth_provider_not_configured`        | 404  | `not_found_error`       | このログイン方法は現在利用できません。別の方法をご利用ください。                            |
| `LZ-2217` | `oauth_cancelled`                      | 400  | `invalid_request_error` | 認可がキャンセルされたため、ログインは完了していません。                                |
| `LZ-2218` | `oauth_provider_error`                 | 502  | `api_error`             | ログインプロバイダーがエラーを返しました。しばらくしてからもう一度お試しください。                   |
| `LZ-2219` | `oauth_state_invalid`                  | 400  | `invalid_request_error` | このログインは有効期限が切れました。もう一度ログインを始めてください。                         |
| `LZ-2220` | `oauth_exchange_failed`                | 502  | `api_error`             | ログインプロバイダーとのログインを完了できませんでした。しばらくしてからもう一度お試しください。            |
| `LZ-2221` | `oauth_identity_invalid`               | 401  | `authentication_error`  | ログインプロバイダーから受け取った本人情報を確認できませんでした。しばらくしてからもう一度お試しください。       |
| `LZ-2222` | `oauth_login_failed`                   | 500  | `api_error`             | ログインが完了しませんでした。しばらくしてからもう一度お試しください。                         |
| `LZ-2223` | `oauth_email_unverified`               | 403  | `permission_error`      | このアカウントには確認済みのメールアドレスがありません。プロバイダー側でメールを確認してから、もう一度お試しください。 |
| `LZ-2224` | `oauth_email_conflict`                 | 409  | `conflict_error`        | このメールアドレスは複数のアカウントに該当します。管理者にお問い合わせください。                    |
| `LZ-2225` | `oauth_identity_conflict`              | 409  | `conflict_error`        | この外部アカウントは別のユーザーに連携済みです。そのユーザーでログインしてください。                  |

### LZ-23xx · アクセス

| 番号        | Code                       | HTTP | タイプ                | 意味と対処                                                     |
| --------- | -------------------------- | ---- | ------------------ | --------------------------------------------------------- |
| `LZ-2301` | `access_denied`            | 403  | `permission_error` | この操作を行う権限がありません。管理者にアクセス権を依頼してください。                       |
| `LZ-2302` | `ip_not_allowed`           | 403  | `permission_error` | この API キーは現在の IP アドレスからのリクエストを受け付けません。キーの IP 制限を確認してください。 |
| `LZ-2303` | `user_banned`              | 403  | `permission_error` | このアカウントは無効化されています。ご不明な点は管理者にお問い合わせください。                   |
| `LZ-2304` | `group_access_denied`      | 403  | `permission_error` | このアカウントでは指定されたレーンを利用できません。別のレーンを選んでください。                  |
| `LZ-2305` | `channel_selection_denied` | 403  | `permission_error` | 特定のチャネルにリクエストを固定できるのは管理者だけです。                             |
| `LZ-2306` | `project_access_suspended` | 403  | `permission_error` | このプロジェクトへのアクセスは停止されています。プロジェクト管理者に連絡してください。               |
| `LZ-2307` | `address_not_enabled`      | 403  | `permission_error` | この API アドレスはお使いのアカウントで有効になっていません。既定のアドレスに戻してください。         |

### LZ-26xx · 判別モデル

| 番号        | Code                             | HTTP | タイプ                     | 意味と対処                               |
| --------- | -------------------------------- | ---- | ----------------------- | ----------------------------------- |
| `LZ-2601` | `missing_questions`              | 400  | `invalid_request_error` | questions を指定するか、質問の自動生成を有効にしてください。 |
| `LZ-2602` | `invalid_decision_state`         | 400  | `invalid_request_error` | テキスト、JSON、または埋め込み画像を指定してください。       |
| `LZ-2603` | `invalid_decision_questions`     | 400  | `invalid_request_error` | 判定の質問形式が正しくありません。                   |
| `LZ-2604` | `unsupported_question_type`      | 400  | `invalid_request_error` | この質問形式には対応していません。                   |
| `LZ-2605` | `unsupported_decision_input`     | 400  | `invalid_request_error` | この判定モデルは入力形式に対応していません。              |
| `LZ-2606` | `unsupported_decision_parameter` | 400  | `invalid_request_error` | このパラメーターには対応していません。判定はストリーミングできません。 |
| `LZ-2607` | `question_generation_failed`     | 502  | `api_error`             | 生成された質問の検証に失敗しました。生成料金は返金されます。      |
| `LZ-2608` | `upstream_decision_invalid`      | 502  | `api_error`             | 判定モデルの応答形式が正しくありません。                |
| `LZ-2609` | `upstream_capacity`              | 429  | `rate_limit_error`      | 上流の処理容量に達しました。指定時間後に再試行してください。      |

### LZ-3xxx · ウォレットと予算

| 番号        | Code                             | HTTP | タイプ                  | 意味と対処                                                            |
| --------- | -------------------------------- | ---- | -------------------- | ---------------------------------------------------------------- |
| `LZ-3101` | `insufficient_quota`             | 429  | `insufficient_quota` | ウォレットの残高が不足しているため、このリクエストを実行できません。チャージしてから続けてください。               |
| `LZ-3201` | `key_budget_exceeded`            | 429  | `insufficient_quota` | この API キーの予算ではリクエストをまかなえないため、送信されませんでした。キーの予算を上げるか、出力上限を下げてください。 |
| `LZ-3202` | `pre_consume_token_quota_failed` | 429  | `insufficient_quota` | この API キーの残り利用枠ではリクエストをまかなえません。利用枠を増やすか、別のキーを使ってください。            |
| `LZ-3301` | `member_budget_exceeded`         | 429  | `insufficient_quota` | 今月のメンバー予算を使い切りました。プロジェクト管理者に調整を依頼してください。                         |
| `LZ-3401` | `project_budget_exceeded`        | 429  | `insufficient_quota` | プロジェクトの予算を使い切りました。プロジェクト管理者に調整を依頼してください。                         |
| `LZ-3501` | `platform_budget_exceeded`       | 429  | `insufficient_quota` | プラットフォームの支出上限に達しました。プラットフォーム管理者に連絡してください。                        |
| `LZ-3601` | `pricing_not_configured`         | 503  | `api_error`          | このモデルは選択したレーンでまだ価格が設定されていないため、利用できません。別のモデルを選んでください。             |

### LZ-4xxx · モデルとルート

| 番号        | Code                         | HTTP | タイプ                              | 意味と対処                                                                |
| --------- | ---------------------------- | ---- | -------------------------------- | -------------------------------------------------------------------- |
| `LZ-4001` | `model_not_found`            | 404  | `not_found_error`                | このモデルはモデルカタログにありません。モデル名を確認してください。                                   |
| `LZ-4002` | `model_not_allowed`          | 403  | `permission_error`               | この API キーでは指定したモデルを利用できません。キーのモデル範囲を確認してください。                        |
| `LZ-4003` | `token_vendor_denied`        | 403  | `permission_error`               | この API キーではこのベンダーのモデルを利用できません。キーのベンダー範囲を確認してください。                    |
| `LZ-4101` | `no_available_channel`       | 503  | `overloaded_error`               | 現在このモデルを提供できるルートがありません。しばらくしてからお試しいただくか、別のモデルを選んでください。               |
| `LZ-4102` | `invalid_channel_id`         | 400  | `invalid_request_error`          | 指定されたチャネル ID が無効です。                                                  |
| `LZ-4103` | `channel_disabled`           | 403  | `permission_error`               | 指定されたチャネルは無効化されています。                                                 |
| `LZ-4104` | `channel_config_invalid`     | 503  | `api_error`                      | このモデルは一時的に利用できず、リクエストは完了しませんでした。しばらくしてからお試しください。                     |
| `LZ-4105` | `channel_no_available_key`   | 503  | `overloaded_error`               | このモデルは一時的に利用できず、リクエストは完了しませんでした。しばらくしてからお試しください。                     |
| `LZ-4106` | `preferred_lane_unavailable` | 503  | `overloaded_error`               | このモデルは API キーに固定されたレーンでは利用できず、自動切り替えもオフです。別のモデルを選ぶか、キーのレーンを変更してください。 |
| `LZ-4301` | `prompt_blocked`             | 400  | `content_policy_violation_error` | モデルがコンテンツポリシーによりこの内容を拒否しました。内容を修正してからお試しください。                        |

### LZ-5xxx · レートと容量

| 番号        | Code                                | HTTP | タイプ                | 意味と対処                                                 |
| --------- | ----------------------------------- | ---- | ------------------ | ----------------------------------------------------- |
| `LZ-5001` | `token_rate_limit_exceeded`         | 429  | `rate_limit_error` | この API キーからのリクエストが多すぎます。Retry-After の時間を待ってからお試しください。 |
| `LZ-5002` | `request_rate_limit_exceeded`       | 429  | `rate_limit_error` | リクエストが多すぎます。少し待ってからお試しください。                           |
| `LZ-5003` | `total_request_rate_limit_exceeded` | 429  | `rate_limit_error` | リクエストの総数が上限に達しました。少し待ってからお試しください。                     |
| `LZ-5101` | `gateway_overloaded`                | 503  | `overloaded_error` | ゲートウェイが混み合っています。少し待ってからお試しください。                       |
| `LZ-5201` | `upstream_rate_limited`             | 429  | `rate_limit_error` | このモデルは現在リクエストを制限しています。少し待ってからお試しください。                 |
| `LZ-5301` | `too_many_attempts`                 | 429  | `rate_limit_error` | 試行回数が多すぎます。少し待ってからお試しください。                            |

### LZ-6xxx · 上流プロバイダー

| 番号        | Code                        | HTTP | タイプ                    | 意味と対処                                            |
| --------- | --------------------------- | ---- | ---------------------- | ------------------------------------------------ |
| `LZ-6001` | `upstream_error`            | 502  | `api_error`            | モデルがエラーを返しました。しばらくしてからお試しください。                   |
| `LZ-6002` | `upstream_invalid_response` | 502  | `api_error`            | モデルの応答を利用できませんでした。結果が生成されていないか確認してから再試行してください。   |
| `LZ-6003` | `upstream_stream_failed`    | 502  | `api_error`            | モデルがストリーミング中にエラーで停止しました。途中までの出力を確認してから再試行してください。 |
| `LZ-6101` | `upstream_timeout`          | 504  | `timeout_error`        | モデルの応答がタイムアウトしたため、結果は未確認です。再送する前に利用ログを確認してください。  |
| `LZ-6201` | `upstream_network_error`    | 502  | `api_connection_error` | モデルへの接続に失敗しました。少し待ってからお試しください。                   |
| `LZ-6202` | `upstream_overloaded`       | 503  | `overloaded_error`     | モデルが混み合っています。少し待ってからお試しください。                     |
| `LZ-6301` | `upstream_auth_failed`      | 502  | `api_error`            | このモデルは一時的に利用できず、リクエストは完了しませんでした。しばらくしてからお試しください。 |
| `LZ-6302` | `upstream_billing_failed`   | 502  | `api_error`            | このモデルは一時的に利用できず、リクエストは完了しませんでした。しばらくしてからお試しください。 |

### LZ-7xxx · コンソール

| 番号        | Code                                     | HTTP | タイプ                     | 意味と対処                                                                             |
| --------- | ---------------------------------------- | ---- | ----------------------- | --------------------------------------------------------------------------------- |
| `LZ-7001` | `user_not_found`                         | 404  | `not_found_error`       | ユーザーが見つかりません。削除された可能性があります。一覧を更新してください。                                           |
| `LZ-7002` | `user_exists`                            | 409  | `conflict_error`        | このユーザー名またはメールアドレスは登録済みか、削除済みのアカウントで使われていました。別のものを指定してください。                        |
| `LZ-7003` | `user_manage_forbidden`                  | 403  | `permission_error`      | 自分と同じかそれより上の権限を持つアカウントは管理できません。                                                   |
| `LZ-7004` | `user_role_elevation_forbidden`          | 403  | `permission_error`      | アカウントに自分と同じかそれより上のロールを付与することはできません。                                               |
| `LZ-7005` | `root_user_protected`                    | 403  | `permission_error`      | この管理者は無効化・削除・降格できません。自分自身や最後の管理者は降格できません。                                         |
| `LZ-7006` | `user_role_unchanged`                    | 409  | `conflict_error`        | このアカウントはすでにそのロールです。                                                               |
| `LZ-7007` | `balance_adjustment_reason_required`     | 400  | `invalid_request_error` | 残高調整の理由を入力してください。                                                                 |
| `LZ-7008` | `balance_adjustment_amount_zero`         | 400  | `invalid_request_error` | 調整額を 0 にすることはできません。正または負の金額を入力してください。                                             |
| `LZ-7009` | `username_invalid`                       | 400  | `invalid_request_error` | ユーザー名は 2〜20 文字で、英数字・アンダースコア・ハイフンのみ使用でき、英数字で始める必要があります。                            |
| `LZ-7010` | `username_unavailable`                   | 409  | `conflict_error`        | このユーザー名は使用中か予約済みです。別の名前を指定してください。                                                 |
| `LZ-7011` | `username_change_cooldown`               | 429  | `rate_limit_error`      | ユーザー名は {{cooldown\_days}} 日に 1 回だけ変更できます。期間が過ぎてから変更してください。                        |
| `LZ-7012` | `identity_unlink_unavailable`            | 403  | `permission_error`      | 連携済みのログイン方法はまだ解除できません。                                                            |
| `LZ-7101` | `topup_order_not_found`                  | 404  | `not_found_error`       | この取引番号のチャージ注文は見つかりません。番号を確認してもう一度お試しください。                                         |
| `LZ-7102` | `topup_order_not_pending`                | 409  | `conflict_error`        | このチャージ注文は支払い待ちではないため、手動で完了できません。一覧を更新して状態を確認してください。                               |
| `LZ-7103` | `topup_method_unsupported`               | 400  | `invalid_request_error` | 手動で完了できるのは Stripe のチャージ注文のみです。                                                    |
| `LZ-7104` | `topup_credit_invalid`                   | 409  | `conflict_error`        | このチャージ注文には入金できる金額がないため、完了できません。Stripe で注文を確認してください。                               |
| `LZ-7105` | `topup_search_keyword_invalid`           | 400  | `invalid_request_error` | 検索には %、\_、! 以外の文字が 2 文字以上必要です。より長い注文番号を入力してください。                                  |
| `LZ-7106` | `invalid_amount`                         | 400  | `invalid_request_error` | チャージ金額は許可された範囲内の整数ドルで指定してください。金額を変更してもう一度お試しください。                                 |
| `LZ-7107` | `payment_not_found`                      | 404  | `not_found_error`       | この支払いは見つかりません。別のアカウントのものである可能性があります。リンクを確認してください。                                 |
| `LZ-7108` | `invoice_unavailable`                    | 404  | `not_found_error`       | この支払いの請求書または領収書はまだ用意できていません。数分後にもう一度お試しください。                                      |
| `LZ-7109` | `payment_provider_unavailable`           | 503  | `api_error`             | 決済サービスは一時的に利用できません。数分後にもう一度お試しください。                                               |
| `LZ-7110` | `no_billing_customer`                    | 409  | `conflict_error`        | このプロジェクトにはまだ請求先情報がありません。初回の支払い時に作成されます。                                           |
| `LZ-7111` | `wallet_ledger_range_invalid`            | 400  | `invalid_request_error` | この期間は表示できません。32 日以内の期間を選択してください。                                                  |
| `LZ-7112` | `dispute_still_open`                     | 409  | `conflict_error`        | Stripe はまだこの結果で異議申し立てを終了していません。Stripe で終了してから結果を記録してください。                         |
| `LZ-7113` | `dispute_resolution_failed`              | 409  | `conflict_error`        | このチャージの異議申し立ての結果を記録できませんでした。チャージ ID と異議申し立て ID を確認してください。                         |
| `LZ-7114` | `payment_document_reconcile_failed`      | 503  | `api_error`             | このチャージの請求書と領収書を Stripe と照合できませんでした。しばらくしてからもう一度お試しください。                           |
| `LZ-7121` | `referral_unavailable`                   | 500  | `invalid_request_error` | 紹介記録を取得できません。後でもう一度お試しください。                                                       |
| `LZ-7122` | `referral_code_invalid`                  | 400  | `invalid_request_error` | 3〜20 文字の英小文字・数字・ハイフンを使ってください。先頭と末尾にハイフンは使えません。                                    |
| `LZ-7123` | `referral_code_reserved`                 | 400  | `invalid_request_error` | この名前は使えません。別の名前をお試しください。                                                          |
| `LZ-7124` | `referral_code_taken`                    | 409  | `invalid_request_error` | この名前はすでに使われています。                                                                  |
| `LZ-7125` | `referral_code_limit`                    | 409  | `invalid_request_error` | 変更できる回数を使い切りました。                                                                  |
| `LZ-7126` | `promotion_unavailable`                  | 500  | `invalid_request_error` | キャンペーン設定を取得できません。後でもう一度お試しください。                                                   |
| `LZ-7127` | `promotion_config_invalid`               | 400  | `invalid_request_error` | 割合、金額上限、期間を確認してください。                                                              |
| `LZ-7128` | `referral_status_invalid`                | 400  | `invalid_request_error` | 紹介状態のフィルターが無効です。                                                                  |
| `LZ-7129` | `referral_search_invalid`                | 400  | `invalid_request_error` | 紹介記録の検索条件が無効です。                                                                   |
| `LZ-7130` | `referral_not_found`                     | 400  | `invalid_request_error` | 紹介報酬が見つかりません。                                                                     |
| `LZ-7131` | `referral_not_pending`                   | 409  | `invalid_request_error` | この紹介報酬は処理待ちではありません。                                                               |
| `LZ-7201` | `key_name_too_long`                      | 400  | `invalid_request_error` | API キーの名前が長すぎます。{{max\_length}} 文字以内にしてください。                                      |
| `LZ-7202` | `key_enable_blocked`                     | 409  | `conflict_error`        | この API キーは有効期限切れか利用枠を使い切っているため、有効にできません。先に有効期限を延ばすか、利用枠を増やしてください。                 |
| `LZ-7203` | `key_limit_reached`                      | 409  | `conflict_error`        | このプロジェクトで保有できる API キーは {{limit}} 本までで、上限に達しています。使っていないキーを削除してから作成してください。          |
| `LZ-7204` | `secret_unavailable`                     | 409  | `conflict_error`        | この API キーはダイジェストのみ保存されているため、完全なキーを表示できません。完全なキーが必要な場合は新しく作成してください。                |
| `LZ-7205` | `key_not_found`                          | 404  | `not_found_error`       | この API キーが見つかりません。削除された可能性があります。ページを再読み込みしてください。                                  |
| `LZ-7301` | `channel_not_found`                      | 404  | `not_found_error`       | このチャネルはすでに存在しません。削除された可能性があります。一覧を再読み込みしてください。                                    |
| `LZ-7302` | `channel_search_backend_managed`         | 409  | `conflict_error`        | このチャネルは検索バックエンドのため、ここでは変更できません。「検索バックエンド」ページで管理してください。                            |
| `LZ-7303` | `channel_lane_invalid`                   | 400  | `invalid_request_error` | ティア「{{lane}}」は存在しません。チャネルは既存のティアのいずれか 1 つに属します。一覧から選択してください。                      |
| `LZ-7304` | `channel_settings_invalid`               | 400  | `invalid_request_error` | チャネルの追加設定を読み取れなかったため、保存されませんでした。JSON の形式と値を確認してください。                              |
| `LZ-7305` | `channel_model_name_too_long`            | 400  | `invalid_request_error` | 255 文字を超えるモデル名があるため、チャネルは保存されませんでした。短くするか削除してください。                                |
| `LZ-7306` | `channel_not_multi_key`                  | 409  | `conflict_error`        | このチャネルはキーが 1 つのため、キーを個別に管理できません。                                                  |
| `LZ-7307` | `channel_key_index_invalid`              | 400  | `invalid_request_error` | このキーはすでにチャネルにありません。キー一覧を再読み込みしてから、もう一度お試しください。                                    |
| `LZ-7308` | `channel_last_key`                       | 409  | `conflict_error`        | チャネルの最後のキーのため削除できません。先に別のキーを追加するか、チャネルごと削除してください。                                 |
| `LZ-7309` | `channel_keys_none_eligible`             | 409  | `conflict_error`        | この操作に該当するキーがないため、何も変更されませんでした。                                                    |
| `LZ-7310` | `channel_balance_unsupported`            | 400  | `invalid_request_error` | このチャネルの種類、またはマルチキーのチャネルでは残高を照会できません。                                              |
| `LZ-7311` | `channel_balance_query_failed`           | 502  | `api_error`             | アップストリームから残高が返されませんでした。チャネルのキーと接続先 URL を確認してから、もう一度お試しください。                       |
| `LZ-7312` | `channel_upstream_models_failed`         | 502  | `api_error`             | アップストリームからモデル一覧が返されませんでした。キーと接続先 URL を確認するか、モデルを手動で入力してください。                      |
| `LZ-7313` | `channel_task_running`                   | 409  | `conflict_error`        | 同じメンテナンス処理がすでに実行中のため、新たに開始しませんでした。完了してからもう一度お試しください。                              |
| `LZ-7314` | `channel_test_failed`                    | 502  | `api_error`             | チャネルのテストに失敗しました。アップストリームがエラーを返しました。キー、接続先 URL、テスト用モデルを確認してから、もう一度テストしてください。       |
| `LZ-7315` | `channel_test_not_sent`                  | 422  | `invalid_request_error` | このチャネル用のテストリクエストを作成できなかったため、アップストリームには送信していません。チャネルの種類、モデルのマッピング、料金設定を確認してください。   |
| `LZ-7316` | `channel_route_not_found`                | 404  | `not_found_error`       | このチャネルは、そのティアでこのモデルを提供していません。ページを再読み込みして最新のルートを確認してください。                          |
| `LZ-7317` | `route_observation_incomplete`           | 409  | `conflict_error`        | このソースはまだ観察期間中です。7 日が経過し、すべてのチェックに合格すると公開できます。                                     |
| `LZ-7318` | `route_observation_none`                 | 404  | `not_found_error`       | このソースには観察中のモデルがありません。ページを再読み込みして最新の状態を確認してください。                                   |
| `LZ-7401` | `setting_invalid`                        | 400  | `invalid_request_error` | 設定値の一部が受け付けられなかったため、保存されていません。形式と値を確認してから、もう一度保存してください。                           |
| `LZ-7402` | `content_limit_exceeded`                 | 400  | `invalid_request_error` | このリストには最大 {{limit}} 件まで登録できます。いくつか削除してから保存してください。                                 |
| `LZ-7403` | `announcement_not_found`                 | 404  | `not_found_error`       | このお知らせはすでに存在しません。一覧を更新してください。                                                     |
| `LZ-7404` | `email_test_failed`                      | 502  | `api_error`             | テストメールを送信できませんでした。SMTP 設定を確認してください。メールサーバーの応答はサーバーログに記録されています。                    |
| `LZ-7405` | `email_test_recipient_missing`           | 400  | `invalid_request_error` | アカウントにメールアドレスがないため、テストメールの送信先がありません。先にメールアドレスを登録してください。                           |
| `LZ-7406` | `email_recipients_required`              | 400  | `invalid_request_error` | 宛先が選択されていないため、送信されませんでした。ユーザーを選ぶか、全員に送信を選んでください。                                  |
| `LZ-7407` | `announcement_email_content_missing`     | 400  | `invalid_request_error` | 送信できるお知らせがありません。タイトルと本文を入力するか、先にお知らせを公開してください。                                    |
| `LZ-7408` | `translation_token_missing`              | 400  | `invalid_request_error` | 翻訳にはご自身の API Key が必要ですが、使える Key がありません。Key を作成または有効にしてから、もう一度お試しください。             |
| `LZ-7409` | `feedback_request_not_found`             | 404  | `not_found_error`       | このリクエスト ID はお使いのアカウントに見つかりません。リクエスト ID を確認してください。                                 |
| `LZ-7410` | `database_unreachable`                   | 503  | `api_error`             | サーバーがデータベースに接続できません。データベースの状態を確認してから、もう一度お試しください。                                 |
| `LZ-7411` | `email_domain_not_allowed`               | 400  | `invalid_request_error` | このメールドメインは利用できません。許可されたドメインのアドレスを使ってください。                                         |
| `LZ-7412` | `email_alias_not_allowed`                | 400  | `invalid_request_error` | @ の前に「+」や「.」を含むアドレスは利用できません。エイリアスのないアドレスを使ってください。                                 |
| `LZ-7413` | `password_invalid`                       | 400  | `invalid_request_error` | パスワードは 8〜64 文字、かつ 72 バイト以内にしてください。別のパスワードを選んでください。                                |
| `LZ-7414` | `password_reset_link_invalid`            | 400  | `invalid_request_error` | リセットリンクが無効か、有効期限が切れています。もう一度リセットを申請してください。                                        |
| `LZ-7415` | `password_reset_client_upgrade_required` | 400  | `invalid_request_error` | ページが古いため、リンクはまだ使われていません。ページを再読み込みしてから、パスワードを設定し直してください。                           |
| `LZ-7421` | `mail_not_found`                         | 404  | `invalid_request_error` | 保存済みメールが見つかりません。                                                                  |
| `LZ-7422` | `mail_resend_failed`                     | 400  | `invalid_request_error` | メールの再送に失敗しました。配信の詳細を確認してください。                                                     |
| `LZ-7423` | `admin_email_missing`                    | 400  | `invalid_request_error` | プレビューの送信前にメールアドレスを登録してください。                                                       |
| `LZ-7424` | `mail_regenerate_failed`                 | 400  | `invalid_request_error` | メールの再生成に失敗しました。下書きは使用量レポートから再生成してください。                                            |
| `LZ-7425` | `digest_settings_invalid`                | 400  | `invalid_request_error` | 使用量レポートの設定が無効です。                                                                  |
| `LZ-7426` | `mail_send_failed`                       | 400  | `invalid_request_error` | メールの送信に失敗しました。配信の詳細を確認してください。                                                     |
| `LZ-7501` | `model_name_taken`                       | 409  | `conflict_error`        | {{model}} という名前のモデルはすでに存在します。別の名前にするか、既存のモデルを編集してください。                            |
| `LZ-7502` | `vendor_name_taken`                      | 409  | `conflict_error`        | {{vendor}} という名前のベンダーはすでに存在します。別の名前にするか、既存のベンダーを編集してください。                         |
| `LZ-7503` | `prefill_group_name_taken`               | 409  | `conflict_error`        | {{name}} という名前のプリセットグループはすでに存在します。別の名前にしてください。                                    |
| `LZ-7504` | `model_sync_not_configured`              | 503  | `api_error`             | このサーバーではモデルメタデータの同期が設定されていません。サーバーの環境変数にメタデータの URL を設定し、再起動してください。                |
| `LZ-7505` | `model_sync_source_unavailable`          | 502  | `api_error`             | {{source}} のモデルカタログを読み込めなかったため、何も同期されていません。しばらくしてからもう一度お試しください。                   |
| `LZ-7510` | `lane_not_found`                         | 404  | `not_found_error`       | レーン {{lane}} は存在しません。再読み込みして現在のレーンを確認してください。                                      |
| `LZ-7511` | `lane_builtin_locked`                    | 409  | `conflict_error`        | レーン {{lane}} は組み込みのため、停止も削除もできません。                                                |
| `LZ-7512` | `lane_ever_enabled`                      | 409  | `conflict_error`        | レーン {{lane}} は過去にトラフィックを処理したため、削除できません。代わりに停止してください。                              |
| `LZ-7513` | `lane_has_no_sources`                    | 409  | `conflict_error`        | レーン {{lane}} にはまだソースがなく、有効にするとこのレーンへのリクエストはすべて失敗します。先にソースを移してください。                |
| `LZ-7514` | `lane_in_use`                            | 409  | `conflict_error`        | レーン {{lane}} にはまだソース、価格、または割引が残っています。削除する前にそれらを移動または削除してください。                     |
| `LZ-7520` | `tier_not_found`                         | 404  | `not_found_error`       | ティア {{tier}} は存在しません。再読み込みして現在のティアを確認してください。                                      |
| `LZ-7521` | `tier_exists`                            | 409  | `conflict_error`        | {{tier}} という名前のティアはすでに存在します。別の名前にするか、そのティアを編集してください。                              |
| `LZ-7522` | `tier_builtin_locked`                    | 409  | `conflict_error`        | ティア {{tier}} は組み込みのため、削除できません。                                                    |
| `LZ-7523` | `tier_has_accounts`                      | 409  | `conflict_error`        | ティア {{tier}} にはまだアカウントが所属しています。ユーザーページで別のティアに移してから削除してください。                       |
| `LZ-7530` | `sell_price_missing`                     | 400  | `invalid_request_error` | 販売価格が入力されていません。少なくとも 1 つの価格を入力してから保存してください。                                       |
| `LZ-7531` | `sell_price_model_listed`                | 409  | `conflict_error`        | {{model}} はまだ公開中のため、価格を削除できません。先に非公開にしてください。                                      |
| `LZ-7532` | `sell_price_model_served`                | 409  | `conflict_error`        | 有効なチャネルがまだ {{model}} を提供しています。価格を削除するとリクエストが拒否されます。先にそれらのチャネルを無効にしてください。          |
| `LZ-7533` | `sell_price_model_discounted`            | 409  | `conflict_error`        | {{model}} には有効な割引が残っています。価格を削除する前に割引を解除してください。                                    |
| `LZ-7534` | `model_listing_unpriced`                 | 409  | `conflict_error`        | 次のモデルはどのレーンにも販売価格がなく、公開すると $0 で課金されます: {{models}}。公開する前に価格を設定してください。              |
| `LZ-7535` | `model_listing_no_source`                | 409  | `conflict_error`        | 次のモデルはレーン {{lane}} に有効なソースがありません: {{models}}。公開する前にソースを追加してください。                  |
| `LZ-7601` | `feature_unavailable`                    | 403  | `permission_error`      | このアカウントではチームプロジェクトが有効になっていません。                                                    |
| `LZ-7602` | `project_context_mismatch`               | 400  | `invalid_request_error` | このページのプロジェクトとリクエストのプロジェクトが一致しません。ページを再読み込みしてください。                                 |
| `LZ-7603` | `project_not_found`                      | 404  | `not_found_error`       | このプロジェクトが見つからないか、すでにメンバーではありません。                                                  |
| `LZ-7604` | `project_member_not_found`               | 404  | `not_found_error`       | この人はプロジェクトのメンバーではありません。メンバー一覧を更新してください。                                           |
| `LZ-7605` | `invite_not_found`                       | 404  | `not_found_error`       | この招待リンクは無効です。招待をもう一度送ってもらってください。                                                  |
| `LZ-7606` | `budget_request_not_found`               | 404  | `not_found_error`       | この予算申請はもう存在しません。一覧を更新してください。                                                      |
| `LZ-7607` | `undo_expired`                           | 409  | `conflict_error`        | 取り消しできる 10 分が経過しました。もう一度招待してください。                                                 |
| `LZ-7608` | `invalid_budget`                         | 400  | `invalid_request_error` | 予算は 0 以上の金額で指定してください。空欄にすると上限なしになります。                                             |
| `LZ-7609` | `invalid_effort_cap`                     | 400  | `invalid_request_error` | この推論強度の上限は選択できる段階ではありません。一覧から選んでください。                                             |
| `LZ-7610` | `invalid_settings`                       | 400  | `invalid_request_error` | プロジェクト設定に無効な値があります。設定を確認して保存し直してください。                                             |
| `LZ-7611` | `cannot_edit_own_budget`                 | 403  | `permission_error`      | 自分の予算は変更できません。別の管理者に変更を依頼してください。                                                  |
| `LZ-7612` | `cannot_change_owner`                    | 403  | `permission_error`      | オーナーの役割とステータスは変更できません。                                                            |
| `LZ-7613` | `confirm_mismatch`                       | 400  | `invalid_request_error` | プロジェクト名が一致しません。表示どおりに入力してください。                                                    |
| `LZ-7614` | `resend_too_soon`                        | 429  | `rate_limit_error`      | 招待を送信したばかりです。1 分待ってから再送してください。                                                    |
| `LZ-7615` | `request_pending`                        | 409  | `conflict_error`        | 処理待ちの予算申請がすでにあります。処理を待つか、先に取り下げてください。                                             |
| `LZ-7616` | `invalid_pagination`                     | 400  | `invalid_request_error` | このページの一覧は表示できません。ページを更新してください。                                                    |
| `LZ-7617` | `already_member`                         | 409  | `conflict_error`        | この人はすでにメンバーです。                                                                    |
| `LZ-7618` | `already_invited`                        | 409  | `conflict_error`        | このアドレスには承諾待ちの招待があります。その招待を再送してください。                                               |
| `LZ-7619` | `invite_expired`                         | 409  | `conflict_error`        | 招待は期限切れです。新しい招待を送ってもらってください。                                                      |
| `LZ-7620` | `invite_revoked`                         | 409  | `conflict_error`        | 招待は取り消されました。参加が必要な場合は、もう一度招待してもらってください。                                           |
| `LZ-7621` | `invite_email_mismatch`                  | 403  | `permission_error`      | この招待はログイン中のメールアドレス宛ではありません。招待を受け取ったアドレスでログインしてから承諾してください。                         |
| `LZ-7622` | `invite_email_unverified`                | 403  | `permission_error`      | 招待を承諾する前に、メールアドレスを確認してください。                                                       |
| `LZ-7623` | `invitee_feature_unavailable`            | 403  | `permission_error`      | このアカウントはまだプロジェクトに参加できません。別のメールアドレスを試すか、しばらくしてからもう一度お試しください。                       |
| `LZ-7624` | `invite_email_invalid`                   | 400  | `invalid_request_error` | メールアドレスの形式が正しくありません。確認してもう一度お試しください。                                              |
| `LZ-7625` | `invite_role_invalid`                    | 400  | `invalid_request_error` | 役割は管理者またはメンバーから選んでください。                                                           |
| `LZ-7626` | `project_name_invalid`                   | 400  | `invalid_request_error` | プロジェクト名は空にできず、191 文字以内で入力してください。                                                  |
| `LZ-7627` | `project_deletion_dependency`            | 409  | `conflict_error`        | このアカウントは、メンバー・支払い・キーが依存するチームプロジェクトをまだ所有しているか、参加しています。先にそれらのプロジェクトを整理してから削除してください。 |
| `LZ-7701` | `usage_range_invalid`                    | 400  | `invalid_request_error` | 期間の終了が開始より前になっています。期間を調整してもう一度お試しください。                                            |
| `LZ-7702` | `usage_range_too_long`                   | 400  | `invalid_request_error` | 期間が {{max\_days}} 日を超えています。期間を短くしてください。                                           |
| `LZ-7703` | `invalid_usage_summary_window`           | 400  | `invalid_request_error` | 使用量サマリーの期間指定が無効です。since、until、granularity を確認してください。                              |
| `LZ-7704` | `request_not_found`                      | 404  | `not_found_error`       | この API キーではこのリクエストが見つかりませんでした。リクエスト ID を確認してください。                                 |
| `LZ-7705` | `log_session_not_found`                  | 404  | `not_found_error`       | 閲覧できるログの中にこのセッションが見つかりません。ページを再読み込みしてください。                                        |
| `LZ-7706` | `usage_export_format_unsupported`        | 400  | `invalid_request_error` | このエクスポート形式には対応していません。CSV または XLSX でエクスポートしてください。                                  |
| `LZ-7707` | `log_cleanup_cutoff_too_recent`          | 400  | `invalid_request_error` | 直近 {{min\_days}} 日のログはモデルランキングに使うため削除できません。より前の日付を選んでください。                        |
| `LZ-7708` | `spend_budget_not_found`                 | 404  | `not_found_error`       | この支出予算が見つかりません。削除された可能性があります。ページを再読み込みしてください。                                     |
| `LZ-7801` | `purpose_not_supported`                  | 400  | `invalid_request_error` | このファイル用途には対応していません。user\_data または vision としてアップロードしてください。                         |
| `LZ-7802` | `invalid_file`                           | 400  | `invalid_request_error` | ファイルが受け付けられませんでした。ファイルの種類と内容を確認して、もう一度アップロードしてください。                               |
| `LZ-7803` | `file_too_large`                         | 413  | `invalid_request_error` | ファイルがサイズ上限を超えています。より小さいファイルをアップロードしてください。                                         |
| `LZ-7804` | `file_not_found`                         | 404  | `not_found_error`       | このファイルが見つからないか、アクセスできません。ファイル ID を確認してください。                                       |
| `LZ-7805` | `file_expired`                           | 400  | `invalid_request_error` | このファイルは有効期限が切れたため使用できません。もう一度アップロードしてください。                                        |
| `LZ-7806` | `file_dereference_failed`                | 502  | `api_error`             | ストレージからファイルを読み込めなかったため、リクエストは送信されませんでした。しばらくしてからもう一度お試しください。                      |
| `LZ-7807` | `file_storage_failed`                    | 502  | `api_error`             | ファイルストレージで操作が完了しませんでした。しばらくしてからもう一度お試しください。                                       |
| `LZ-7808` | `storage_not_configured`                 | 503  | `api_error`             | このサイトではファイルストレージが設定されていないため、ファイルを保存・読み込みできません。管理者にお問い合わせください。                     |
| `LZ-7809` | `storage_quota_exceeded`                 | 429  | `insufficient_quota`    | ファイルストレージの予算を使い切りました。不要なファイルを削除するか、予算の引き上げを依頼してください。                              |
| `LZ-7821` | `unsupported_media_kind`                 | 400  | `invalid_request_error` | このメディアの種類には対応していません。image または video を選んでください。                                     |
| `LZ-7822` | `unsupported_media_status`               | 400  | `invalid_request_error` | このステータスでの絞り込みには対応していません。pending、running、succeeded、failed のいずれかを指定してください。          |
| `LZ-7823` | `media_job_not_found`                    | 404  | `not_found_error`       | このメディアジョブが見つかりません。ジョブ ID を確認してください。                                               |
| `LZ-7824` | `artifact_file_not_found`                | 404  | `not_found_error`       | 成果物のファイルが見つかりません。ファイル ID を確認するか、もう一度アップロードしてください。                                 |
| `LZ-7825` | `video_not_found`                        | 404  | `not_found_error`       | この動画ジョブが見つかりません。ジョブ ID を確認してください。                                                 |
| `LZ-7826` | `invalid_studio_media_job`               | 400  | `invalid_request_error` | リクエスト内の Studio ジョブがこのリクエストと一致しません。Studio から生成をやり直してください。                          |
| `LZ-7827` | `artifact_too_large`                     | 502  | `api_error`             | 生成されたファイルが保存できるサイズを超えたため、結果は保存されませんでした。サイズを小さくするか、長さを短くしてお試しください。                 |
| `LZ-7828` | `video_artifact_missing`                 | 502  | `api_error`             | 動画の生成は終わりましたが、ダウンロードできるファイルがありません。もう一度生成してください。                                   |
| `LZ-7841` | `studio_disabled`                        | 404  | `not_found_error`       | このサイトでは Studio が有効になっていません。                                                       |
| `LZ-7842` | `studio_generation_not_found`            | 404  | `not_found_error`       | この作品が見つからないか、表示する権限がなくなりました。ページを再読み込みしてください。                                      |
| `LZ-7843` | `studio_project_not_found`               | 404  | `not_found_error`       | この Studio プロジェクトまたはキャンバスの項目が見つかりません。削除された可能性があります。ページを再読み込みしてください。                |
| `LZ-7844` | `studio_artifact_not_found`              | 404  | `not_found_error`       | この作品のファイルが見つからないか、期限切れです。もう一度生成してください。                                            |
| `LZ-7845` | `studio_artifact_unsupported`            | 415  | `invalid_request_error` | このファイルは対応している画像または動画ではありません。PNG、JPEG、GIF、WebP、または動画ファイルを選んでください。                  |
| `LZ-7846` | `studio_key_unavailable`                 | 400  | `invalid_request_error` | 選択した API キーは無効化されているか、存在しません。別のキーを選んでください。                                        |
| `LZ-7847` | `studio_key_required`                    | 400  | `invalid_request_error` | アカウント残高での生成は、ログイン済みのブラウザからのみ行えます。代わりに API キーを選んでください。                             |
| `LZ-7848` | `studio_creator_not_found`               | 404  | `not_found_error`       | このクリエイターの公開作品は見つかりませんでした。リンクを確認するか、最新の作品をご覧ください。                                  |
| `LZ-7849` | `studio_sign_in_required`                | 401  | `authentication_error`  | ログインしてください。検索、オリジナル画像のダウンロード、続きの閲覧にはアカウントが必要です。                                   |
| `LZ-7850` | `studio_download_limit_reached`          | 429  | `rate_limit_error`      | 本日のオリジナル画像のダウンロード回数を使い切りました。お使いのタイムゾーンの午前0時にリセットされます。プレビュー画像は引き続きダウンロードできます。      |
| `LZ-7851` | `studio_free_unavailable`                | 409  | `conflict_error`        | 本日の無料生成は利用できません。すでに使用済みか、メールアドレスの確認が必要です。                                         |
| `LZ-7852` | `studio_not_favoritable`                 | 409  | `conflict_error`        | お気に入りに追加できるのは公開済みの作品だけです。                                                         |
| `LZ-7853` | `studio_signature_invalid`               | 403  | `permission_error`      | ダウンロードリンクが無効か期限切れです。もう一度ダウンロードしてください。                                             |
| `LZ-7861` | `search_backend_not_found`               | 404  | `not_found_error`       | この検索バックエンドが見つかりません。一覧を再読み込みしてください。                                                |
| `LZ-7862` | `search_backend_provider_invalid`        | 400  | `invalid_request_error` | この検索プロバイダーには対応していないか、チャネルの種類と一致しません。一覧からプロバイダーを選んでください。                           |
| `LZ-7863` | `poster_draft_not_found`                 | 404  | `not_found_error`       | このポスターの下書きが見つかりません。一覧を再読み込みしてください。                                                |
| `LZ-7864` | `upload_file_not_found`                  | 404  | `not_found_error`       | このデータファイルがサーバー上に見つかりません。ファイルのパスを確認してください。                                         |
| `LZ-7865` | `upload_key_not_allowed`                 | 400  | `invalid_request_error` | このパスはアップロードできません。ディレクトリと設定ファイルは対象外です。通常のデータファイルを選んでください。                          |
| `LZ-7866` | `upload_failed`                          | 502  | `api_error`             | オブジェクトストレージがアップロードを受け付けませんでした。ストレージの設定を確認して、もう一度お試しください。                          |
| `LZ-7867` | `blog_validation_failed`                 | 400  | `invalid_request_error` | ブログのリクエストが無効です：{reason\|値を確認してください}。                                              |
| `LZ-7868` | `blog_publish_blocked`                   | 422  | `invalid_request_error` | 記事が公開前のチェックに合格していません。                                                             |

### LZ-9xxx · 内部エラー

| 番号        | Code              | HTTP | タイプ         | 意味と対処                                                             |
| --------- | ----------------- | ---- | ----------- | ----------------------------------------------------------------- |
| `LZ-9001` | `internal_error`  | 500  | `api_error` | サービスがこのリクエストを完了できませんでした。繰り返し発生する場合は、リクエスト ID を添えてサポートにお問い合わせください。 |
| `LZ-9002` | `not_implemented` | 501  | `api_error` | この機能はまだ利用できません。                                                   |

## 関連ページ

- [レート制限](https://lazu.ai/docs/ja/limits)
- [認証](https://lazu.ai/docs/ja/authentication)
- [リクエスト詳細](https://lazu.ai/docs/ja/endpoints/usage-requests)

---

# Handling request errors

If a request returns `429`, inspect the error body and respect `Retry-After` when present. Use bounded backoff instead of an immediate retry loop. A `429` can arise from gateway or upstream controls; it is not evidence of a published account plan. Do not automatically replay a stream after output has arrived. See [Errors](https://lazu.ai/docs/errors) for authentication, request and upstream failures.

---

# 请求错误处理

收到 `429` 时检查错误正文，如有 `Retry-After` 则按其等待，使用有上限的退避重试，避免立即循环请求。`429` 可能来自网关或上游控制，不代表某个已公布的账户套餐。已经收到流式输出后，不要自动重放请求。鉴权、参数和上游错误见[错误说明](https://lazu.ai/docs/zh/errors)。

---

# 請求錯誤處理

收到 `429` 時檢查錯誤本文，如有 `Retry-After` 則依其等待，使用有上限的退避重試，避免立即循環請求。`429` 可能來自閘道或上游控制，不代表某個已公布的帳戶方案。已收到串流輸出後，不要自動重送請求。驗證、參數與上游錯誤見[錯誤說明](https://lazu.ai/docs/zh-TW/errors)。

---

# リクエストエラーへの対処

`429` が返った場合はエラー本文を確認し、`Retry-After` があれば従います。即時ループではなく上限付きバックオフを使ってください。`429` はゲートウェイまたは上流の制御から発生し、公開アカウントプランの証明ではありません。ストリーム出力を受信した後は自動再送しないでください。認証、入力、上流の問題は[エラー説明](https://lazu.ai/docs/ja/errors)を参照してください。

---

# 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-6-luna",
      "object": "model",
      "name": "gpt-6-luna",
      "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"
          ]
        }
      },
      "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](https://lazu.ai/docs/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](https://lazu.ai/docs/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`。

## 相关页面

- [模型列表](https://lazu.ai/docs/zh/endpoints/models)
- [定价与渠道](https://lazu.ai/docs/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`。

## 相關頁面

- [模型列表](https://lazu.ai/docs/zh-TW/endpoints/models)
- [定價與通道](https://lazu.ai/docs/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`
を使ってください。

## 関連ページ

- [モデル一覧](https://lazu.ai/docs/ja/endpoints/models)
- [料金と経路](https://lazu.ai/docs/ja/models/pricing)

---

# Pricing and lanes

Available lanes and prices are shown in the model catalog. A model may expose one or more available lanes. Internal/API values `direct` and `cheap` identify routing-price lanes; they do not by themselves certify a provider identity, compliance status, uptime or latency guarantee.

## Stable lane and discount lane

The stable lane runs on each maker's official API, is billed at the list price, has the highest availability and suits every use. The discount lane is a reverse-engineered route: a third-party supplier serves the model through its official client, not the official API. It costs far less, but availability varies, a failed request does not fall back to the stable lane, and the supplier may add its own system prompt. So use it only inside the matching agent tool: Claude models in Claude Code, GPT models in Codex, Gemini models in Antigravity. For your own code, or anywhere the output must be controlled exactly, use the stable lane. Both lanes work with the same key, and each key picks the lane per model.

## Read current prices

Use `/api/models/catalog` with your API key: its `pricing` object is the adjusted catalog price for that key, while `lanes` describes published lane prices and availability. Do not substitute the public `/v1/models` or session-based catalog pricing shape for this route. Check the serving lane and any applicable peak schedule when estimating. Missing price fields do not mean zero. The final request receipt records the charge.

```bash
curl --fail-with-body https://api.lazu.ai/api/models/catalog \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  | jq '.data[] | {id, supported_endpoints, pricing, lanes}'
```

## Selection and fallback

Inspect your API key settings and the model’s current lanes. A cheap preference is strict: if its price or a compatible channel is unavailable, the request fails. Once a cheap channel is selected, an upstream failure is returned without retrying another channel or falling back to direct. Select direct explicitly if you want stable-lane pricing and retries. Reference prices, when present, are for comparison only and are not the charge. Do not treat example prices or a past catalog response as a current quote.

## Price changes

Prices and available routes can change. Refresh the catalog before estimating a new workload; preserve the request ID and receipt for reconciliation. Do not infer a new price for an old request from today’s catalog.

[Billing](https://lazu.ai/docs/billing)

---

# 价格与线路

模型目录展示当前可用通道与价格，一个模型可能有一个或多个可用通道。API／内部值 `direct` 和 `cheap` 表示路由计价通道，本身不构成供应商身份、合规资质、可用率或延迟保证。

## 稳定线路和优惠线路

稳定线路走各家官方 API，按标价计费，可用率最高，适合所有场景。优惠线路是逆向渠道：由第三方供应商通过官方客户端接入，不是官方 API。价格低很多，但可用率会有波动，失败时不会自动切到稳定线路，上游也可能附带自己的系统提示，所以只建议在对应的 Agent 工具里使用：Claude 模型配 Claude Code，GPT 模型配 Codex，Gemini 模型配 Antigravity。自己写的程序或需要精确控制输出的场景，请用稳定线路。两条线路用同一个 Key，可以在每把 Key 上按模型选线路。

## 读取当前价格

使用 API Key 查询 `/api/models/catalog`：此入口的 `pricing` 是按当前 Key 上下文调整的目录价格，`lanes` 描述已发布通道价格和可用状态。不要混用公开 `/v1/models` 或会话目录的价格结构。估算时核对实际服务通道和适用的峰时安排；缺失价格字段不代表零价，最终费用按请求回执核对。

```bash
curl --fail-with-body https://api.lazu.ai/api/models/catalog \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  | jq '.data[] | {id, supported_endpoints, pricing, lanes}'
```

## 选择与回退

查看 API Key 的设置及模型当前通道。选择 cheap 后，仅使用优惠档：没有对应售价或可用渠道时直接报错；选定渠道后，上游失败也不会切换其他渠道重试或回落 direct。如需稳定档价格和重试，请主动选择 direct。官方参考价仅用于比较，不是扣费价格。不要把示例数字或旧目录响应当成当前报价。

## 价格变化

价格与可用路由可能调整。估算新工作负载前刷新目录，保留请求 ID 和回执用于对账；不要用今天的目录价格重新推算旧请求账单。

[计费说明](https://lazu.ai/docs/zh/billing)

---

# 價格與線路

模型目錄顯示目前可用通道與價格，一個模型可能有一個或多個可用通道。API／內部值 `direct` 與 `cheap` 表示路由計價通道，本身不構成供應商身分、合規資格、可用率或延遲保證。

## 穩定線路和優惠線路

穩定線路走各家官方 API，按標價計費，可用率最高，適合所有場景。優惠線路是逆向渠道：由第三方供應商透過官方客戶端接入，不是官方 API。價格低很多，但可用率會有波動，失敗時不會自動切到穩定線路，上游也可能附帶自己的系統提示，所以只建議在對應的 Agent 工具裡使用：Claude 模型搭配 Claude Code，GPT 模型搭配 Codex，Gemini 模型搭配 Antigravity。自己寫的程式或需要精確控制輸出的場景，請用穩定線路。兩條線路用同一把 Key，可以在每把 Key 上按模型選線路。

## 讀取目前價格

使用 API Key 查詢 `/api/models/catalog`：此入口的 `pricing` 是按目前 Key 情境調整的目錄價格，`lanes` 描述已發布通道價格與可用狀態。不要混用公開 `/v1/models` 或工作階段目錄的價格結構。估算時核對實際服務通道與適用尖峰時段；缺少價格欄位不代表零價，最終費用按請求回執核對。

```bash
curl --fail-with-body https://api.lazu.ai/api/models/catalog \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  | jq '.data[] | {id, supported_endpoints, pricing, lanes}'
```

## 選擇與回退

查看 API Key 的設定及模型目前通道。選擇 cheap 後，僅使用優惠檔：沒有對應售價或可用通道時直接報錯；選定通道後，上游失敗也不會切換其他通道重試或回退 direct。如需穩定檔價格和重試，請主動選擇 direct。官方參考價僅供比較，不是扣費價格。不要把示例數字或舊目錄回應當成目前報價。

## 價格變化

價格與可用路由可能調整。估算新工作負載前重新讀取目錄，保留請求 ID 與回執對帳；不要用今天的目錄價格重新推算舊請求帳單。

[計費說明](https://lazu.ai/docs/zh-TW/billing)

---

# 価格とレーン

モデルカタログに現在のレーンと価格が表示されます。利用可能なレーン数はモデルごとに異なります。API／内部の `direct` と `cheap` はルーティングと価格のレーンを識別し、それだけで供給元、法令対応、稼働率や遅延を保証するものではありません。

## 安定ラインと割引ライン

安定ラインは各社の公式 API を使い、表示価格で課金され、稼働率が最も高く、あらゆる用途に向いています。割引ラインはリバース型の経路で、サードパーティが公式クライアント経由で提供するもので、公式 API ではありません。料金は大幅に安い一方、稼働率は変動し、失敗しても安定ラインには切り替わらず、提供元が独自のシステムプロンプトを付けることがあります。そのため、対応する Agent ツールでの利用に限って推奨します（Claude モデルは Claude Code、GPT モデルは Codex、Gemini モデルは Antigravity）。自作のプログラムや出力を厳密に制御したい場面では安定ラインを使ってください。どちらも同じ Key で使え、Key ごと・モデルごとにラインを選べます。

## 現在の価格を読む

API キーで `/api/models/catalog` を取得します。この入口の `pricing` はキーのコンテキストに応じたカタログ価格で、`lanes` は公開レーンの価格と利用可否です。公開 `/v1/models` やセッション用カタログの価格構造と混同しないでください。処理するレーンと該当ピーク時間を考慮し、欠落項目をゼロと解釈しないでください。最終料金はリクエスト明細で照合します。

```bash
curl --fail-with-body https://api.lazu.ai/api/models/catalog \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  | jq '.data[] | {id, supported_endpoints, pricing, lanes}'
```

## 選択とフォールバック

API キーの設定とモデルの現在のレーンを確認してください。cheap を選択した場合、対応する価格や利用可能なチャネルがなければエラーになります。チャネル選択後に上流で失敗しても、別チャネルでの再試行や direct へのフォールバックは行いません。安定レーンの価格と再試行を利用するには、明示的に direct を選択してください。参考価格は比較用であり、請求額ではありません。例示価格や過去のカタログを現在の見積もりとして扱わないでください。

## 価格の変更

価格や利用可能な経路は変わることがあります。新しい処理の見積もり前にカタログを更新し、照合用にリクエスト ID と明細を保存してください。過去のリクエスト料金を現在のカタログから再計算しないでください。

[料金体系](https://lazu.ai/docs/ja/billing)

---

# Quickstart

## 1. Create a key and select a model

Create a key in the [console](https://lazu.ai/console/token). Set the environment variables below, then query the catalog with that key. Choose a model whose `supported_endpoints` includes `/v1/chat/completions` and set `LAZU_MODEL` to its ID. A catalog entry describes access and capabilities; it does not prove a live upstream request will succeed.

```bash
export LAZU_API_ORIGIN="https://api.lazu.ai"
export LAZU_API_KEY="YOUR_LAZU_KEY"
curl --fail-with-body "$LAZU_API_ORIGIN/api/models/catalog" \
  -H "Authorization: Bearer $LAZU_API_KEY"
export LAZU_MODEL="MODEL_ID_FROM_CATALOG"
```

## 2. Send a request

For raw HTTP, `LAZU_API_ORIGIN` is the origin without `/v1`. OpenAI SDKs use that origin plus `/v1`. For self-hosting, replace the origin with your own.

```bash
# Requires jq. Inspect response headers in response.headers.
jq -n --arg model "$LAZU_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello"}]}' \
  | curl --fail-with-body -D response.headers \
      "$LAZU_API_ORIGIN/v1/chat/completions" \
      -H "Authorization: Bearer $LAZU_API_KEY" \
      -H "Content-Type: application/json" --data-binary @-
```

### Python

```bash
python -m pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ["LAZU_API_ORIGIN"].rstrip("/") + "/v1",
)
response = client.chat.completions.create(
    model=os.environ["LAZU_MODEL"],
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```bash
npm install openai
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAZU_API_KEY,
  baseURL: `${process.env.LAZU_API_ORIGIN}/v1`,
});
const response = await client.chat.completions.create({
  model: process.env.LAZU_MODEL!,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);
```

## 3. Check the result

Read the returned text and save `X-Request-Id` from the response headers. In Console → Usage, find the request and inspect usage and billing. Use the same API key for `GET /api/usage/requests/{request_id}`. Do not assume an upstream response body ID is the Lazu request ID.

[Images, video and audio](https://lazu.ai/docs/endpoints/media) · [Pricing and lanes](https://lazu.ai/docs/models/pricing)

---

# 快速开始

## 1. 创建密钥并选择模型

在[控制台](https://lazu.ai/console/token)创建密钥。设置下面的环境变量，用该密钥查询目录，选择 `supported_endpoints` 包含 `/v1/chat/completions` 的模型，将其 ID 设置为 `LAZU_MODEL`。目录说明访问范围和能力，不代表一次真实上游请求一定成功。

```bash
export LAZU_API_ORIGIN="https://api.lazu.ai"
export LAZU_API_KEY="YOUR_LAZU_KEY"
curl --fail-with-body "$LAZU_API_ORIGIN/api/models/catalog" \
  -H "Authorization: Bearer $LAZU_API_KEY"
export LAZU_MODEL="MODEL_ID_FROM_CATALOG"
```

## 2. 发起请求

直接发送 HTTP 请求时，`LAZU_API_ORIGIN` 是不含 `/v1` 的域名地址；OpenAI SDK 的 base URL 需在其后加 `/v1`。自托管时替换为自己的地址。

```bash
# Requires jq. Inspect response headers in response.headers.
jq -n --arg model "$LAZU_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello"}]}' \
  | curl --fail-with-body -D response.headers \
      "$LAZU_API_ORIGIN/v1/chat/completions" \
      -H "Authorization: Bearer $LAZU_API_KEY" \
      -H "Content-Type: application/json" --data-binary @-
```

### Python

```bash
python -m pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ["LAZU_API_ORIGIN"].rstrip("/") + "/v1",
)
response = client.chat.completions.create(
    model=os.environ["LAZU_MODEL"],
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```bash
npm install openai
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAZU_API_KEY,
  baseURL: `${process.env.LAZU_API_ORIGIN}/v1`,
});
const response = await client.chat.completions.create({
  model: process.env.LAZU_MODEL!,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);
```

## 3. 查看结果与用量

读取返回文本，并保存响应头中的 `X-Request-Id`。在控制台“用量与日志”中找到请求，核对用量和费用；也可用同一密钥调用 `GET /api/usage/requests/{request_id}`。不要将上游响应正文的 ID 直接当作 Lazu 请求 ID。

[图片、视频与音频](https://lazu.ai/docs/zh/endpoints/media) · [价格与线路](https://lazu.ai/docs/zh/models/pricing)

---

# 快速開始

## 1. 建立金鑰並選擇模型

在[控制台](https://lazu.ai/console/token)建立金鑰。設定下方環境變數，用該金鑰查詢目錄，選擇 `supported_endpoints` 包含 `/v1/chat/completions` 的模型，將其 ID 設為 `LAZU_MODEL`。目錄說明存取範圍與能力，不代表一次真實上游請求一定成功。

```bash
export LAZU_API_ORIGIN="https://api.lazu.ai"
export LAZU_API_KEY="YOUR_LAZU_KEY"
curl --fail-with-body "$LAZU_API_ORIGIN/api/models/catalog" \
  -H "Authorization: Bearer $LAZU_API_KEY"
export LAZU_MODEL="MODEL_ID_FROM_CATALOG"
```

## 2. 發起請求

直接發送 HTTP 請求時，`LAZU_API_ORIGIN` 是不含 `/v1` 的網域位址；OpenAI SDK 的 base URL 需在其後加 `/v1`。自架部署請替換為自己的位址。

```bash
# Requires jq. Inspect response headers in response.headers.
jq -n --arg model "$LAZU_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello"}]}' \
  | curl --fail-with-body -D response.headers \
      "$LAZU_API_ORIGIN/v1/chat/completions" \
      -H "Authorization: Bearer $LAZU_API_KEY" \
      -H "Content-Type: application/json" --data-binary @-
```

### Python

```bash
python -m pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ["LAZU_API_ORIGIN"].rstrip("/") + "/v1",
)
response = client.chat.completions.create(
    model=os.environ["LAZU_MODEL"],
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```bash
npm install openai
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAZU_API_KEY,
  baseURL: `${process.env.LAZU_API_ORIGIN}/v1`,
});
const response = await client.chat.completions.create({
  model: process.env.LAZU_MODEL!,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);
```

## 3. 查看結果與用量

讀取回傳文字並保存回應標頭的 `X-Request-Id`。在控制台「用量與日誌」找到請求，核對用量與費用；也可用同一金鑰呼叫 `GET /api/usage/requests/{request_id}`。不要將上游回應本文的 ID 直接當成 Lazu 請求 ID。

[圖片、影片與音訊](https://lazu.ai/docs/zh-TW/endpoints/media) · [價格與線路](https://lazu.ai/docs/zh-TW/models/pricing)

---

# クイックスタート

## 1. キーを作成してモデルを選ぶ

[コンソール](https://lazu.ai/console/token)でキーを作成します。下記の環境変数を設定し、そのキーでカタログを取得してください。`supported_endpoints` に `/v1/chat/completions` が含まれるモデルを選び、ID を `LAZU_MODEL` に設定します。カタログはアクセス範囲と機能を示しますが、実際の上流リクエストの成功を保証するものではありません。

```bash
export LAZU_API_ORIGIN="https://api.lazu.ai"
export LAZU_API_KEY="YOUR_LAZU_KEY"
curl --fail-with-body "$LAZU_API_ORIGIN/api/models/catalog" \
  -H "Authorization: Bearer $LAZU_API_KEY"
export LAZU_MODEL="MODEL_ID_FROM_CATALOG"
```

## 2. リクエストを送る

HTTP を直接使う場合、`LAZU_API_ORIGIN` は `/v1` を含まないオリジンです。OpenAI SDK の base URL には `/v1` を追加します。セルフホストでは自身のオリジンに置き換えてください。

```bash
# Requires jq. Inspect response headers in response.headers.
jq -n --arg model "$LAZU_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello"}]}' \
  | curl --fail-with-body -D response.headers \
      "$LAZU_API_ORIGIN/v1/chat/completions" \
      -H "Authorization: Bearer $LAZU_API_KEY" \
      -H "Content-Type: application/json" --data-binary @-
```

### Python

```bash
python -m pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAZU_API_KEY"],
    base_url=os.environ["LAZU_API_ORIGIN"].rstrip("/") + "/v1",
)
response = client.chat.completions.create(
    model=os.environ["LAZU_MODEL"],
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```bash
npm install openai
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAZU_API_KEY,
  baseURL: `${process.env.LAZU_API_ORIGIN}/v1`,
});
const response = await client.chat.completions.create({
  model: process.env.LAZU_MODEL!,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);
```

## 3. 結果と使用量を確認する

返されたテキストを読み、レスポンスヘッダーの `X-Request-Id` を保存します。コンソールの使用量・ログで請求を確認するか、同じキーで `GET /api/usage/requests/{request_id}` を呼び出します。上流レスポンス本文の ID が Lazu のリクエスト ID とは限りません。

[画像・動画・音声](https://lazu.ai/docs/ja/endpoints/media) · [価格とレーン](https://lazu.ai/docs/ja/models/pricing)