> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LaoZhang API 接続ガイド：APIキーの作成からリクエスト送信まで

> APIキーを設定し、OpenAI・Anthropic・Gemini形式のリクエストを送信して、画像の生成と編集、既存のOpenAIアプリの移行まで、動作するコード例で進められます。

LaoZhang APIのAPIキーを付けて、下表のいずれかのホストにリクエストを送ります。OpenAI SDKは `https://api.laozhang.ai/v1` を指定し、Google Gen AI SDKとAnthropic SDKはホストのルートを指定します。

| ドメイン | 使う場面 |
| - | - |
| `api.laozhang.ai` | 既定。このサイトのコード例はすべてこのドメインを使います |
| `api-vip.laozhang.ai` | サーバーがヨーロッパや北米にあり、直接接続したい場合 |
| `api2.laozhang.ai` | お使いのネットワークから `api.laozhang.ai` に接続できない場合 |

3つのドメインは、同じAPIキー、パス、パラメーターを受け付けます。切り替えるのはホスト名だけで、コンソールも各ドメインで開けます。アプリケーションがすでに使っているリクエスト形式を選び、APIキーのグループで呼び出せるモデルを指定してください。

## APIキーの作成

APIキーは[トークン管理](https://api.laozhang.ai/token)で作成します。コンソールではAPIキーを「トークン」と呼びます。作成時にグループと課金方式を選び、グループによって、そのキーで呼び出せるモデルが決まります。

課金方式は、従量優先（推奨。コンソールの表示は「按量优先」）を選んでください。この方式のキーなら、従量課金のテキストモデルと、以下で使う回数課金の画像モデルの両方を呼び出せます。2つの設定は[課金、トークングループ、請求書](https://docs.laozhang.ai/ja/pricing.md)で説明しています。

コード例を実行するターミナルで、キーを環境変数に設定します。

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

プレースホルダーは自分のキーに置き換えてください。キーはサーバー側で管理し、ブラウザ向けのバンドル、ソース管理、ログには含めないでください。アカウント管理用のAccessTokenはAPIキーとは別の認証情報で、[残高照会API](https://docs.laozhang.ai/ja/api-capabilities/balance-query.md)などのアカウント系エンドポイントでのみ使います。

コード例では、次のモデルを使います。

* テキスト：`gpt-5.4-mini`
* Geminiネイティブのリクエスト：`gemini-3.8-flash`
* Anthropic Messages：`glm-5.2`
* 画像の生成：`gpt-image-2.5-flare-vip`
* 画像の編集：`gpt-image-2.5-sunburst-vip`

別のモデルを使うときは、[モデルと料金](https://docs.laozhang.ai/ja/models.md)から正確なモデルIDをコピーし、キーのグループで呼び出せることを確認してください。テキストモデルとリクエスト形式の選び方は、[テキスト生成API](https://docs.laozhang.ai/ja/api-capabilities/text-generation.md)のガイドを参照してください。

## テキストリクエストの送信

Chat Completionsは `messages` 配列を受け取ります。APIキーはBearerトークンとして送り、本文はJSONにします。

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "「connected」とだけ返信してください"}]
  }'
```

回答は `choices[0].message.content` に入ります。このプロンプトなら `connected` が返ります。自分のアプリケーションでは、メッセージの内容を実際のプロンプトに置き換えるだけで同じリクエストを使えます。メッセージのフィールド、ストリーミング、モデル固有のオプションは、[OpenAIプロトコルのリファレンス](https://docs.laozhang.ai/ja/api-reference/chat-completions.md)を参照してください。

## OpenAI SDK

OpenAI SDKはエンドポイントのパスを自分で組み立てます。ベースURLは `https://api.laozhang.ai/v1` までにして、`/chat/completions` は付けないでください。

> [tab] Python
>
> SDKをインストールします。
>
> ```bash theme={null}
> python -m pip install openai
> ```
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> # 環境変数からAPIキーを読み取り、LaoZhang APIのベースURLを指定する
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=120.0,
>     max_retries=0,
> )
> response = client.chat.completions.create(
>     model="gpt-5.4-mini",
>     messages=[{"role": "user", "content": "「connected」とだけ返信してください"}],
> )
> print(response.choices[0].message.content)
> ```

> [tab] Node.js
>
> `npm install openai` でSDKをインストールし、次のコードを `.mjs` ファイルに保存して、Node.jsで実行します。
>
> ```javascript theme={null}
> import OpenAI from "openai";
>
> // 環境変数からAPIキーを読み取り、LaoZhang APIのベースURLを指定する
> const client = new OpenAI({
>   apiKey: process.env.LAOZHANG_API_KEY,
>   baseURL: "https://api.laozhang.ai/v1",
>   timeout: 120_000,
>   maxRetries: 0,
> });
> const response = await client.chat.completions.create({
>   model: "gpt-5.4-mini",
>   messages: [{ role: "user", content: "「connected」とだけ返信してください" }],
> });
> console.log(response.choices[0].message.content);
> ```

これらの例ではSDKの自動リトライを無効にしています。リクエストを再送するタイミングは、アプリケーション側で決めるためです。

同じクライアントから、Responses、Images、Audio、Embeddings、Moderationsの各エンドポイントも呼び出せます。OpenAIの各モデルがどのエンドポイントを使うかは、`o3-pro`、GPT Image、音声モデルも含めて、[LaoZhang APIでOpenAIモデルを使う](https://docs.laozhang.ai/ja/api-reference/openai.md)にまとめています。

### 既存のOpenAIアプリを移行する

すでにOpenAI SDKを使っているアプリケーションで変更するのは、クライアントのAPIキーとベースURL、そして各リクエストの `model` の値の3点です。リクエストを組み立てる他のコードはそのまま使えます。クライアントの変更は次のとおりです。

```diff theme={null}
 client = OpenAI(
-    api_key=os.environ["OPENAI_API_KEY"],
+    api_key=os.environ["LAOZHANG_API_KEY"],
+    base_url="https://api.laozhang.ai/v1",
 )
