ZNNZ · API 使用文档

ZNNZ · API 的目标很直接：让你少折腾，这份文档会教你取得 Key 就能使用这个世界上最屌的AI，最屌的客户端。

。这份文档是我让AI写的，写的太乱了，我后面会针对小白与开发者重写。

1. 先看这个

你可以把它理解成一个统一入口：

获取密钥：首页充值 / 领取免费密钥后会立刻返回您的KEY
接口地址：https://api.znnz.net/v1
可用模型：直接看模型广场
模型价格：直接看模型广场标价
使用详情：查询密钥，粘贴KEY后查询，页面会实时刷新KEY的使用记录。

我不搞花里胡哨的会员体系，也不逼你先注册一堆账号。你就两件事：拿 Key、调接口。模型要全一点，价格尽量老实，用着顺手最重要。谁爱折腾谁去折腾，我这边尽量让你少踩坑。

3. 接口基础

项目	值
站点	`https://znnz.net`
API Base URL	`https://api.znnz.net/v1`
风格	OpenAI Compatible
鉴权	`Authorization: Bearer sk-xxx`
数据格式	JSON（少数文件接口可能 multipart）

兼容坑：有的软件要带 /v1，有的软件别带。填 https://api.znnz.net/v1；个别客户端不兼容时再试去掉末尾 /v1。

4. 鉴权

所有业务接口都要带 Key：

Authorization: Bearer sk-你的密钥

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

别漏 Bearer
别多空格、别换行
别把邮箱当成 Key
免费 Key 过期了会直接不能用

5. 对话接口（最常用）

接口：POST /v1/chat/completions

5.1 最小请求

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

5.2 字段说明

字段	必须	说明
`model`	是	模型名，按模型广场填写
`messages`	是	对话内容
`stream`	否	是否流式输出
`temperature`	否	创造性
`max_tokens`	否	最大输出长度

5.3 Python

from openai import OpenAI

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

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/v1",
});

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/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

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

7. 兼容能力

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

/v1/chat/completions：主力
/v1/models：列表
其他 /v1/*：能转就转，不保证所有上游都全

【支持边界草稿】
对话我尽量保证好用。图片、语音、文件这类能力，上游支持我就转，不支持我也变不出魔法。你要是有明确刚需，先小额测试，通了再上生产，别一上来就重资产梭哈。

8. 计费说明

余额按美元计
usage 模型按 token 扣
count 模型按次扣
不同渠道挂牌价可能不同

扣费怎么走

请求开始：先预扣一点，防止并发打穿
请求结束：按真实 usage（或估算）结算
多扣的退回，只留真实消费

【扣费口径草稿】
正常成功的调用会扣费。上游已经真实消耗了的，也不可能让系统装没看见。如果你遇到“明显异常扣费”，把时间和 Key 前几位发我，我查日志。别一上来就公开完整 Key。

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

9. 渠道说明

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

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

【渠道介绍草稿】
默认渠道：日常主力，先用这个准没错。
优质渠道：更看重稳定性/体感时再考虑，价格可能更高。
优惠渠道：更看价格，高峰期波动你得自己有预期。
一句话：你要省心就默认，你要极致再挑别的。

10. 查询与续费

查询订单

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

查询密钥

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

续费密钥

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

11. 客户端接入

配置项	填什么
API Base URL	`https://api.znnz.net/v1`
API Key	你的 `sk-...`
Model	模型广场里的名字

不会配时按这个顺序查

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

【客户端教程草稿】
后面我会按实际测过的软件补图文：ChatBox、Cherry Studio、LobeChat 这些。原则就一个：能填自定义 OpenAI 地址的，基本都能接。先把 Base URL 和 Key 填对，比研究软件皮肤重要。

12. 错误码

HTTP	意思	你怎么处理
`401`	Key 无效/没带	检查 Authorization
`402`	余额不足	去续费
`403`	模型不允许	换模型，或续费转正
`410`	Key 过期	重新领，或到期前续费
`429`	请求太快	降并发，稍后重试
`502`	上游异常	稍后重试
`503`	渠道不可用	联系站长

13. 常见问题

我不是程序员，能用吗？

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

Key 丢了怎么办？

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

免费 Key 和正式 Key 差在哪？

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

模型广场灯条是什么？

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

【商务/售后草稿】
个人用直接线上买就行。企业要是要更大额度、单独渠道、对公或发票，先把需求说清楚，我按实际情况回你。别一上来甩一句“给我最低价”，至少告诉我用量级和要哪些模型。

售后联系方式这里先占位：（邮箱 / TG / QQ / 微信，你自己填）。服务时间也建议写清楚，比如“白天在线，深夜看缘分”。

14. 安全建议

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

【使用边界草稿】
正常学习、开发、办公、业务接入没问题。违法违规、诈骗、攻击、挖矿式滥用这些别来。被发现会限流、封 Key，情节严重直接处理，不浪费口舌。

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

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

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

【你现在最少要改的 3 项】
1）售后联系方式
2）是否支持发票/对公
3）你最推荐新手用的 1~2 个模型名