# NezhaGate API 開発者ドキュメント

OpenAI 互換の AI API ゲートウェイ。Base URL: `https://nezhagate.com/v1`

## 認証
すべてのリクエストに Bearer トークンが必要です:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## モデルと料金
| モデル | 能力 | エンドポイント | 料金 |
| --- | --- | --- | --- |
| gpt-5.6-sol | 最前線の推論、エージェント型コーディング、長期タスク、構造化出力 | /chat/completions | 入力 $2.0/1M · 出力 $12.0/1M |
| gpt-5.6-terra | 日常のチャット、エージェント型コーディング、推論、構造化出力 | /chat/completions | 入力 $1.2/1M · 出力 $7.0/1M |
| gpt-5.6-luna | 高速なチャット、エージェント型コーディング、大量かつ低レイテンシ、構造化出力 | /chat/completions | 入力 $0.8/1M · 出力 $4.8/1M |
| gpt-5.5 | チャット、推論、エージェント、構造化出力 | /chat/completions | 入力 $0.7/1M · 出力 $4.2/1M |
| gpt-6-astra | 深い推論、エージェント型コーディング、非常に長いコンテキスト、画像入力、構造化出力 | /chat/completions | 入力 $2.8/1M · 出力 $14.0/1M |
| gpt-image-2 | テキストから画像、画像から画像、カバー、ポスター、イラスト | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | テキストから画像、画像から画像、カバー、ポスター、イラスト、文字組み | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-sunburst | テキストから画像、画像から画像、カバー、ポスター、イラスト、文字組み | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-2 | テキストから画像、画像から画像、カバー、ポスター、イラスト | /images/generations | 1K $0.025 · 2K $0.0375 · 4K $0.0625 |
| nano-banana-pro | テキストから画像、画像から画像、カバー、ポスター、イラスト、インフォグラフィック | /images/generations | 1K $0.04 · 2K $0.06 · 4K $0.1 |
| claude-sonnet-4-6 | チャット、コード、推論、長いコンテキスト | /chat/completions | 入力 $1.5/1M · 出力 $7.5/1M |
| claude-opus-5 | 深い推論、コード、エージェント、長いコンテキスト、画像理解 | /chat/completions | 入力 $4.0/1M · 出力 $20.0/1M |
| claude-fable-5 | 中国語の執筆、物語の創作、長文生成、チャット、コード、画像理解 | /chat/completions | 入力 $8.0/1M · 出力 $40.0/1M |
| gemini-3.1-pro | チャット、推論、非常に長いコンテキスト、マルチモーダル | /chat/completions | 入力 $0.5/1M · 出力 $3.0/1M |
| gemini-3.8-flash | チャット、推論、適応的な思考、画像入力、非常に長いコンテキスト | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3.7-flash | チャット、推論、適応的な思考、画像入力、非常に長いコンテキスト | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3.6-flash | チャット、推論、思考、画像入力、非常に長いコンテキスト | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3.6-flash-high | 深い推論、複雑なタスク、思考、画像入力、非常に長いコンテキスト | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3.6-flash-low | 高速なチャット、大量処理、低レイテンシ、画像入力 | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3.6-flash-tiered | 適応的な思考、チャット、推論、画像入力 | /chat/completions | 入力 $0.6/1M · 出力 $3.6/1M |
| gemini-3-flash-preview | チャット、推論、高い同時実行、低レイテンシ | /chat/completions | 入力 $0.3/1M · 出力 $1.2/1M |
| gemini-2.5-flash | チャット、高い同時実行、低レイテンシ、マルチモーダル | /chat/completions | 入力 $0.3/1M · 出力 $1.2/1M |
| veo-3.1 | テキストから動画、画像から動画、短編クリップ、商用映像 | /videos/generations | $0.075 / 本 · 近日公開、まだ呼び出せません |
| seedance-2.5 | 長回しの短編、複数参照素材の入力、商用映像 | /videos/generations | $0.632 / 本 |
| seedance-2.0 | 短編クリップ、商用素材 | /videos/generations | $0.6 / 本 |
| seedance-2.0-fast | 大量の素材制作、アイデアの素早い検証 | /videos/generations | $0.4 / 本 |
| seedance-2.0-mini | 大量の下書き、低コストの試行錯誤 | /videos/generations | $0.33 / 本 |
| wan3.0-video | 長回しの語り、複数素材の合成、動画の書き換え | /videos/generations | $0.18 / 本 |
| wan3.0-video-prime | 締め切りのある映像、まとめてのテスト撮影 | /videos/generations | $0.24 / 本 |
| minimax-h3 | 高精細な映像、音声付きの短編クリップ | /videos/generations | $0.18 / 本 |
| grok-imagine-video-1.5 | 大量の短尺動画、アイデアの素早い確認 | /videos/generations | $0.3 / 本 |

