# NezhaGate API developer docs

OpenAI-compatible AI API gateway. Base URL: `https://nezhagate.com/v1`

## Authentication
Every request carries a Bearer token:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Models and pricing
| Model | Capability | Endpoint | Price |
| --- | --- | --- | --- |
| gpt-5.6-sol | Frontier reasoning, agentic coding, long-horizon tasks, structured output | /chat/completions | in $2.0/1M · out $12.0/1M |
| gpt-5.6-terra | Everyday chat, agentic coding, reasoning, structured output | /chat/completions | in $1.2/1M · out $7.0/1M |
| gpt-5.6-luna | High-speed chat, agentic coding, high-volume low-latency, structured output | /chat/completions | in $0.8/1M · out $4.8/1M |
| gpt-5.5 | Chat, reasoning, agents, structured output | /chat/completions | in $0.7/1M · out $4.2/1M |
| gpt-6-astra | Deep reasoning, agentic coding, very long context, image input, structured output | /chat/completions | in $2.8/1M · out $14.0/1M |
| gpt-image-2 | Text-to-image, image-to-image, covers, posters, illustrations | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | Text-to-image, image-to-image, covers, posters, illustration, typography | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-sunburst | Text-to-image, image-to-image, covers, posters, illustration, typography | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-2 | Text-to-image, image-to-image, covers, posters, illustrations | /images/generations | 1K $0.025 · 2K $0.0375 · 4K $0.0625 |
| nano-banana-pro | Text-to-image, image-to-image, covers, posters, illustrations, infographics | /images/generations | 1K $0.04 · 2K $0.06 · 4K $0.1 |
| claude-sonnet-4-6 | Chat, code, reasoning, long context | /chat/completions | in $1.5/1M · out $7.5/1M |
| claude-opus-5 | Deep reasoning, code, agents, long context, image understanding | /chat/completions | in $4.0/1M · out $20.0/1M |
| claude-fable-5 | Chinese writing, narrative creation, long-form generation, chat, code, image understanding | /chat/completions | in $8.0/1M · out $40.0/1M |
| gemini-3.1-pro | Chat, reasoning, very long context, multimodal | /chat/completions | in $0.5/1M · out $3.0/1M |
| gemini-3.8-flash | Chat, reasoning, adaptive thinking, image input, very long context | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.7-flash | Chat, reasoning, adaptive thinking, image input, very long context | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash | Chat, reasoning, thinking, image input, very long context | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-high | Deep reasoning, complex tasks, thinking, image input, very long context | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-low | High-speed chat, high volume, low latency, image input | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-tiered | Adaptive thinking, chat, reasoning, image input | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3-flash-preview | Chat, reasoning, high concurrency, low latency | /chat/completions | in $0.3/1M · out $1.2/1M |
| gemini-2.5-flash | Chat, high concurrency, low latency, multimodal | /chat/completions | in $0.3/1M · out $1.2/1M |
| veo-3.1 | Text-to-video, image-to-video, short clips, commercial footage | /videos/generations | $0.075 / clip · coming soon, not callable yet |
| seedance-2.5 | Long-take short films, multi-reference input, commercial footage | /videos/generations | $0.632 / clip |
| seedance-2.0 | Short clips, commercial assets | /videos/generations | $0.6 / clip |
| seedance-2.0-fast | Bulk assets, quick concept checks | /videos/generations | $0.4 / clip |
| seedance-2.0-mini | High-volume drafts, low-cost iteration | /videos/generations | $0.33 / clip |
| wan3.0-video | Long-take storytelling, multi-asset composition, video rewriting | /videos/generations | $0.18 / clip |
| wan3.0-video-prime | Deadline footage, batch test shoots | /videos/generations | $0.24 / clip |
| minimax-h3 | HD footage, short clips with sound | /videos/generations | $0.18 / clip |
| grok-imagine-video-1.5 | Bulk short videos, quick concept checks | /videos/generations | $0.3 / clip |