```

SDKの設定を環境変数だけで行っているなら、コードを変えずに切り替えられます。OpenAIのPython SDKとNode.js SDKは、`OPENAI_API_KEY` と `OPENAI_BASE_URL` を読み取ります。

```bash theme={null}
export OPENAI_API_KEY="$LAOZHANG_API_KEY"
export OPENAI_BASE_URL="https://api.laozhang.ai/v1"
```

本番のトラフィックを流す前に、次の点を確認してください。

* **モデルID。** OpenAIで使えるモデル名でも、LaoZhang APIではIDやグループが異なる場合があります。正確なIDは[モデルと料金](https://docs.laozhang.ai/ja/models.md)からコピーしてください。OpenAIを直接呼び出す場合との違いは、[OpenAIモデルのガイド](https://docs.laozhang.ai/ja/api-reference/openai.md)にまとめています。
* **任意パラメーター。** サンプリングの設定、出力の上限、構造化出力、ツールの設定はモデルによって異なります。まず必須フィールドだけで送り、そのあと必要なオプションを足してください。未対応のパラメーターを示すエラーが返ったら、指摘されたフィールドを削除するか調整します。
* **リトライ。** リトライ処理は1か所にまとめてください。SDKとアプリケーションの両方が再送すると、1回の操作が複数のAPI呼び出しになります。
* **結果。** 上の最小リクエストを実行し、[呼び出しログ](https://api.laozhang.ai/log)でモデル、トークン使用量、課金額を確認してください。

元の環境に戻すときは、以前のAPIキーとベースURLに戻すだけです。

## Responses API

Responses APIはリクエストで `input` を受け取り、`output` 配列を返します。Chat Completionsとはリクエスト本文が異なるため、切り替えるアプリケーションはリクエストとレスポンスの解析の両方を更新する必要があります。

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 120 \
>   "https://api.laozhang.ai/v1/responses" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-5.4-mini",
>     "input": "「connected」とだけ返信してください"
>   }'
> ```