## チャット (Chat Completions)
`POST /v1/chat/completions`。`stream: true` でストリーミング出力になります。
```bash
curl https://nezhagate.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```
画像入力（ビジョン）: `messages` の `content` 配列に `image_url` を入れてください。公開画像のリンクでも、base64 の data URL でも構いません:
```bash
curl https://nezhagate.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":[{"type":"text","text":"この画像には何が写っていますか？"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## 画像生成 — 非同期ジョブ（送信するとジョブ ID が返ります）
画像エンドポイントは**ジョブ方式のみ**です。送信すると即座に `HTTP 202` とジョブ `id` が返り（`{"id":"img_...","object":"image.generation.job","status":"queued"}`）、`GET /v1/images/jobs/{id}` を `status` が `succeeded` になるまでポーリングして `data[0].url` を読みます（期限のない `img.nezhagate.com` のリンクです）。送信時のレスポンスに `data` が入ることを**期待しないでください**。
**テキストから画像**は `POST /v1/images/generations` です。**画像から画像**は `POST /v1/images/edits` を使うか、generations に `image` を加えます。どちらも同じ動きで、`image` には公開 URL、`data:` URI、base64 を渡せます。
```bash
# 1) 送信 -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"gpt-image-2","prompt":"a poster","size":"2:3"}'
# 2) status=succeeded になるまで 2〜3 秒ごとにポーリング、結果は data[0].url
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
`size` には画面比率（`1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9`）を渡すのがおすすめです。モデルはその比率で**ネイティブに描画**するため被写体が切れません。ピクセル指定（`1024x1024` / `1024x1536` / `1536x1024`）も受け付けます。テキストから画像でも画像から画像でも使えます。`async` フィールドはもう不要で、送っても無視されます。


## 動画生成 — 非同期ジョブ（送信するとジョブ ID が返ります）
動画もジョブ方式です。`POST /v1/videos/generations` を送ると即座に `HTTP 202` とジョブ ID が返り（`{"id":"img_...","object":"video.generation.job","status":"queued"}`）、`GET /v1/videos/jobs/{id}` を `status` が `succeeded` になるまでポーリングして `data[0].url` を読みます（再ホストした期限のない mp4 リンクです）。1 本あたり 1〜2 分、1 本ごとの課金で、失敗時は全額返金します。向きは `size` で決まり、`16:9` が横向き（既定）、`9:16` が縦向きです。画像から動画にする場合は `image` に最初のフレームとなる参照画像を渡してください。
```bash
# 1) 送信 -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"seedance-2.5","prompt":"夕暮れにサーフィンをする猫","size":"16:9","duration":"8s"}'
# 2) status=succeeded になるまで 5 秒ごとにポーリング、結果は data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
利用できる動画モデル: `seedance-2.5`、`seedance-2.0`、`seedance-2.0-fast`、`seedance-2.0-mini`、`wan3.0-video`、`wan3.0-video-prime`、`minimax-h3`、`grok-imagine-video-1.5`。
共通パラメータ: 向きは `size`（または `aspect_ratio`）、長さは `duration`、画質は `resolution`（対応するモデルのみ）で指定し、`image` / `images[]` に参照画像を渡すと、その画像を最初のフレームとする画像から動画になります。対応する長さと解像度はモデルごとに異なり、モデル別の表は `/docs/<モデル id>` にあります。例: [/docs/seedance-2.5](/docs/seedance-2.5)。

## ネイティブ Anthropic API（Claude Code から直接接続）
OpenAI 互換の経路に加えて、Claude モデルは**ネイティブの Anthropic Messages API** でも提供しています。Claude Code（または任意の Anthropic SDK）の `ANTHROPIC_BASE_URL` を `https://nezhagate.com/anthropic` に向け、ゲートウェイのキーを `x-api-key` として使ってください（`Authorization: Bearer` も動きます）。thinking、ツール呼び出し、プロンプトキャッシュはいずれもそのまま通ります。モデル: claude-opus-5、claude-fable-5、claude-sonnet-4-6。課金は /v1 とまったく同じトークン単位で、キャッシュの読み書きも含みます。
```bash
export ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://nezhagate.com/anthropic/v1/messages -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
`"stream": true` も標準的な Anthropic の SSE（message_start / content_block_delta / message_delta / message_stop）として利用でき、`/anthropic/v1/messages/count_tokens` と `GET /anthropic/v1/models` も使えます。
**プロンプトキャッシュの課金**: キャッシュヒット（読み取り）は入力単価の **1/10**（0.1x）、キャッシュ書き込みは **1.25x** で課金します（モデルごとの単価は[料金ページ](/pricing)をご覧ください）。ヒットには 3 つの条件が要ります。バイト単位で同一の接頭部、十分な長さ（Claude Opus は 4096 トークン以上、Sonnet は 2048 以上）、そして短い間隔での繰り返しです。大きな `CLAUDE.md` やシステムプロンプトを抱えた Claude Code で実際のコードベースを扱うと毎ターンヒットし、入力コストは約 10 分の 1 になります。プレイグラウンドの短いやり取りは短すぎてキャッシュされませんが、それが正常です。

## 残高の確認
どの API キーからでもアカウントの残高と消費額を読み取れます。管理画面へのログインは不要です:
```bash
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
OpenAI 互換（残高は `total_available` なので、一般的な残高照会ツールが自動で認識します）:
```bash
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## エラーコード
| ステータス | 意味 |
| --- | --- |
| 401 | API キーがない、または無効です |
| 402 | 残高不足、またはキーが上限を超えています |
| 400 | 対応していないモデルまたはパラメータです |
| 429 | 上流のレート制限です |
| 502 | すべての上流経路が失敗しました |