# API リファレンス

すべてのエンドポイントで同じ API キーと同じ残高を使います。対話は OpenAI と Anthropic の両方の形式に対応し、画像と動画は非同期タスクとして処理されます。

> https://nezhagate.com/ja/docs/api

## ベース URL

お使いの SDK に合わせて選んでください。どちらも同じキー、同じ残高で使えます。

| プロトコル | ベース URL | 用途 |
| --- | --- | --- |
| **OpenAI 互換** | `https://nezhagate.com/v1` | 対話、Responses、画像、動画、モデル一覧、残高 |
| **Anthropic ネイティブ** | `https://nezhagate.com/anthropic` | Claude モデルの Messages API（Claude Code、Anthropic SDK） |

### 認証

すべてのリクエストで、ヘッダーに API キーを付けて送ります。キーはコンソールの「API Keys」ページで作成し、作成時に一度だけ表示されます。

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Anthropic のエンドポイントは `x-api-key` ヘッダーを使い、`Authorization: Bearer` も受け付けます。

## エンドポイント一覧

パスはすべて `https://nezhagate.com` の下にあります。同期エンドポイントは結果を返し、画像・動画のエンドポイントはタスク ID を返します。

| メソッド | パス | 説明 |
| --- | --- | --- |
| POST | `/v1/chat/completions` | 対話。すべての対話モデルで使え、`stream: true` でストリーミングします。 |
| POST | `/v1/responses` | OpenAI Responses 形式の対話（一部のモデル）。 |
| POST | `/anthropic/v1/messages` | Claude ネイティブの Messages API。ストリーミング、ツール呼び出し、プロンプトキャッシュに対応。 |
| POST | `/anthropic/v1/messages/count_tokens` | Messages リクエストのトークン数を数えます。 |
| GET | `/anthropic/v1/models` | Claude モデルの一覧（Anthropic 形式）。 |
| POST | `/v1/images/generations` | テキストから画像。すぐにタスク ID を返します（HTTP 202）。 |
| POST | `/v1/images/edits` | 画像から画像。上のエンドポイントに `image` を渡しても同じです。 |
| GET | `/v1/images/jobs/{id}` | 画像タスクの状態と結果を取得します。 |
| POST | `/v1/videos/generations` | 動画を生成。すぐにタスク ID を返します（HTTP 202）。 |
| GET | `/v1/videos/jobs/{id}` | 動画タスクの状態と結果を取得します。 |
| GET | `/v1/models` | 販売中のモデル一覧（OpenAI 形式）。 |
| GET | `/v1/usage` | 残高、累計と今日の利用額、モデル別の利用状況。 |
| GET | `/v1/dashboard/billing/credit_grants` | OpenAI 形式の残高照会。残高は `total_available` にあります。 |

## 非同期タスク（画像と動画）

画像と動画の呼び出しは、すぐに HTTP 202 とタスク ID を返し、生成はバックグラウンドで進みます。ID でポーリングするか、Webhook で結果を受け取ってください。

| ステータス | 意味 |
| --- | --- |
| `queued` | 順番待ち。`queue_position`（前にあるタスク数）と `eta_seconds`（予想待ち時間）が付きます。 |
| `processing` | 生成中。 |
| `succeeded` | 完了。結果は `data[0].url`、課金の内訳は `usage` にあります。 |
| `failed` | 失敗。理由は `error` にあり、予約したクレジットは全額返金されます。 |

```
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2", "prompt": "a lighthouse at dawn, watercolor", "size": "16:9"}'

# HTTP 202
{"id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "nano-banana-2"}
```

```
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791199400,
  "model": "nano-banana-2",
  "data": [{"url": "https://img.nezhagate.com/i/9f86d081a8....png"}],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2"}
}
```

- 画像は 2〜3 秒ごと、動画は 5〜10 秒ごとのポーリングをおすすめします。ポーリング自体は無料です。

- `data[0].url` は当社のメディアホスト上のリンクで、60 日間保存した後に削除されます。残したいものはダウンロードしてください。