> [tab] Python
>
> 上でインストールした `openai` パッケージをそのまま使います。
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=120.0,
>     max_retries=0,
> )
> response = client.responses.create(
>     model="gpt-5.4-mini",
>     input="「connected」とだけ返信してください",
> )
> print(response.output_text)
> ```

生のJSONでは、`output` 配列の中で種類が `output_text` のコンテンツ項目から、`text` の値を集めます。SDKの `output_text` ヘルパーなら、この処理を任せられます。

`output` にはreasoningやツール呼び出しの項目も入るため、先頭の項目が回答のテキストとは限りません。

LaoZhang APIはOpenAIのResponses APIに対応しており、GPT-6、GPT-5.6、GPT-5.4、`o3-pro` などのOpenAIテキストモデルで使えます。他社のモデルをこのエンドポイントに切り替える前に、最小のリクエストを送って動作を確認してください。

サーバー側の会話状態、`previous_response_id`、組み込みツールもモデルによって異なります。会話履歴が必要なアプリケーションは、次のリクエストに必要なメッセージを自分で保持してください。上流のフィールド定義は[OpenAI Responsesリファレンス](https://developers.openai.com/api/reference/resources/responses/methods/create)、データの取り扱いは[データポリシー](https://www.laozhang.ai/data-policy)を参照してください。

## 画像の生成と編集

どちらのImagesエンドポイントも `data` 配列を返します。モデルによって、各項目には画像がBase64の `b64_json` として入るか、ダウンロード用リンクの `url` として入ります。

画像の例ではGPT Image 2.5 VIPのモデルを使います。これらは回数課金で、テキストの例は従量課金です。課金方式が従量優先のキーなら、両方を呼び出せます。画像リクエストが拒否されたときは、キーの[課金方式](https://docs.laozhang.ai/ja/pricing.md)が従量優先か、回数課金（コンソールの表示は「按次计费」）になっているか確認してください。

### 画像を生成する

生成エンドポイントに、JSONでプロンプトを送ります。

```bash theme={null}
curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-vip",
    "prompt": "白いテーブルの上に置かれた青い陶器のカップ。やわらかな自然光、商品写真。"
  }' \
  -o generation.json
```

### 画像を編集する

参照画像を `input.png` という名前でカレントディレクトリに置き、指示と一緒にmultipartフォームデータとしてアップロードします。

```bash theme={null}
curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2.5-sunburst-vip" \
  -F "image[]=@input.png" \
  -F 'prompt=背景を淡い青に変更してください。被写体はそのままにしてください。' \
  -o edit.json
```

`@` を付けると、ファイルの内容がアップロードされます。multipartのContent-Typeとboundaryは、cURLに任せてください。このリクエストには `Content-Type: application/json` を付けないでください。

### 結果を保存する

レスポンスのファイルは画像ではなくJSONです。次のスクリプトを `save_images.py` として保存してください。Pythonの標準ライブラリだけで動きます。

```python theme={null}
import base64
import json
import re
import sys
import urllib.request
from pathlib import Path

source = Path(sys.argv[1])
response = json.loads(source.read_text())
items = response.get("data") or []
if not items:
    sys.exit(f"{source} に画像が含まれていません: {response}")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        # data:image/...;base64, のプレフィックスを取り除き、不足している = を補う
        encoded = re.sub(r"^data:[^,]*,", "", item["b64_json"].strip())
        raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4))
    elif item.get("url"):
        # URLからのダウンロードにはAPIキーを付けない
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            raw = download.read()
    else:
        continue
    if raw.startswith(b"\x89PNG"):
        extension = "png"
    elif raw.startswith(b"\xff\xd8"):
        extension = "jpg"
    elif raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "bin"
    output = source.with_name(f"{source.stem}-{index}.{extension}")
    output.write_bytes(raw)
    print(f"保存しました: {output}")
