# API 手册

所有接口共用一把 API Key 和同一个余额。对话兼容 OpenAI 与 Anthropic 两种格式，图片和视频以异步任务运行。

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

## 基础地址

按你使用的 SDK 选择地址。两个地址共用同一把 Key、同一个余额。

| 协议 | 地址 | 适用于 |
| --- | --- | --- |
| **OpenAI 兼容** | `https://nezhagate.com/v1` | 对话、Responses、图片、视频、模型列表、余额 |
| **Anthropic 原生** | `https://nezhagate.com/anthropic` | Claude 模型的 Messages 接口（Claude Code、Anthropic SDK） |

### 认证

每个请求都在请求头里带上 API Key。Key 在控制台的「API Keys」页面创建，创建时只显示一次。

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

Anthropic 接口用 `x-api-key` 请求头，也接受 `Authorization: Bearer`。

## 接口一览

以下路径都在 `https://nezhagate.com` 之下。同步接口直接返回结果，图片和视频接口返回任务号。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/v1/chat/completions` | 对话。全部对话模型可用，`stream: true` 时流式输出。 |
| POST | `/v1/responses` | OpenAI Responses 格式的对话（部分模型支持）。 |
| POST | `/anthropic/v1/messages` | Claude 原生 Messages 接口，支持流式、工具调用和提示缓存。 |
| POST | `/anthropic/v1/messages/count_tokens` | 计算一个 Messages 请求的 token 数。 |
| GET | `/anthropic/v1/models` | Claude 模型列表（Anthropic 格式）。 |
| POST | `/v1/images/generations` | 文生图。立刻返回任务号（HTTP 202）。 |
| POST | `/v1/images/edits` | 图生图。也可以在上一个接口里带 `image` 参数，两者等价。 |
| GET | `/v1/images/jobs/{id}` | 查询图片任务的状态与结果。 |
| POST | `/v1/videos/generations` | 生成视频。立刻返回任务号（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 和任务号，生成在后台进行。拿着任务号轮询结果，或者用 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`，任务结束后会把和查询接口一样的结果推送到这个地址。 [Webhook 文档 →](https://nezhagate.com/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 Key 都能查询本账户的余额和消费，不需要登录控制台。

```
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` 是稳定的机器可读标识，请按 `code` 判断，不要匹配 `message` 文本。

```
{
  "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** | 没带 Key，或 Key 无效、已停用（`missing_api_key`、`invalid_api_key`）。 |
| **402** | 余额不足，或这把 Key 达到了预算上限（`insufficient_quota`）。 |
| **403** | 这把 Key 的模型白名单里没有这个模型。 |
| **404** | 任务号不存在，或不属于这把 Key（`job_not_found`）。 |
| **429** | 触发限流，或这个模型的所有线路都已满载。按 `Retry-After` 头的秒数等待后重试。 |
| **502** | 上游出错或超时（`upstream_error`）。没有计费，可以重试。 |
| **503** | 模型维护中（`model_maintenance`），维护期间暂停接单。 |

[完整错误码列表 →](https://nezhagate.com/docs-guide#errors)

## 限流与重试

- 账号默认不限制请求频率。每把 Key 可以在控制台单独设置每分钟请求数、每日预算、总额度、模型白名单和 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/docs/gpt-5.6-sol)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 图片模型

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

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

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

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

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

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

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

### 视频模型

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

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

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

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

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

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

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

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

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

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

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