## Chat (Chat Completions)
`POST /v1/chat/completions`, with `stream: true` for streaming output.
```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"}]}'
```
Image input (vision): put an `image_url` in the `content` array of `messages` -- a public image link or a 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":"What is in this picture?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## Images — async jobs (submitting returns a job id)
The image endpoints are **job-only**: submitting returns `HTTP 202` and a job `id` right away (`{"id":"img_...","object":"image.generation.job","status":"queued"}`); poll `GET /v1/images/jobs/{id}` until `status` is `succeeded` and read `data[0].url` (a stable `img.nezhagate.com` link). Do **not** expect `data` on the submit response.
**Text-to-image** is `POST /v1/images/generations`. **Image-to-image** is `POST /v1/images/edits`, or add `image` to generations -- the two are equivalent; `image` takes a public URL, a `data:` URI or base64.
```bash
# 1) submit -> 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) poll every 2-3s until status=succeeded, result in data[0].url
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
For `size`, pass an aspect ratio -- `1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9` -- and the model renders **natively** at that ratio with no subject cropping; pixel sizes (`1024x1024` / `1024x1536` / `1536x1024`) are accepted too. Both text-to-image and image-to-image support it. The `async` field is no longer needed and is ignored if sent.


## Videos — async jobs (submitting returns a job id)
Video is a job too: `POST /v1/videos/generations` returns `HTTP 202` and a job id immediately (`{"id":"img_...","object":"video.generation.job","status":"queued"}`); poll `GET /v1/videos/jobs/{id}` until `status` is `succeeded` and read `data[0].url` (a re-hosted, stable mp4 link). About 1-2 minutes per clip, billed per clip, refunded in full on failure. Orientation comes from `size`: `16:9` landscape (default) or `9:16` portrait; for image-to-video pass a first-frame reference in `image`.
```bash
# 1) submit -> 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":"a cat surfing at sunset","size":"16:9","duration":"8s"}'
# 2) poll every 5s until status=succeeded, result in data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Video models available: `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`.
Shared parameters: `size` (or `aspect_ratio`) for orientation, `duration` for length, `resolution` for quality where the model supports it, and `image` / `images[]` for a reference frame, which makes it image-to-video. Supported durations and resolutions differ per model; the exact table for each is at `/docs/<model id>`, e.g. [/docs/seedance-2.5](/docs/seedance-2.5).

## Native Anthropic API (Claude Code connects directly)
Beyond the OpenAI-compatible route, Claude models also expose the **native Anthropic Messages API**. Point `ANTHROPIC_BASE_URL` in Claude Code (or any Anthropic SDK) at `https://nezhagate.com/anthropic` and use your gateway key as `x-api-key` (`Authorization: Bearer` works too). Thinking, tool use and prompt caching all pass through unchanged. Models: claude-opus-5, claude-fable-5, claude-sonnet-4-6. Billed exactly like /v1, per token, cache reads and writes included.
```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` is supported as standard Anthropic SSE (message_start / content_block_delta / message_delta / message_stop), along with `/anthropic/v1/messages/count_tokens` and `GET /anthropic/v1/models`.
**Prompt-cache billing**: a cache hit (cache read) bills at **1/10** of the input rate (0.1x) and a cache write at **1.25x** (per-model rates on the [pricing page](/pricing)). A hit needs three things: a byte-identical prefix, a long enough one (Claude Opus >= 4096 tokens, Sonnet >= 2048), and the same prefix repeated within a short window. Claude Code with a large `CLAUDE.md` or system prompt over a real codebase hits every turn and pays about a tenth for input; the short exchanges in the Playground are too small to cache, which is expected.

## Check your balance
Any API key can read the account balance and spend -- no dashboard login needed:
```bash
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
OpenAI-compatible (balance = `total_available`, so the usual balance-checking tools pick it up automatically):
```bash
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Error codes
| Status | Meaning |
| --- | --- |
| 401 | API key missing or invalid |
| 402 | Insufficient balance or key over quota |
| 400 | Unsupported model or parameter |
| 429 | Upstream rate limit |
| 502 | All upstream routes failed |