```

どちらのレスポンスファイルにも使えます。

```bash theme={null}
python save_images.py generation.json
python save_images.py edit.json
```

スクリプトは `data` 内のすべての画像を、`generation-1.png` のような名前で保存します。次のケースに対応しています。

* Base64が `data:image/...;base64,` で始まる場合、または末尾の `=` パディングが足りない場合
* `url` で返された結果。APIキーを付けずにダウンロードします。URLの結果は早めに保存し、自分でもコピーを保管してください。

2つの操作のPython SDK例は、[Images APIリファレンス](https://docs.laozhang.ai/ja/api-reference/images.md)にあります。画像のサイズ、品質、出力形式はモデルによって異なります。これらを追加するときは、該当モデルのガイドを参照してください。

## GeminiネイティブAPIの呼び出し

GeminiのネイティブAPIは、OpenAIのmessagesではなく `contents[].parts[]` を使います。

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "「connected」とだけ返信してください"}]
    }]
  }'
```

テキストは `candidates[].content.parts[]` から読み取ります。テキストが含まれていない場合は、`finishReason` と `promptFeedback` を確認してください。

Google Gen AI SDKでは、ホストのルート `https://api.laozhang.ai` と `api_version="v1beta"` を指定します。モデルのパスとAPIキーのヘッダーは、SDKが付加します。[Geminiプロトコルのリファレンス](https://docs.laozhang.ai/ja/api-reference/gemini.md)には、Pythonの完全な例、2通りの認証ヘッダー、画像・PDF・音声を入力する手順があります。MP4動画のフレームと音声を分析するには、[動画理解API](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)を参照してください。

## Anthropic Messages APIの呼び出し

Anthropic SDKをはじめ、Anthropic Messages形式で作られたアプリケーションは、`/v1/messages` にリクエストを送ります。

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/messages" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "glm-5.2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "「connected」とだけ返信してください"}]
  }'
