# GPT-6 Astra — /chat/completions

GPT-6 Astra（OpenAI）の対話 API です。GPT-6 ファミリーのフラッグシップで、コンテキストウィンドウは 105 万トークン、1 回の出力は最大 128,000 トークン、思考の深さは low から max までの 5 段階で調整でき、画像入力、ツール呼び出し、JSON 出力に対応しています。OpenAI SDK 互換で、/v1/responses でも呼び出せます。

**エンドポイント:** `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": "gpt-6-astra", "messages": [{"role": "user", "content": "光合成を一文で説明してください"}]}'
```

レスポンス（HTTP 200）

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

`message.content` が回答、`message.reasoning_content` が思考の内容です。`usage` はこのリクエストで課金されるトークン数で、思考トークンは `completion_tokens` に含まれ、出力料金で課金されます。

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

```
curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "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="gpt-6-astra",
    messages=[{"role": "user", "content": "光合成を一文で説明してください"}],
)
print(resp.choices[0].message.content)

# 2. ストリーミング
stream = client.chat.completions.create(
    model="gpt-6-astra",
    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,050,000 トークン |
| --- | --- |
| 1 回の最大出力 | 128,000 トークン |
| 入力 | テキスト、画像 |
| 思考 | `reasoning_effort` に応じて思考します（省略時は medium）。思考の要約は `reasoning_content` で返ります |
| ツール呼び出し | 対応（OpenAI の `tools` 形式） |
| JSON 出力 | 対応（`response_format`） |
| ウェブ検索 | 対応（`web_search: true`。検索自体は無料） |
| エンドポイント | /v1/chat/completions · /v1/responses |
| ストリーミング | 対応（`stream: true`、SSE） |
| 課金方法 | トークン単位：入力、出力（思考を含む）、キャッシュヒットをそれぞれの料金で課金し、失敗は課金されません |

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

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

| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| model | string | はい | モデル ID：`gpt-6-astra`。 |
| messages | array | はい | 会話のメッセージの配列です。各メッセージは `role`（`system` / `user` / `assistant` / `tool`）と `content` を持ちます。`content` は文字列、または `text` と `image_url` のパーツからなる配列です（画像入力については下記を参照）。複数ターンの対話では、これまでの履歴をすべて順番どおりに送ってください。 |
| stream | boolean | いいえ | `true` にすると SSE でストリーミングし、最後のチャンクに `usage` が付きます。既定は `false` です。 |
| max_tokens | integer | いいえ | このモデルは出力の上限を受け付けません。`max_tokens` / `max_completion_tokens` は無視されます（エラーにはなりません）。短い回答がほしい場合は、プロンプトで指示してください。 |
| temperature / top_p | number | いいえ | このモデルはサンプリングパラメータを受け付けません。指定しても無視されます（エラーにはなりません）。 |
| reasoning_effort | string | いいえ | 思考の深さ：low / medium / high / xhigh / max。既定は medium です。段階が高いほど長く慎重に考えますが、その分時間がかかり、出力トークンも増えます。`gpt-6-astra-high` のように、モデル ID の末尾に付けて指定することもできます。 |
| tools / tool_choice | array / string | いいえ | OpenAI 標準形式の関数呼び出しです。モデルが関数を呼び出すときは `finish_reason: "tool_calls"` と `tool_calls` を返します。詳しくは下記をご覧ください。 |
| response_format | object | いいえ | `{"type": "json_object"}` にすると、モデルは正しい JSON だけを出力します。プロンプトでも、JSON で出力することと、どのフィールドが必要かを明記してください。 |
| web_search | boolean | いいえ | `true` にすると、まずウェブ検索を行い、その結果を参考資料としてモデルに渡します。詳しくは下記をご覧ください。 |

`frequency_penalty` と `presence_penalty` も同様に無視されます。そのほかの OpenAI のパラメータは、送ったとおりモデルに渡されます。

## 料金

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

| 種類 | USD / 100 万トークン | クレジット / 100 万トークン |
| --- | --- | --- |
| 入力 | $3.00 | 600 |
| 出力（思考を含む） | $15.00 | 3000 |
| キャッシュヒット | $0.30 | 60 |

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

## 思考

`reasoning_effort` には low / medium / high / xhigh / max を指定できます。省略すると、ゲートウェイは medium でリクエストします。段階が高いほど長く考えて回答が安定しますが、その分時間がかかり、出力トークンも増えます。簡単な質問なら low で十分です。

思考の要約は `message.reasoning_content`（ストリーミング時は `delta.reasoning_content`）で返ります。段階はモデル ID の末尾に付けて `gpt-6-astra-low`、`gpt-6-astra-high`、`gpt-6-astra-xhigh` のように指定することもでき、効果は同じで、`gpt-6-astra` として課金されます。

/v1/responses では、思考の深さを `reasoning.effort` で指定します。要約が返るのは `reasoning.summary` を自分で指定した場合だけです（ゲートウェイは自動で追加しません）。

思考トークンは `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": "gpt-6-astra", "messages": [{"role": "user", "content": [{"type": "text", "text": "この画像には何が写っていますか"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'
```

## ツール呼び出し（Function Calling）

`tools` に JSON Schema で関数を記述します。モデルが関数を呼び出すと判断したときは `finish_reason: "tool_calls"` を返し、`message.tool_calls` に関数名と引数（JSON 文字列）が入ります。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "上海の今の天気はどうですか"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'
```

関数を実行したら、その結果を `role: "tool"` のメッセージとして、対応する `tool_call_id` を付けて会話に追加し、もう一度リクエストを送ってください。モデルはそれをもとに最終的な回答を返します。`tool_choice` には `auto`、`none`、`required`、または特定の関数を指定できます。

## Responses API（/v1/responses）

このモデルは OpenAI の Responses API でも呼び出せます。Codex などのツールが使っているのがこの API です。リクエストとレスポンスは OpenAI の Responses 形式に従い、入力は `input`、思考の深さは `reasoning.effort` で指定します。

```
curl https://nezhagate.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "input": "光合成を一文で説明してください", "reasoning": {"effort": "medium", "summary": "auto"}}'
```

このエンドポイントでは、ゲートウェイが既定の思考の深さを付け加えることはなく、要約も自動では返りません。要約が必要な場合は、上の例のように `"summary": "auto"` を送ってください。課金は対話エンドポイントと同じです。ウェブ検索は /v1/chat/completions でのみ使えます。

## ウェブ検索

リクエストに `"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": "gpt-6-astra", "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` を増やしてから再試行してください。 |
| 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 | モデル提供元が空の内容を返しました。リクエストの内容に対する判定ではありません。 | 再試行してください。 |
| 503 | model_maintenance | モデルのメンテナンス中で、リクエストを受け付けていません。その間、別のモデルが代わりに回答することもありません。 | メンテナンスが終わってから再試行してください。状況は [サービス状態](https://nezhagate.com/ja/status) で確認できます。 |

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