# Gemini 3.8 Flash — /chat/completions

Gemini 3.8 Flash（Google）の対話 API です。3.8 世代の Flash モデルで、長時間にわたるコーディング、エージェントのワークフロー、複雑な推論向けに設計されています。動的思考（簡単な質問にはすばやく、難しい質問にはじっくり考えて回答）を備え、コンテキストウィンドウは約 100 万トークン、出力は最大 64K トークンで、画像入力に対応しています。OpenAI SDK 互換です。

**エンドポイント:** `POST https://nezhagate.com/v1/chat/completions`

## クイックスタート

2 ステップで動きます：まずリクエストを送信し、次にストリーミングで回答を受け取ります。YOUR_API_KEY をご自身のキーに置き換えれば、下のコマンドはそのまま実行できます。エンドポイントは OpenAI の Chat Completions と同じなので、既存の OpenAI のコードは `base_url` と `model` を変えるだけで使えます。

**ステップ 1 · リクエストを送信**

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "光合成を一文で説明してください"}]}'
```

レスポンス（HTTP 200）

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-3.8-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "光合成とは、植物が日光を使って二酸化炭素と水から糖をつくり、酸素を放出するしくみです。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60,
    "prompt_tokens_details": {"cached_tokens": 0}
  }
}
```

`message.content` が回答です。`usage` はこのリクエストで課金されるトークン数です。そのうち `prompt_tokens_details.cached_tokens` はキャッシュにヒットした分で、キャッシュ料金で課金されます。

**ステップ 2 · ストリーミングで受け取る（推奨）**

```
curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "stream": true, "messages": [{"role": "user", "content": "光合成を一文で説明してください"}]}'
```

ストリームは標準的な SSE です。各チャンクの本文は `choices[0].delta.content` に入り、最後のチャンクに `usage` が付き、`data: [DONE]` で終わります。回答が長い場合や思考モデルでは、ストリーミングを使ってください。ストリーミングしないリクエストは約 10 分で切断されます。

**Python（OpenAI SDK）**

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. 一問一答
resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "光合成を一文で説明してください"}],
)
print(resp.choices[0].message.content)

# 2. ストリーミング
stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "光合成を一文で説明してください"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 仕様早見表

| コンテキストウィンドウ | ~1,000,000 トークン |
| --- | --- |
| 1 回の最大出力 | 64K トークン |
| 入力 | テキスト、画像 |
| 思考 | 動的思考：どれだけ考えるかをモデルが決めます |
| ツール呼び出し | 保証なし：`tools` が無視され、モデルがそのまま回答することがあります |
| ウェブ検索 | 対応（`web_search: true`。検索自体は無料） |
| エンドポイント | /v1/chat/completions |
| ストリーミング | 対応（`stream: true`、SSE） |
| 課金方法 | トークン単位：入力、出力（思考を含む）、キャッシュヒットをそれぞれの料金で課金し、失敗は課金されません |

## リクエストパラメータ

`POST /v1/chat/completions` のリクエスト本文（JSON）で、OpenAI の Chat Completions と同じです。よく使うパラメータと、このモデルでの実際の動作は次のとおりです：

| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| model | string | はい | モデル ID：`gemini-3.8-flash`。 |
| messages | array | はい | 会話のメッセージの配列です。各メッセージは `role`（`system` / `user` / `assistant` / `tool`）と `content` を持ちます。`content` は文字列、または `text` と `image_url` のパーツからなる配列です（画像入力については下記を参照）。複数ターンの対話では、これまでの履歴をすべて順番どおりに送ってください。 |
| stream | boolean | いいえ | `true` にすると SSE でストリーミングし、最後のチャンクに `usage` が付きます。既定は `false` です。 |
| max_tokens | integer | いいえ | 出力の上限で、思考トークンも含みます。小さすぎると、モデルが回答を書く前に上限を使い切ることがあり、その場合ゲートウェイは 400 `max_tokens_too_small` を返し、課金はしません（512 以上を推奨）。一部のモデルでは、小さすぎる値は回答を最後まで書ける下限まで自動で引き上げられます。その場合も、課金は実際の使用量の分だけです。 |
| temperature / top_p | number | いいえ | サンプリングパラメータで、送ったとおりモデルに渡されます（`temperature` は 0〜2）。思考モデルでは反映されないことがあります。 |
| web_search | boolean | いいえ | `true` にすると、まずウェブ検索を行い、その結果を参考資料としてモデルに渡します。詳しくは下記をご覧ください。 |