- 送信時に `callback_url` を付けると、タスク終了時にポーリングと同じ結果がその URL に送られます。 [Webhook のドキュメント →](https://nezhagate.com/ja/docs/webhooks)

## モデル一覧

販売中のすべてのモデル ID を OpenAI と同じ形式で返します。提供終了したモデルは含まれません。近日公開のモデルは一覧に出ますが、公開までは 400 `model_coming_soon` を返します。

```
curl https://nezhagate.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
```

```
{"object": "list", "data": [{"id": "gpt-5.5", "object": "model", "owned_by": "..."}, {"id": "claude-sonnet-5", "object": "model", "owned_by": "..."}]}
```

## 残高と利用状況

どの API キーでも、アカウントの残高と利用額を照会できます。コンソールへのログインは不要です。

```
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "object": "usage",
  "balance": {"usd": 12.5, "credits": 2500},
  "total": {"cost_usd": 37.5, "requests": 1840, "billed_requests": 1822, "failed_requests": 18},
  "today": {"cost_usd": 1.2, "requests": 64, "billed_requests": 63, "failed_requests": 1},
  "by_model": [
    {"model": "gpt-5.5", "cost_usd": 20.1, "requests": 900, "billed_requests": 896, "failed_requests": 4,
     "prompt_tokens": 1520000, "completion_tokens": 410000, "image_count": 0}
  ]
}
```

`balance.usd` は米ドルでの残高、`balance.credits` は同じ残高のクレジット換算です（1 ドル = 200 クレジット）。

既存の残高確認ツールに対応させたいときは、OpenAI 形式のエンドポイントを使います。残高は `total_available` です。

```
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## エラー形式

すべてのエラーは同じ構造です。`code` は変わらない機械可読の識別子なので、`message` の文面ではなく `code` で判定してください。

```
{
  "error": {
    "message": "Model not enabled: gpt-9",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}
```

| HTTP | 発生する場面 |
| --- | --- |
| **400** | パラメータの誤り、または存在しないモデル（`model_not_found` など）。`error.param` が該当フィールドを示します。 |
| **401** | キーがない、または無効・停止中（`missing_api_key`、`invalid_api_key`）。 |
| **402** | 残高不足、またはキーが予算の上限に達しました（`insufficient_quota`）。 |
| **403** | このキーのモデル許可リストに、そのモデルが入っていません。 |
| **404** | タスクが存在しないか、別のキーのタスクです（`job_not_found`）。 |
| **429** | レート制限、またはこのモデルのすべての回線が混み合っています。`Retry-After` ヘッダーの秒数だけ待ってから再試行してください。 |
| **502** | 上流でのエラーまたはタイムアウト（`upstream_error`）。課金されないので、そのまま再試行できます。 |
| **503** | モデルのメンテナンス中（`model_maintenance`）。終わるまで受け付けを止めています。 |

[エラーコードの完全な一覧 →](https://nezhagate.com/ja/docs-guide#errors)

## レート制限と再試行

- アカウントには既定のリクエスト頻度の制限はありません。コンソールで、キーごとに 1 分あたりのリクエスト数、1 日の予算、合計の利用上限、モデル許可リスト、IP 許可リストを設定できます。

- 429 を受け取ったら、`Retry-After` ヘッダーの時間だけ待ってから再試行してください。502、503、タイムアウトは指数バックオフ（例：1 秒、2 秒、4 秒）で再試行できます。

- 失敗したリクエストは課金されません。ストリーミングが途中で切れた場合は、返ってきた分だけを精算します。

- 高い同時実行数を継続して使う予定があれば、事前にご連絡ください。利用量に合わせて容量を増やします。

## SDK とサンプル

専用の SDK は不要です。OpenAI と Anthropic の公式 SDK は `base_url` を変えるだけで使えます。

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")
```

```
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://nezhagate.com/v1", apiKey: "YOUR_API_KEY" });
const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);
```

```
import anthropic

client = anthropic.Anthropic(base_url="https://nezhagate.com/anthropic", api_key="YOUR_API_KEY")
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)
```

そのまま動くサンプルをもっと見る（Python、Node.js、curl。画像・動画の非同期フローを含む）： [github.com/gaoorange/nezhagate-api-examples](https://github.com/gaoorange/nezhagate-api-examples)

## 各モデルのドキュメント

モデルごとに専用ページがあります。パラメータの取りうる値、サンプルコード、レスポンス形式、課金方法をまとめています。

### 対話モデル

- [GPT-5.6 Sol](https://nezhagate.com/ja/docs/gpt-5.6-sol)

- [GPT-5.6 Terra](https://nezhagate.com/ja/docs/gpt-5.6-terra)

- [GPT-5.6 Luna](https://nezhagate.com/ja/docs/gpt-5.6-luna)

- [GPT-5.5](https://nezhagate.com/ja/docs/gpt-5.5)

- [GPT-6 Astra](https://nezhagate.com/ja/docs/gpt-6-astra)

- [GPT-6.1 Sol](https://nezhagate.com/ja/docs/gpt-6.1-sol)

- [GPT-6 Sol](https://nezhagate.com/ja/docs/gpt-6-sol)

- [GPT-6 Luna](https://nezhagate.com/ja/docs/gpt-6-luna)

- [Claude Sonnet 4.6](https://nezhagate.com/ja/docs/claude-sonnet-4-6)

- [Claude Opus 5](https://nezhagate.com/ja/docs/claude-opus-5)

- [Claude Fable 5](https://nezhagate.com/ja/docs/claude-fable-5)

- [Claude Sonnet 5](https://nezhagate.com/ja/docs/claude-sonnet-5)

- [Claude Opus 5.5](https://nezhagate.com/ja/docs/claude-opus-5-5)

- [Claude Sonnet 5.5](https://nezhagate.com/ja/docs/claude-sonnet-5-5)

- [Gemini 3.1 Pro](https://nezhagate.com/ja/docs/gemini-3.1-pro)

- [Gemini 3.8 Flash](https://nezhagate.com/ja/docs/gemini-3.8-flash)

- [Gemini 3.7 Flash](https://nezhagate.com/ja/docs/gemini-3.7-flash)

- [Gemini 3.6 Flash](https://nezhagate.com/ja/docs/gemini-3.6-flash)

- [Gemini 3.6 Flash High](https://nezhagate.com/ja/docs/gemini-3.6-flash-high)

- [Gemini 3.6 Flash Low](https://nezhagate.com/ja/docs/gemini-3.6-flash-low)

- [Gemini 3.6 Flash Tiered](https://nezhagate.com/ja/docs/gemini-3.6-flash-tiered)

- [Gemini 3 Flash](https://nezhagate.com/ja/docs/gemini-3-flash-preview)

- [Gemini 2.5 Flash](https://nezhagate.com/ja/docs/gemini-2.5-flash)

- [DeepSeek V4.1 Flash](https://nezhagate.com/ja/docs/deepseek-v4.1-flash)

- [DeepSeek V4 Flash 0731](https://nezhagate.com/ja/docs/deepseek-v4-flash-0731)

- [GLM-5.3](https://nezhagate.com/ja/docs/glm-5.3)

- [GLM-5.3 Flash](https://nezhagate.com/ja/docs/glm-5.3-flash)

- [Kimi K3](https://nezhagate.com/ja/docs/kimi-k3)

- [Qwen3.7 Max](https://nezhagate.com/ja/docs/qwen3.7-max)

- [Qwen3.8 Max](https://nezhagate.com/ja/docs/qwen3.8-max)

- [Qwen3.8 Max 0902](https://nezhagate.com/ja/docs/qwen3.8-max-0902)

- [Qwen3.8 Flash](https://nezhagate.com/ja/docs/qwen3.8-flash)

- [Doubao Seed 2.1 Pro](https://nezhagate.com/ja/docs/doubao-seed-2-1-pro)

- [Doubao Seed 2.1 Turbo](https://nezhagate.com/ja/docs/doubao-seed-2-1-turbo)

- [Grok 4.7](https://nezhagate.com/ja/docs/grok-4.7)

### 画像モデル

- [GPT Image 2](https://nezhagate.com/ja/docs/gpt-image-2)

- [GPT Image 2.5 Flare](https://nezhagate.com/ja/docs/gpt-image-2.5-flare)

- [GPT Image 2.5 Sunburst](https://nezhagate.com/ja/docs/gpt-image-2.5-sunburst)

- [Nano Banana 2](https://nezhagate.com/ja/docs/nano-banana-2)

- [Nano Banana Pro](https://nezhagate.com/ja/docs/nano-banana-pro)

- [Grok Imagine Image](https://nezhagate.com/ja/docs/grok-imagine-image)

- [Grok Imagine Image Quality](https://nezhagate.com/ja/docs/grok-imagine-image-quality)

### 動画モデル

- [Veo 3.1](https://nezhagate.com/ja/docs/veo-3.1)

- [Gemini Omni Flash](https://nezhagate.com/ja/docs/gemini-omni-flash)

- [Seedance 2.5](https://nezhagate.com/ja/docs/seedance-2.5)

- [Seedance 2.0](https://nezhagate.com/ja/docs/seedance-2.0)

- [Seedance 2.0 Fast](https://nezhagate.com/ja/docs/seedance-2.0-fast)

- [Seedance 2.0 · Clip](https://nezhagate.com/ja/docs/seedance-2.0-clip)

- [Seedance 2.5 · 30s](https://nezhagate.com/ja/docs/seedance-2.5-30s)

- [Wan 3.0](https://nezhagate.com/ja/docs/wan3.0-video)

- [Wan 3.0 Prime](https://nezhagate.com/ja/docs/wan3.0-video-prime)

- [MiniMax H3](https://nezhagate.com/ja/docs/minimax-h3)

- [Grok Imagine Video 1.5](https://nezhagate.com/ja/docs/grok-imagine-video-1.5)