NezhaGateNezhaGate
网站公告全部公告 →
公告Seedance 2.5 · 30 秒近期成功率较低；按秒档限时 9 折 暂停Seedance 2.0 暂时不可用，推荐改用 Seedance 2.5 上新Seedance 2.5 开放 1080P：每秒 $0.33
简体中文 ✓EnglishEspañol한국어日本語Русский
登录 获取 API Key
文档
/

API 手册

⧉复制为 Markdown 📄查看 Markdown纯文本版，适合交给 AI 阅读 ✦在 ChatGPT 中打开 ✶在 Claude 中打开

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

基础地址

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

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

认证

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

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

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

管理 API Key →

接口一览

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

方法路径说明
POST/v1/chat/completions对话。全部对话模型可用，stream: true 时流式输出。
POST/v1/responsesOpenAI Responses 格式的对话（部分模型支持）。
POST/anthropic/v1/messagesClaude 原生 Messages 接口，支持流式、工具调用和提示缓存。
POST/anthropic/v1/messages/count_tokens计算一个 Messages 请求的 token 数。
GET/anthropic/v1/modelsClaude 模型列表（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_grantsOpenAI 风格的余额查询，余额在 total_available。

异步任务（图片与视频）

图片和视频接口提交后立刻返回 HTTP 202 和任务号，生成在后台进行。拿着任务号轮询结果，或者用 Webhook 等结果推送过来。

状态含义
queued排队中。返回里带 queue_position（前面还有几个任务）和 eta_seconds（预计等待秒数）。
processing生成中。
succeeded已完成。结果在 data[0].url，计费明细在 usage。
failed失败。原因在 error，预扣的积分已全额退回。
curl · 提交任务
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 · 查询任务
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 文档 →

模型列表

返回当前在售的全部模型 ID，格式与 OpenAI 相同。已下架的模型不在列表里；即将上线的模型会列出，但调用时返回 400 model_coming_soon。

curl · GET /v1/models
curl https://nezhagate.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
200 · JSON
{"object": "list", "data": [{"id": "gpt-5.5", "object": "model", "owned_by": "..."}, {"id": "claude-sonnet-5", "object": "model", "owned_by": "..."}]}

余额与用量

用任意一把 API Key 都能查询本账户的余额和消费，不需要登录控制台。

curl · GET /v1/usage
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
200 · JSON
{
  "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 · GET /v1/dashboard/billing/credit_grants
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"

错误格式

所有错误都用同一个结构。code 是稳定的机器可读标识，请按 code 判断，不要匹配 message 文本。

400 · JSON
{
  "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），维护期间暂停接单。

完整错误码列表 →

限流与重试

  • 账号默认不限制请求频率。每把 Key 可以在控制台单独设置每分钟请求数、每日预算、总额度、模型白名单和 IP 白名单。
  • 收到 429 时，按 Retry-After 头等待后重试；502、503 和超时可以用指数退避重试（例如等 1、2、4 秒）。
  • 失败的请求不计费。流式输出中途断开时，只按已经返回的用量结算。
  • 需要长期稳定的高并发，请提前联系我们，我们会按你的用量扩容。

SDK 与示例

不需要专门的 SDK：OpenAI 和 Anthropic 的官方 SDK 改一下 base_url 就能用。

Python · openai
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="")

更多可以直接运行的示例（Python、Node.js、curl，包括图片和视频的异步流程）： github.com/gaoorange/nezhagate-api-examples

各模型文档

每个模型都有单独的文档：参数取值、示例代码、返回格式和计费方式。

对话模型

图片模型

视频模型