快速开始 · API 指南 · 客户端接入
接入文档
选择你的工具，复制配置，开始第一次调用。
快速开始
客户端接入
API 指南
首次调用 API
先创建 API 密钥，再把接口地址填入客户端。
https://api.nowaterapi.xyz/v1不同客户端的完整配置参数
| 参数名称 | 配置值 | 适用场景与配置说明 |
|---|---|---|
base_urlOpenAI 兼容 | https://api.nowaterapi.xyz/ | 适用 Cherry Studio、NextChat、Chatbox、Cursor，以及 Python / Node SDK。 |
base_urlAnthropic 兼容 | https://api.nowaterapi.xyz | 仅针对 Claude Code 或 Anthropic 官方 SDK（注意：末尾不带 /v1） |
api_key | sk-... | 在账户中心一键创建并复制，请妥善保管，请勿泄露 |
model | gpt-6-sol / claude-sonnet-5 / grok-4.5 | 已验收型号和实际价格见 模型价格 |
替换下面的密钥并发送请求，收到回复即可确认基本调用正常。
curl https://api.nowaterapi.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 在这里粘贴你的密钥" \
-d '{
"model": "gpt-6-sol",
"messages": [{"role": "user", "content": "Hello! 请回复 OK"}]
}'获取 API 密钥
https://api.nowaterapi.xyz/v1sk-...（复制时已自动带前缀，末尾请勿带有空格）• Windows PowerShell：执行
[Environment]::SetEnvironmentVariable("NOWATER_API_KEY", "在这里粘贴你的密钥", "User")，然后重启终端。
• macOS / Linux：在终端执行
echo 'export NOWATER_API_KEY="在这里粘贴你的密钥"' >> ~/.zshrc && source ~/.zshrc。
错误码与排查
所有接口异常均会返回 JSON 格式的错误信息。请优先查看返回体中的 error.message 字段，它已经用人类可读的文字写明了原因。以下是高频问题与自查清单：
| 状态码 | 典型现象 | 推荐排查顺序 |
|---|---|---|
401 | 提示密钥无效、未授权或鉴权失败 | ① 检查复制的密钥是否以 sk- 开头；② 检查粘贴时前后是否多带了空格；③ 到账户中心确认该密钥是否未被停用；④ 检查请求头是否写成 Authorization: Bearer sk-...。 |
404 | 提示网址不存在或路径找不到 | 核心注意事项：检查接口地址 (Base URL) 末尾是否漏写了 /v1（或者误写成 /v1/v1）；若使用 Claude 官方协议，末尾不要带 /v1。 |
429 Quota / Rate | 提示余额不足或并发过高 | ① 登录账户中心查看钱包余额是否不足，及时前往钱包充值；② 若单 Key 设置了消费额度，可在密钥设置中调高上限；③ 适当降低瞬时并发请求。 |
400 | 提示参数格式错误或模型不存在 | ① 检查 model 字段拼写是否完全正确，对照模型页复制标准名称；② 检查 messages 数组 JSON 语法是否规范。 |
502 / 504 / 5xx | 网关暂时不可用或网络超时 | 通常为网络瞬时抖动或模型处理耗时较长，请稍等 5 秒后重试。若持续报错请联系客服。 |
API 端点与协议
| 能力 | 端点 | 状态 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | 已验证 |
| Responses API | POST /v1/responses | 已验证 |
| Anthropic Messages | POST /v1/messages | 基础消息已验证 |
| 图像生成 | POST /v1/images/generations | 已开放 |
| 图像编辑 | POST /v1/images/edits | 已开放 |
| 视频生成 | POST /v1/videos | 可提交，返回不稳定 |
| 模型列表 | GET /v1/models | 需密钥 |
文本与 Agent 工作流优先使用 Responses API；传统 OpenAI 兼容客户端使用 Chat Completions。图像模型应调用图像端点，不应放入聊天补全。
curl https://api.nowaterapi.xyz/v1/responses \
-H "Authorization: Bearer $NOWATER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6-sol","input":"Review this repository"}'思考模式
Claude 与 GPT 推理模型支持思考强度档位：low / medium / high / xhigh / max（GPT‑6 Astra 另有 ultra）。同一型号各档位价格一致；未填写或填写无效值时，网关自动按 high 处理，不会报错。
| 接口 | 写法 |
|---|---|
| Chat Completions | "reasoning_effort": "max" |
| Responses | "reasoning": {"effort": "max"} |
| Anthropic Messages | "output_config": {"effort": "max"} |
curl https://api.nowaterapi.xyz/v1/chat/completions \
-H "Authorization: Bearer $NOWATER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-fable-5-1","reasoning_effort":"max","messages":[{"role":"user","content":"证明根号 2 是无理数"}]}'各型号支持的档位以模型与价格页面标注为准。
流式输出
在 Chat Completions 请求中加入 "stream": true 即可启用 SSE。客户端应逐条读取 data: 事件，并在收到 [DONE] 后结束本次响应。
curl -N https://api.nowaterapi.xyz/v1/chat/completions \
-H "Authorization: Bearer $NOWATER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-6-sol","stream":true,"messages":[{"role":"user","content":"用一句话说明流式输出"}]}'多轮对话
Chat Completions 是无状态接口。应用需要保存本轮的助手消息，并在下一次请求中连同新的用户消息一起传入。长会话应设置历史裁剪或摘要策略，避免上下文无限增长。
messages = [
{"role": "user", "content": "广州有哪些适合周末参观的博物馆？"},
{"role": "assistant", "content": first_answer},
{"role": "user", "content": "只保留地铁可达的三个。"},
]工具调用
模型只负责选择工具并生成参数，不会替应用执行本地函数。应用必须校验参数、执行工具、按调用 ID 回传结果，再请求模型生成最终答复。完整回路见下方 Agent Harness。
使用 Anthropic API
调用 Claude 模型时，可以直接使用 Anthropic 官方 SDK 或任何兼容 Anthropic Messages 的客户端。base_url 填本站根地址（不带 /v1），密钥仍使用账户中心的 sk- 密钥：
| 参数 | 值 |
|---|---|
base_url | https://api.nowaterapi.xyz |
api_key | 账户中心创建的 sk- 密钥 |
model | claude-sonnet-5 / claude-opus-5 / claude-fable-5-1 等 |
import anthropic
client = anthropic.Anthropic(
api_key="在这里粘贴你的密钥",
base_url="https://api.nowaterapi.xyz",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
)
print(message.content)Claude Code 无需手写这些配置，见 Claude Code 接入。Claude 模型按官网标准 API 价格的 1.5 倍计费，输入 / 输出 / 缓存单价逐型号列在模型与价格页。
图像与视频
图像模型调用 POST /v1/images/generations（生成）和 POST /v1/images/edits（编辑），不要放进聊天补全接口。Grok 图像按张计费；GPT Image 按实际图像 Token 或按张结算，详见模型页。
curl https://api.nowaterapi.xyz/v1/images/generations \
-H "Authorization: Bearer $NOWATER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"grok-imagine-image-2.0","prompt":"一只在键盘上睡觉的橘猫，柔光","n":1}'文本生成视频目前只开放 480p，按秒计费。任务可以提交，但模型服务当前经常不返回可用结果。没有结果时不会结算，模型广场会写明原因。图像生成和图片编辑不受这一条影响。
Codex 接入
Codex CLI 与 Codex 桌面 App 都可以接入本站。推荐用 CC Switch 管理配置：它是跨平台桌面工具，切换供应商不需要手改配置文件，写入前会自动备份，全程不需要 GPT 或 ChatGPT 账号。
方式一 · CC Switch（推荐）
- 下载安装：Windows 用
.msi；macOS 运行brew install --cask cc-switch或下载.dmg；Linux 用.deb/.rpm/.AppImage。入口见 ccswitch.io 或 GitHub Releases。 - 打开 CC Switch，左侧切到 Codex，点右上角
+添加供应商，预设选「自定义」。 - 名称填
NoWater，Base URL 填https://api.nowaterapi.xyz/v1，API Key 填本站密钥。 - 点模型输入框旁的「获取模型」，它会用你的密钥调用
GET /v1/models自动列出可用模型；也可以直接手动填gpt-6-sol、grok-4.7。 - 保存后点该卡片的「启用」，重新打开终端，输入
codex即可使用。
在 Codex 里输入 /model 切换模型；想换回官方登录，在 CC Switch 里添加一个官方预设并切过去。
方式二 · Codex 桌面 App（Codex++）
如果你用的是 Codex 桌面 App，希望保留官方账号的插件市场能力、同时把模型请求转到本站，可以用 Codex++ 的「中转注入」。
- 下载安装 Codex++：Windows 用
-windows-x64-setup.exe；macOS 按芯片选macos-x64.dmg或macos-arm64.dmg。macOS 若提示「已损坏」，按项目说明执行xattr -rd com.apple.quarantine解除隔离。 - 打开「Codex++ 管理工具」→ 中转注入，确认已检测到 ChatGPT 登录状态。
- 添加一个中转配置：Base URL 填
https://api.nowaterapi.xyz/v1，Key 填本站密钥，然后点「应用中转注入」。 - 以后从 Codex++ 入口启动（不是原版 Codex），模型请求即走本站。
要回到官方登录态，在「中转注入」页面点「清除 API 模式」。
方式三 · 手动配置
不想安装额外工具时，直接写配置文件即可。先把本站密钥存成系统环境变量 NOWATER_API_KEY，再创建下面这个文件。
model_provider = "nowater" model = "gpt-6-sol" model_reasoning_effort = "high" [model_providers.nowater] name = "NoWater API" base_url = "https://api.nowaterapi.xyz/v1" env_key = "NOWATER_API_KEY" wire_api = "responses" requires_openai_auth = false
Windows 路径为 %USERPROFILE%\.codex\config.toml。保存后重新打开终端，输入 codex；模型可改成 gpt-6-astra、grok-4.7 等，也可以在 Codex 里用 /model 切换。
还没有安装 Codex CLI？
先按 Codex CLI 官方说明完成安装，并确认终端输入 codex --version 能显示版本号。不要先运行 codex login，直接按上面任一方式配置即可。
备用方案 · NoWater 一键配置脚本
不想安装 CC Switch 时，也可以运行我们提供的一键脚本：它会写入上面的配置并备份原文件，内置经过验证的模型目录（菜单 1 GPT‑5.6 Sol、2 GPT‑5.6 Terra、3 Grok 4.7、4 GPT‑6 Astra、5 GPT‑6 Sol、6 GPT‑6.1 Terra，9 还原）。
irm https://nowaterapi.xyz/setup/codex.ps1 | iex
bash <(curl -fsSL https://nowaterapi.xyz/setup/codex.sh)
Claude Code 接入
Claude Code 可以使用本站的 Claude、GPT 与 Grok 文本模型。推荐用 CC Switch 管理：它同时支持 Claude Code 与 Codex，一份配置两边复用，切换供应商不用改环境变量。
https://api.nowaterapi.xyz（不带 /v1）③ 模型名，日常编程建议 claude-sonnet-5。方式一 · CC Switch（推荐）
- 下载安装 CC Switch（同上一节）。
- 左侧切到 Claude Code，点
+添加供应商，预设选「自定义」。 - API Key 填本站密钥，端点地址填
https://api.nowaterapi.xyz；也可以点「获取模型」自动拉取。 - 保存后点「启用」。Claude Code 支持热切换，不需要重启终端。
方式二 · 环境变量（手动）
在 ~/.zshrc、~/.bashrc 或 Windows 用户环境变量里加入下面三行，然后重新打开终端。
export ANTHROPIC_BASE_URL="https://api.nowaterapi.xyz" export ANTHROPIC_AUTH_TOKEN="在这里粘贴你的密钥" export ANTHROPIC_MODEL="claude-sonnet-5"
换模型只改 ANTHROPIC_MODEL。改成 gpt-6-astra、grok-4.7 这类非 Claude 型号时，再加一行 export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1，否则 Claude Code 会按未知模型处理。
还没有安装 Claude Code？
先选择当前系统运行官方安装命令，安装完成后执行 claude --version；能看到版本号就可以继续配置。
irm https://claude.ai/install.ps1 | iex
curl -fsSL https://claude.ai/install.sh | bash
更多安装方式见 Claude Code 官方安装说明。
备用方案 · NoWater 一键配置脚本
脚本会先用你的密钥调用 GET /v1/models 校验密钥并读取当前可用的模型，再写入上面的环境变量。
irm https://nowaterapi.xyz/setup/claude-code.ps1 | iex
bash <(curl -fsSL https://nowaterapi.xyz/setup/claude-code.sh)
Cursor / Cline / Roo Code / Cherry Studio
支持自定义 API 的客户端与 IDE 插件都可以零代码接入。各软件入口命名略有差异，但核心参数完全相同——找不到专有入口时，选择 OpenAI Compatible 或「自定义 OpenAI」即可。
| 客户端 | 设置入口 | 接口地址 | 推荐模型 |
|---|---|---|---|
| Cherry Studio | 设置 → 模型服务 → OpenAI 兼容 | https://api.nowaterapi.xyz/ | GPT-6 Sol (gpt-6-sol) |
| Cursor | Settings → Models → Add Model | https://api.nowaterapi.xyz/ | Claude Sonnet 5 (claude-sonnet-5) |
| NextChat / Chatbox | 设置 → 模型服务商 OpenAI | https://api.nowaterapi.xyz/ | GPT-6 Sol (gpt-6-sol), Claude Sonnet 5 (claude-sonnet-5) |
| Cline / Roo Code | 插件设置 → API Provider | https://api.nowaterapi.xyz/ | Claude Sonnet 5 (claude-sonnet-5) |
API Key 统一使用账户中心创建的 sk- 密钥。OpenAI 兼容客户端的 Base URL 末尾必须带 /v1；Claude Code 除外（见上一节）。
客户端的模型列表没有自动下拉出现怎么办？
部分客户端的“从接口拉取模型列表”可能会因为网络环境或权限校验而不显示。这不代表接口不可用！你只需在客户端中点击「+ 添加模型 / Add model」，从我们的模型与价格页复制完整模型名（例如 gpt-6-sol 或 claude-sonnet-5）手动保存，即可立即正常调用。
为什么客户端测试时提示 404 Not Found？
99% 的原因是接口地址 (Base URL) 填错了：对于 OpenAI 兼容客户端，末尾必须带有 /v1（即 https://api.nowaterapi.xyz/v1），请检查是否漏掉了 /v1 或者客户端自己又追加了一次变成 /v1/v1。
OpenAI SDK
写程序时只需把官方 SDK 的 base_url 改为 NoWater，并从环境变量读取密钥。下面示例可以直接运行。
# Python python -m pip install --upgrade openai # Node.js npm install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOWATER_API_KEY"],
base_url="https://api.nowaterapi.xyz/v1",
)
response = client.responses.create(
model="gpt-5.6-sol",
input="Review this function",
)
print(response.output_text)import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.NOWATER_API_KEY,
baseURL: "https://api.nowaterapi.xyz/v1",
});
const result = await client.chat.completions.create({
model: "gpt-6-sol",
messages: [{ role: "user", content: "Reply with OK" }],
});
console.log(result.choices[0].message.content);Agent Harness 接入
Agent 的关键不是“发一次请求”，而是完成工具调用闭环：模型返回函数调用，Harness 执行本地工具，再把工具结果送回模型，直到得到最终答复。工具本身始终由你的程序执行。
使用 gpt-6-astra 时优先选择 /v1/responses。它支持流式输出、函数工具、MCP、计算机操作等能力；如果现有框架只有 Chat Completions，也可以先完成普通对话兼容，再把工具调用迁移到 Responses。
| Harness 类型 | 协议 | 配置重点 |
|---|---|---|
| Codex / GPT‑6 Responses Agent | /v1/responses | 设置 Provider、环境变量和 Responses wire API |
| OpenAI 兼容 Agent | /v1/chat/completions | 传入 tools，应用侧执行并回传结果 |
| Claude Code / Anthropic Harness | /v1/messages | 使用自定义网关变量，并逐项验证工具能力 |
messages = [{"role": "user", "content": "查询广州天气"}]
response = client.chat.completions.create(
model="gpt-6-astra",
messages=messages,
tools=tools,
)
message = response.choices[0].message
messages.append(message)
for call in message.tool_calls or []:
result = run_local_tool(call.function.name, call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": result,
})
final = client.chat.completions.create(
model="gpt-6-astra",
messages=messages,
tools=tools,
)相关协议可对照 OpenAI Responses API、DeepSeek Tool Calls 与 Claude Code 环境变量。
接入验收
- 在账户中心手动刷新模型，确认目标模型对当前账户可见。
- 发送最短非流式文本请求，确认鉴权和基础协议。
- 开启流式输出，确认客户端能完整读取事件流。
- 运行一个无副作用的函数工具，确认参数、调用 ID 和工具结果回传。
- 最后验证长任务、超时、重试和用量记录，再投入生产。
Grok 文本通道已完成最短非流式调用验证；投入长期或批量任务前，仍建议按上述步骤完成流式、工具调用与用量核对。
密钥与账户安全
- 每个项目创建独立密钥，设置额度和有效期；测试完成后及时停用。
- 不要把密钥写进 Git、截图、前端 JavaScript、公开日志或聊天记录。
- 服务端通过环境变量或密钥管理器读取密钥；浏览器应用应由自己的后端转发请求。
- 邮箱一经绑定不能用于第二个账户；密码重置只向唯一绑定邮箱发送。
- 发现异常用量时先停用对应密钥，再检查用量记录与登录设备，必要时修改密码并撤销其他会话。
常见问题
Codex 桌面 App 打开后还是要求登录 ChatGPT？
那是官方桌面 App 的账户界面，它负责账号与插件入口，第三方配置无法删除这个界面，也不要把 NoWater 密钥填进 ChatGPT 登录框。想完全跳过登录页，请改用 Codex CLI 配合 CC Switch（不需要 ChatGPT 账号）。
客户端的模型列表没有自动出现？
不代表接口不可用。点击客户端的“Add model / 添加模型”，从模型页复制完整模型名（例如 gpt-5.6-sol）手动保存即可。
提示 401 / 密钥无效？
按顺序检查：① 密钥是否完整复制（以 sk- 开头，无多余空格）；② 账户中心里该密钥是否被停用或已过有效期；③ 请求头是否为 Authorization: Bearer sk-...。都没问题就重建一个密钥。
哪个模型最便宜？第一次测试用哪个？
低成本文本测试可从 gpt-6.1-terra 开始。按任务需要选择模型，输入、缓存与输出单价见模型与价格页；模型详情内可估算标准档费用。
密钥忘了 / 泄露了怎么办？
在账户中心 → 密钥里点击“查看并复制”可随时取回完整密钥；怀疑泄露时直接删除该密钥并新建，旧密钥立即失效。也可以随时在账户安全页退出其他登录设备。
不想写代码，能直接试用模型吗？
可以。登录后打开模型广场，粘贴你的 API Key 即可在网页里聊天、画图和编辑图片。视频任务可以提交；没有返回结果时不会扣费，页面会写明原因。