```

* **必須フィールド：** `model`、`messages`、`max_tokens` です。
* **システムプロンプト：** `messages` に入れず、トップレベルの `system` フィールドに指定します。
* **レスポンス：** `content` 配列には、`text`、`thinking`、`tool_use` のブロックが入ります。
* **回答テキスト：** 先頭のブロックが回答とは限らないため、`type` が `text` のブロックを読み取ります。

Messagesエンドポイントでは、[モデルと料金](https://docs.laozhang.ai/ja/models.md)でAnthropic Messagesと表示されているモデルを呼び出せます。

* 2026年10月18日から再び掲載しているClaudeモデル（`claude-sonnet-5-5`、`claude-opus-5-5` など）。Anthropic自身のAPIとの違いは、[Claudeモデルの制限](https://docs.laozhang.ai/ja/api-reference/claude.md)を参照してください。
* `default` トークングループで使える `glm-5.2`。Anthropic自身のMessages APIとほぼ同じ動作をします。
* `deepseek-v4-pro` と `deepseek-v4-flash` も、このエンドポイント向けに表示されています。

Anthropic Python SDKでは、`base_url="https://api.laozhang.ai"` とLaoZhang APIのキーを指定します。`/v1/messages` はSDKが付加します。SDK、ストリーミング、ツール呼び出しは、[Claudeプロトコルのリファレンス](https://docs.laozhang.ai/ja/api-reference/claude.md)にまとめています。

## その他のAPI操作

* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)：アプリケーションで使えるモデルIDを調べる
* [テキスト埋め込み](https://docs.laozhang.ai/en/api-capabilities/text-embedding.md)：テキストをベクトルに変換する
* [音声文字起こし](https://docs.laozhang.ai/en/api-capabilities/audio-transcription.md)：音声をアップロードして文字起こしを受け取る

## エラーへの対処

| ステータス | 確認すること |
| - | - |
| 400 | JSONの構文、フィールドの型、モデルのオプション、入力の長さ |
| 401 | APIキー、認証ヘッダー、キーの有効期限 |
| 403 | トークングループ、モデルの利用権限、アカウントの制限 |
| 404 | 最終的なURLと正確なモデルID。`/v1` が重複していないか確認 |
| 429 | エラー本文に、レート、同時実行数、処理能力、残高のどの制限が示されているか |
| 5xx またはタイムアウト | ネットワークの状態、モデルの稼働状況、呼び出しログ |

不正なリクエストは、再送する前に修正してください。一時的な障害には、上限付きのバックオフを使い、SDKのリトライとアプリケーションのリトライを重ねないようにします。

クライアント側のタイムアウトは、生成の取り消しを意味せず、課金されたかどうかも示しません。画像リクエストを再送する前に、[呼び出しログ](https://api.laozhang.ai/log)を確認してください。

サポートへの連絡は、[hi@laozhang.ai](mailto:hi@laozhang.ai) へのメール、またはTelegramの [@laozhang\_cn](https://t.me/laozhang_cn) への連絡で受け付けています。リクエストの時刻、モデル、エンドポイント、トークングループ、機密情報を伏せたエラー内容を添えてください。課金と返金は[利用規約](https://www.laozhang.ai/terms)に従います。

## AIコーディングツールでこのドキュメントを使う

コーディングアシスタントには、対象のモデルとタスクに加えて、次のいずれかのファイルを渡してください。

* [skill.md](https://docs.laozhang.ai/skill.md)：コーディングアシスタント向けの接続ルールと最小リクエスト集（英語）
* [llms.txt](https://docs.laozhang.ai/llms.txt) と [llms-full.txt](https://docs.laozhang.ai/llms-full.txt)：ドキュメントのページ一覧と全文エクスポート（どちらも現在は中国語のドキュメントが対象）

認証情報はプロンプトに貼り付けず、環境変数で渡してください。

## APIリファレンス

LaoZhang APIのリファレンスです。

* [テキスト生成API：プロトコルとモデルの選び方](https://docs.laozhang.ai/ja/api-capabilities/text-generation.md)
* [OpenAIモデル：エンドポイントとSDKの設定](https://docs.laozhang.ai/ja/api-reference/openai.md)
* [OpenAIプロトコル：Chat Completions](https://docs.laozhang.ai/ja/api-reference/chat-completions.md)
* [Claudeプロトコル：Anthropic Messages](https://docs.laozhang.ai/ja/api-reference/claude.md)
* [Geminiプロトコル：generateContent](https://docs.laozhang.ai/ja/api-reference/gemini.md)
* [Images API：画像の生成と編集](https://docs.laozhang.ai/ja/api-reference/images.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)

リクエストのフィールドとモデルの機能は、上流のリファレンスで定義されています。LaoZhang APIでのモデルID、利用条件、料金は、[モデルと料金](https://docs.laozhang.ai/ja/models.md)と[コンソール](https://api.laozhang.ai/account/pricing)で確認できます。

* OpenAI：[API reference](https://developers.openai.com/api/reference/overview)、[Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)、[Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)、[models](https://developers.openai.com/api/docs/models)
* Anthropic：[Messages API](https://platform.claude.com/docs/en/api/messages)
* Google：[Gemini API documentation](https://ai.google.dev/gemini-api/docs)と[generateContent reference](https://ai.google.dev/api/generate-content)

Alibaba Cloud、ByteDance、xAI、Black Forest Labs、DeepSeekなど各社の公式APIドキュメントは、[ベンダー別の公式APIドキュメント](https://docs.laozhang.ai/en/resources.md)にまとめています。各社とLaoZhang APIのガイドの対応も確認できます。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.