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

# Chat Completions API：OpenAI形式の呼び出し方

> LaoZhang APIのテキストモデルをOpenAI Chat Completions形式で呼び出します。cURLとPythonの例、ストリーミング、レスポンスのフィールド、エラー対応をまとめています。

OpenAI、Google Gemini、DeepSeek、Qwenなど各社のテキストモデルを、OpenAI Chat Completionsという1つのインターフェースで呼び出せます。`messages` を送り、`choices[0].message.content` から回答を読み取ります。

| 項目 | 内容 |
| - | - |
| エンドポイント | `POST https://api.laozhang.ai/v1/chat/completions` |
| モデル | [モデルカタログ](https://docs.laozhang.ai/ja/models.md)の**Endpoints**にOpenAI-compatibleと表示されているモデル。`model` で指定する |
| ストリーミング | `"stream": true` を指定すると、生成された順に回答を受け取れる |
| 例のモデル | `gpt-5.4-mini` |

任意パラメーターとツールへの対応はモデルによって異なります。アプリケーションがAnthropic MessagesやGeminiの `generateContent` のリクエスト構造で作られている場合は、[Claudeプロトコル](https://docs.laozhang.ai/ja/api-reference/claude.md)または[Geminiプロトコル](https://docs.laozhang.ai/ja/api-reference/gemini.md)のページを参照してください。3つの形式の比較は、[テキスト生成API](https://docs.laozhang.ai/ja/api-capabilities/text-generation.md)のガイドにあります。

```text theme={null}
POST https://api.laozhang.ai/v1/chat/completions
```

## リクエストを送る

[トークン管理](https://api.laozhang.ai/token)でAPIキーを作成します。課金方式は、従量優先（推奨。コンソールの表示は「按量优先」）または従量課金（「按量计费」）にしてください。作成したキーは、ターミナルで環境変数に設定します。

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

リクエストは `Authorization: Bearer` で認証し、本文は `model` と `messages` を含むJSONにします。例では `gpt-5.4-mini` を使います。

> [tab] cURL
>
> ```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」とだけ返信してください"}
>     ]
>   }'
> ```

> [tab] Python
>
> `python -m pip install openai` でSDKをインストールします。
>
> ```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.chat.completions.create(
>     model="gpt-5.4-mini",
>     messages=[{"role": "user", "content": "「connected」とだけ返信してください"}],
> )
> print(response.choices[0].message.content)
> ```

このプロンプトなら、`connected` が返ります。クライアントの設定を確認できたら、プロンプトを自分のアプリケーションのメッセージに置き換えてください。

## モデルを選ぶ

モデルは[モデルカタログ](https://docs.laozhang.ai/ja/models.md)から選びます。`model` の値を変える前に、そのモデルの行で次の3点を確認してください。

* **Endpoints** にOpenAI-compatibleが含まれていること。`o3-pro` シリーズのようにResponsesだけが表示されているモデルは、代わりに `/v1/responses` を使います。[API接続ガイド](https://docs.laozhang.ai/ja/api-manual.md)のResponses APIの例を参照してください。
* **Token groups** に、自分のAPIキーのグループが含まれていること。
* 1Mトークンあたりの **Input**、**Output**、**Cache read** の価格が、用途に合っていること。

カタログにある代表的なテキストモデルは次のとおりです。

* `gpt-5.4-mini` と `gpt-5.4`
* `gemini-3.8-flash`、`gemini-3.6-flash`、`gemini-3.5-flash-lite`

モデルIDは、製品名から組み立てずに、カタログまたはコンソールから正確にコピーしてください。これらのモデルの形式と価格は[テキスト生成API](https://docs.laozhang.ai/ja/api-capabilities/text-generation.md)のガイドに、Responses専用の `o3-pro` の呼び出し方は[OpenAIモデル](https://docs.laozhang.ai/ja/api-reference/openai.md)にあります。

一般的なランキングだけでは、アプリケーションに合うモデルはわかりません。自分のプロンプトのサンプルを2〜3個の候補モデルに通し、次の点を比べてください。

* 回答の品質と、指示への従い方
* 構造化出力の安定性。ツールを使う場合は、ツール呼び出しの成功率も
* レイテンシと、各リクエストに記録されるトークン使用量

選んだモデルのIDは設定ファイルなどに固定し、モデルの変更を意図的な更新にしてください。

## リクエストのフィールド

| フィールド | 説明 |
| - | - |
| `model` | 必須。トークングループで利用できる正確なモデルID。 |
| `messages` | 必須。会話の順に並べたメッセージ。 |
| `stream` | 任意。`true` にするとserver-sent eventsで回答を返す。後述の「レスポンスをストリーミングする」を参照。 |
| `temperature`、`top_p` | 任意。サンプリングの制御。モデルが対応している場合のみ有効。 |
| `max_completion_tokens` | 出力の上限。このフィールドに対応するモデル向け。 |
| `max_tokens` | 一部のモデルが使う出力の上限。2つの上限フィールドは同時に送らない。 |
| `response_format` | JSONや構造化出力に対応するモデル向けの、出力形式の設定。 |
| `tools`、`tool_choice` | ツール呼び出しに対応するモデル向けの、ツール定義と選択の設定。 |

まずは `model` と `messages` だけで始めてください。任意フィールドと指定できる値はモデルによって異なります。未対応のパラメーターで拒否されたリクエストは、フィールドを直してから再送します。上流のフィールド定義は、[OpenAI公式のChat Completionsリファレンス](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)を参照してください。

### メッセージと会話履歴

各メッセージには `role` と `content` があります。ユーザーの入力は `user`、モデルの過去の回答は `assistant` で表します。アプリケーションに必要な履歴は、リクエストのたびに送ってください。

```json theme={null}
[
  {"role": "user", "content": "プロジェクト名はCedarです。"},
  {"role": "assistant", "content": "Cedarについて、どのようなお手伝いができますか？"},
  {"role": "user", "content": "短いキャッチコピーを提案してください。"}
]
```

`system` や `developer` などの指示用ロール、ツールメッセージ、マルチモーダルの内容は、選んだモデルによって異なります。ビジョンモデルに画像を送る方法は、[画像理解API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)を参照してください。

## レスポンスを読み取る

テキストのレスポンスには `choices` 配列が含まれます。読み取るフィールドだけを残した例です。

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "connected"},
      "finish_reason": "stop"
    }
  ]
}
```

回答は `message.content` から、生成が終わった理由は `finish_reason` から読み取ります。`finish_reason` が `length` なら、回答が出力上限またはコンテキスト上限に達しています。完全な回答が必要なときは、入力を短くするか、モデルが対応する出力上限を調整してください。

ツール呼び出しに対応するモデルでは、通常のテキストの代わりに `message.tool_calls` が返ることがあります。会話を続けるときは、その呼び出しと対応する結果を残してください。トークン数は `usage` に含まれることがあります。アカウントの課金額は、[呼び出しログ](https://docs.laozhang.ai/en/faq/call-logs.md)で確認します。

## レスポンスをストリーミングする

`"stream": true` を追加すると、モデルが書いた順に、回答を細かく分けて受け取れます。レスポンスはserver-sent eventsのストリームです。

* 各 `data:` 行に `chat.completion.chunk` オブジェクトが入ります。
* 新しいテキストは `choices[0].delta.content` に入ります。
* ストリームは `data: [DONE]` の行で終わります。

> [tab] cURL
>
> `-N` を付けると、cURLの出力バッファリングが無効になり、チャンクが届くたびに表示されます。
>
> ```bash theme={null}
> curl --fail-with-body -N --max-time 300 \
>   "https://api.laozhang.ai/v1/chat/completions" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-5.4-mini",
>     "stream": true,
>     "messages": [
>       {"role": "user", "content": "変数名を付けるときのコツを3つ、短く教えてください。"}
>     ]
>   }'
> ```

> [tab] Python
>
> ```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=300.0,
>     max_retries=0,
> )
> stream = client.chat.completions.create(
>     model="gpt-5.4-mini",
>     messages=[{"role": "user", "content": "変数名を付けるときのコツを3つ、短く教えてください。"}],
>     stream=True,
> )
> for chunk in stream:
>     if not chunk.choices:
>         continue
>     text = chunk.choices[0].delta.content
>     if text:
>         print(text, end="", flush=True)
> print()
> ```

生のストリームは次のような形です。必要なフィールドだけに省略しています。実際のチャンクには `id` や `model` などのフィールドも含まれます。

```text theme={null}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1. 変数名は"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