そのほかの OpenAI のパラメータ（`stop`、`seed`、`user` など）は送ったとおりモデルに渡されます。反映されるかどうかはモデルによります。

## 料金

トークン単位で課金します。下の表は 100 万トークンあたりの最新の料金です。課金されるのは成功したリクエストの実際の使用量だけで、失敗、タイムアウト、拒否の場合は課金されません。1 クレジット = $0.005 です。

| 種類 | USD / 100 万トークン | クレジット / 100 万トークン |
| --- | --- | --- |
| 入力 | $0.60 | 120 |
| 出力（思考を含む） | $3.60 | 720 |
| キャッシュヒット | $0.06 | 12 |

たとえば、入力 2,000 トークン、出力 1,000 トークン（思考を含む）のリクエストは約 $0.0048 です。

## 思考

動的思考です。質問ごとにどれだけ考えるかをモデルが自分で決め、簡単な質問にはすばやく答え、難しい質問ではより深く考えます。追加のパラメータは不要です。思考トークンも出力の上限に含まれるため、`max_tokens` を小さくしすぎないでください。

思考トークンは `usage.completion_tokens` に含まれ、出力料金で課金されます（一部のモデルは `completion_tokens_details.reasoning_tokens` で内訳も返します）。

## プロンプトキャッシュ

パラメータは不要です。繰り返し送られる長い先頭部分（同じシステムプロンプトや、会話の前半のターンなど）は、モデル提供元によって自動でキャッシュされることがあり、キャッシュされた部分はより安いキャッシュ料金で課金されます。キャッシュされるかどうか、どれだけヒットするかはモデル提供元によります。変わらない部分をメッセージの先頭に置くと、ヒットしやすくなります。

キャッシュヒットしたトークン数は `usage.prompt_tokens_details.cached_tokens` で返ります。この部分はキャッシュヒット料金、残りの入力は入力料金で課金されます。

## 画像入力

`content` の配列に `image_url` のパーツを入れます。推奨は base64 の data URI（`data:image/png;base64,...`）で、確実に読み込めます。公開されている画像のリンクは先にダウンロードする必要があり、まれに取得できない、またはタイムアウトすることがあります。画像はモデル提供元の規則に従って入力トークンに換算されます。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": [{"type": "text", "text": "この画像には何が写っていますか"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'
```

## ウェブ検索

リクエストに `"web_search": true` を加えます（または `tools` に `{"type": "web_search"}` を入れます）。ゲートウェイはまず会話の内容をもとにウェブをリアルタイムで検索し、最大 5 件の結果とそのリンクを参考資料としてモデルに渡します。モデルはそれを踏まえて回答し、出典を示します。検索自体は無料で、参考資料は入力トークンとして課金されます。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "web_search": true, "messages": [{"role": "user", "content": "今日の主なテクノロジーニュースは何ですか"}]}'
```

## 安定性と自動再試行

- リクエストがエラーになったり、タイムアウトしたり、混み合っていたりすると、ゲートウェイは内容を返し始める前に自動で再試行します。再試行する必要はなく、二重に課金されることもありません。

