ZNNZ · API 使用文档

这站的目标很直接：让你少折腾，买完 Key 就能调模型。

不管你是写代码的，还是只会在客户端里填 API 地址的，都按这份文档走就行。真正关键的章节我已经写细了；涉及你个人运营口径的地方，我先用“像你说话”的草稿补上，你后面改几个事实即可。

1. 先看这个

你可以把它理解成一个统一入口（已实测：Chat / Responses / Messages / Gemini）：

• 接口地址：https://api.znnz.net（兼容 https://api.znnz.net/v1）
• 密钥：首页购买 / 领取后立刻给你
• 计费：按用量扣余额
• 查询：邮箱查订单，Key 查余额

2. 购买 / 领取

2.1 买正式密钥

1. 打开 主页
2. 输入金额（美元面值）
3. 填写邮箱（以后查订单用，不是登录账号）
4. 如果有渠道选择，就选你要的渠道
5. 点「立即购买」，扫码支付
6. 成功后保存：Key、接口地址、余额

2.2 领免费密钥

• 入口：主页「免费密钥」
• 有有效期（当前大约 15 天）
• 模型可能受限，额度通常不大
• 到期前续费，会转成正式密钥

2.3 支付成功后你拿到什么

3. 接口基础

4. 鉴权

所有业务接口都要带 Key：

同一个 Key 全站共用（余额池也共用）。按客户端习惯任选一种写法：

Authorization: Bearer sk-你的密钥

x-api-key: sk-你的密钥

x-goog-api-key: sk-你的密钥

curl https://api.znnz.net/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

• OpenAI / 多数客户端：优先 Authorization: Bearer
• Anthropic 风格：可用 x-api-key
• Gemini 风格：可用 x-goog-api-key 或 ?key=
• 别漏 Bearer 、别多空格、别把邮箱当 Key
• 免费 Key 过期会直接不能用

5. 对话接口（最常用）

接口：POST /v1/chat/completions

5.1 最小请求

curl https://api.znnz.net/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-4o-mini\",
    \"messages\": [{\"role\":\"user\",\"content\":\"你好\"}],
    \"stream\": false
  }"

5.2 字段说明

5.3 Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.znnz.net",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

5.4 Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.znnz.net",
});

const resp = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

6. 模型列表

GET /v1/models

curl https://api.znnz.net/models \
  -H "Authorization: Bearer sk-你的密钥"

• 想看价格：回主页模型广场
• 想看好不好用：看可用性灯条 + 自己实测
• 免费 Key：只能用领取时允许的模型

7. 兼容能力

目标是尽量兼容 OpenAI 风格接口，最稳的是对话。其他路径会尽量转发，但最终取决于上游支不支持。

• /chat/completions 与 /v1/chat/completions：主力（OpenAI Chat）
• /models 与 /v1/models：列表
• /responses 与 /v1/responses：OpenAI Responses
• /messages 与 /v1/messages：Anthropic Messages（取决于上游）
• /models/{model}:generateContent：Gemini（取决于上游）
• 其他路径：能转就转，不保证所有上游都全

统一入口说明

• 只记一个地址：https://api.znnz.net（兼容 /v1）
• 四种协议走同一主机、同一 Key、同一余额
• 是否“原教旨完整可用”，最终取决于你绑定的上游渠道（NewAPI / Sub2API 等）
• 日常对话优先用 OpenAI Chat Completions，兼容性最好

OpenAI Responses 示例

curl https://api.znnz.net/responses \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "你好"
  }'

也兼容 /v1/responses。

Anthropic Messages 示例

curl https://api.znnz.net/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"你好"}]
  }'

也可用 Authorization: Bearer；短地址 /messages 同样兼容。

Gemini GenerateContent 示例

curl "https://api.znnz.net/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"你好"}]}]
  }'

也兼容 /models/{model}:generateContent。服务端策略：优先原样透传；失败或跨族时自动适配（含 Gemini/Anthropic/Responses → Chat 兜底并尽量包装回原协议），便于在 CCS / Claude Code / Codex 中切换更多模型。

8. 计费说明

• 余额按美元计
• usage 模型按 token 扣
• count 模型按次扣
• 不同渠道挂牌价可能不同（Key 绑渠道，挂牌价 = 基础价 × 渠道 K2）