ストリームを読み取るときの注意点です。

* `delta.content` を順に連結すると、回答全体を再構成できます。
* 最初のチャンクにはロールだけが入っていることがあります。また、最後の使用量のチャンクなど、`choices` が空配列のチャンクもあるため、読み取る前に確認してください。
* 最後の内容チャンクに `finish_reason` が設定され、続く `data: [DONE]` でストリームが閉じます。Python SDKはこの時点でループを終了します。
* `[DONE]` の前に接続が切れた場合は、回答が途中で終わったものとして扱ってください。

## エラーへの対処

| ステータス | 対応 |
| - | - |
| 400 | 無効なフィールド、フィールドの型、モデルの上限を超える入力を修正する。 |
| 401 | Bearerヘッダーを確認し、APIキーを見直す。 |
| 403 | トークングループの権限と、アカウントの制限を確認する。 |
| 404 | エンドポイントと、正確なモデルIDを確認する。 |
| 429 | エラー本文で、レート、同時実行数、処理能力、残高のどの制限かを確認する。 |
| 5xx | 呼び出しログを確認し、一時的な障害は上限付きのバックオフで再試行する。 |

クライアント側でタイムアウトしたときは、再送する前に、そのリクエストが[呼び出しログ](https://api.laozhang.ai/log)に記録されているか確認してください。Pythonの例ではSDKの自動リトライを無効にしています。リトライ処理は、アプリケーション側で意図して実装してください。

サポートに連絡するときは、リクエストの時刻、エンドポイント、モデル、トークングループ、認証情報を伏せたエラーメッセージを添えてください。APIキーは送らないでください。

## 関連ドキュメント

* [テキスト生成API](https://docs.laozhang.ai/ja/api-capabilities/text-generation.md)
* [OpenAIモデル](https://docs.laozhang.ai/ja/api-reference/openai.md)
* [API接続ガイド](https://docs.laozhang.ai/ja/api-manual.md)
* [モデルカタログと料金](https://docs.laozhang.ai/ja/models.md)
* [画像理解API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)
* [モデルの提供状況と権限](https://docs.laozhang.ai/en/faq/model-availability.md)


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