- ストリーミングは、出力が始まった後は自動で再試行しません。途中で切れた場合は、切れるまでに生成された分が課金されます（[課金と返金](https://nezhagate.com/ja/docs/guide/billing) を参照）。

- モデルが混み合っているときは、ゲートウェイが `Retry-After` 付きで 429 を返します。その秒数だけ待ってから再試行してください。失敗したリクエストは課金されません。各モデルの状態は [サービス状態](https://nezhagate.com/ja/status) で確認できます。

## エラーと返金

エラーは `error` オブジェクト（`message`、`type`、`code`、`param`）で返ります。判定には HTTP ステータスコードと `code` を使い、`message` の文面では判定しないでください。失敗したリクエストは課金されません。完全な一覧は [エラーコード](https://nezhagate.com/ja/docs/guide/errors) をご覧ください。

| HTTP | code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | 対話リクエストの `messages` がない・空・形式が正しくない、`role` が許可された値ではない、または `max_tokens` が正の整数ではありません。`param` が該当するフィールドを示します。 | `param` が示すフィールドを直してください。 |
| 400 | model_not_found | モデル ID のつづりが違う・`model` がない・そのモデルをこのエンドポイントでは使えない（たとえば対話モデルで画像のエンドポイントを呼び出した）のいずれかです。 | `GET /v1/models` または [API リファレンス](https://nezhagate.com/ja/docs/api) にあるモデル ID を使ってください。 |
| 400 | max_tokens_too_small | 推論モデルが `max_tokens` をすべて思考に使い切り、回答を書けませんでした（ストリーミングしない対話）。 | `max_tokens` を増やしてから再試行してください。 |
| 400 | content_filter | モデルはリクエストを処理しましたが、何も返しませんでした。多くの場合、内容がモデル提供元の安全ポリシーに触れたためです。 | プロンプトを調整してから再試行してください。同じプロンプトのままでは、たいてい再び拒否されます。 |
| 4xx | invalid_request | モデル提供元がリクエストを拒否しました（コンテキストが長すぎる、対応していないパラメータがあるなど）。ステータスコードと `message` はモデル提供元が返したまま渡され、`code` はモデル提供元の値です。 | `message` の内容に沿ってリクエストを変更してください。 |
| 401 | invalid_api_key | キーが存在しない・削除された・無効化されているか、アカウントが停止されています。 | コンソールの「API Keys」ページでキーを確認してください。 |
| 402 | insufficient_quota | このリクエストの分を確保するだけの残高がありません。ゲートウェイはまずリクエストにかかりうる最大の費用を確保するため、同時に多くの呼び出しを送ったときにも起こることがあります。 | 一度に多くの呼び出しを送った直後なら、数秒待って再試行してください。そうでなければチャージしてください。 |
| 403 | permission_denied | そのモデルがキーのモデル許可リストに入っていません。 | 許可リストにあるモデルを使うか、コンソールで許可リストを変更してください。 |
| 429 | rate_limit_exceeded | このキーに設定した 1 分あたりのリクエスト数の上限を超えました（直近 60 秒で数えます）。`Retry-After` ヘッダーは付きません。 | 数秒待ってから再試行するか、コンソールでこのキーの上限を引き上げてください。 |
| 429 | rate_limit_exceeded | このモデルが混み合っていて、リクエストは送られませんでした。対話エンドポイントでのみ発生し、画像と動画のタスクは拒否されずに順番待ちになります。OpenAI 互換のエンドポイントでは `Retry-After` が付きます。 | `Retry-After` の秒数だけ待ってから再試行してください。 |
| 502 | upstream_timeout | 上流がタイムアウトしました（最初のトークンがなかなか返ってこない場合を含みます）。 | 再試行してください。長い回答には `stream: true` を使ってください。 |
| 502 | upstream_unavailable | 上流でエラーが起きたか、一時的に利用できません。 | しばらくしてから再試行してください。 |
| 502 | upstream_busy | モデル提供元がレート制限をかけています。モデル提供元の 429 をそのまま 429 として返すことはなく、代わりにこの 502 を返します。 | しばらくしてから再試行してください。 |
| 502 | empty_completion | モデル提供元が空の内容を返しました。リクエストの内容に対する判定ではありません。 | 再試行してください。 |
| 502 | upstream_prompt_filter | モデル提供元の事前チェックでプロンプトが止められました。モデルによる判定ではありません。 | しばらくしてから再試行するか、言い回しを少し変えてください。 |
| 503 | model_maintenance | モデルのメンテナンス中で、リクエストを受け付けていません。その間、別のモデルが代わりに回答することもありません。 | メンテナンスが終わってから再試行してください。状況は [サービス状態](https://nezhagate.com/ja/status) で確認できます。 |

ストリーミングで出力が始まった後にエラーが起きても、ステータスコードは変わりません。エラーは `error` を含むデータ行としてストリーム内に届くか、ストリームが（`data: [DONE]` なしで）そのまま終わります。いずれの場合も、途中で切れたものとして扱ってください。