四种协议，一个余额池

记住一句话：换协议不换 Key，换路径不换余额。流式 / 非流式都进同一本账。

扣费怎么走

1. 请求开始：先预扣一点，防止并发打穿
2. 请求结束：按真实 usage（或估算）结算
3. 多扣的退回，只留真实消费
4. 余额不足：返回续费提示（带站点地址）

什么时候会估算

• 上游没回 usage，但请求已成功
• 部分媒体 / 特殊路径本来就更适合按次
• 估算偏保守，避免“白嫖成功请求”

余额不够时，接口会提示你去站点续费。

9. 渠道说明

买 Key 时如果出现渠道选择，说明当前开了多个可选渠道。

• 你选哪个，Key 就绑哪个
• 后续调用按绑定渠道走
• 续费默认不换渠道
• 想换渠道，通常重新买更干净

10. 查询与续费

查询订单

主页点「查询订单」，输入邮箱，查历史购买记录。

查询密钥

主页点「查询密钥」，输入完整 Key，可看余额、已用、渠道、使用明细，以及近 24 小时 tokens。

续费密钥

• 正式 Key：填 Key + 金额即可
• 免费 Key：续费时补邮箱，成功后转正
• 续费成功会提示到账金额和最新余额

11. 客户端接入

不会配时按这个顺序查

1. 先测 /v1/models
2. 再测最小对话请求
3. 核对模型名有没有多写少写
4. 检查 Base URL 带不带 /v1
5. 还不行，把状态码和错误信息留下

常见客户端怎么填

Cherry Studio / ChatBox（最省事）

1. 供应商类型选 OpenAI / OpenAI Compatible
2. API 地址填 https://api.znnz.net（软件要求带 v1 就填 https://api.znnz.net/v1）
3. API Key 填你的 sk-...
4. 模型名去首页模型广场复制，别手打错字
5. 先发一句 “hi” 小测；能回就说明通路通了

11.1 CCS / 多协议切换（重点）

如果你用的是 CCS、CC Switch，或其它“一套配置切 Claude / GPT / Gemini”的工具，按下面记就够了。

只记 3 个固定值

按协议切换时，只换路径

推荐配置顺序

1. 先用 OpenAI Chat 测通（兼容性最高）
2. 再在 CCS 里加 Claude 配置（Messages）
3. 最后加 Gemini 配置（GenerateContent）
4. 三套配置共用同一 Key；余额在本站「查询密钥」里一起看

12. 错误码

13. 常见问题

我不是程序员，能用吗？

能。会在客户端里填地址和 Key 就行。

Key 丢了怎么办？

用购买邮箱去查订单。所以邮箱一定要填对，支付成功页也建议截图保存。

免费 Key 和正式 Key 差在哪？

• 免费：有期限，模型可能受限
• 正式：余额制，通常永久
• 免费续费成功后转正式

模型广场灯条是什么？

是后台探活后的可用性展示，方便你顺眼看看状态。最终还是以你实际调用为准。

一个 Key 能同时给 GPT / Claude / Gemini 用吗？

能。同一把 Key、同一个余额池。客户端按协议换路径即可，不必重复购买。

接口地址到底带不带 /v1？

两种都行：https://api.znnz.net 和 https://api.znnz.net/v1 等价。软件要求带就带，不要求就不带。

14. 安全建议

• Key 别发群，别截图发朋友圈
• 别把 Key 写进公开仓库
• 浏览器前端裸奔 Key 很容易被刷
• 正经业务建议走你自己的后端
• 发现异常消费，先停用再联系处理

15. 站长补充草稿（你重点改这里）

下面这些我已经按你的语气写好了初稿。你只需要改“事实”，不用从零写。

1. 品牌定位：少折腾、买了就能用
2. 推荐模型：先稳后强，按预算选
3. 渠道差异：默认 / 优质 / 优惠
4. 免费策略：先体验，再续费
5. 扣费口径：成功调用计费，异常可查
6. 能力边界：对话优先，其他按上游
7. 客户端 / CCS：文字教程已写，截图位待你补
8. 售后联系：你填真实联系方式
9. 企业合作：按量级谈，不空谈最低价
10. 使用边界：合法用途，禁止滥用