纳雪接入文档
https://api.xxxiai.com/status/guide.html
接入文档
打开独立阅读版（软件搜索、代码复制与模板下载） ↗
从第一条对话开始。配置常用软件，连接编程助手，
或用熟悉的 API 把模型接入你的应用。
OpenAI 兼容 Base URLhttps://api.xxxiai.com/v1
快速开始
准备好三个信息：接入地址、纳雪 API Key、完整模型 ID。
登录纳雪，确认账户有可用额度
在控制台查看余额或订阅，并通过“充值购买”补充额度。
创建 API Key，选择要使用的分组
进入 API 密钥，为所需线路创建密钥。Key 绑定的分组决定模型权限与计费倍率。
填写地址和 Key，选一个支持的模型
从分组说明或模型列表复制完整 ID，先发一条简短消息；确认收到完整回复后，再配置工具调用等功能。
模型 ID ≠ 分组名称。例如“科研专线”是分组说明，调用时需要填该分组实际提供的模型 ID。更换模型系列时，请同时检查 Key 所属分组。
地址与密钥
配置位置 | 填写内容 |
OpenAI / 兼容客户端 Base URL | https://api.xxxiai.com/v1 |
Claude Code / Anthropic SDK Base URL | https://api.xxxiai.com |
API Key | 你在纳雪创建的密钥，原样填写 |
模型 | 当前 Key 对应分组支持的完整模型 ID |
若软件自动添加 /v1，只填 https://api.xxxiai.com。如果填写项叫“完整接口地址”，请使用下表中的完整路径。
用途 | 完整请求地址 |
查询 Key 可见模型 | GET https://api.xxxiai.com/v1/models |
Responses / Codex | POST https://api.xxxiai.com/v1/responses |
Chat Completions | POST https://api.xxxiai.com/v1/chat/completions |
Anthropic Messages | POST https://api.xxxiai.com/v1/messages |
图片生成 | POST https://api.xxxiai.com/v1/images/generations |
接口是否适用于某个模型，取决于分组及线路支持的协议。GPT 编程优先使用 Responses；Claude 使用 Messages；Gemini / Grok / 国模可按对应分组说明使用 OpenAI 兼容 Chat Completions。图片接口需要图片分组。
密钥只填在你信任的软件或服务端环境中。反馈问题时请遮挡 Key；不要把密钥放到网页前端、公开仓库或聊天截图里。本页所有密钥均为占位符。
CC Switch 一键配置
用 CC Switch 管理编程助手的服务商，不必反复手动改配置。先安装目标客户端，再从 CC Switch 官方发布页 ↗ 安装对应系统版本。
方法一：从纳雪控制台导入
进入 API 密钥
在 API 密钥 找到你要使用的 Key，确认它所属的分组。
点击该行“导入到 CC Switch”
按钮可能显示为导入图标。浏览器提示打开 CC Switch 时，核对目标应用后打开。请在自己的电脑操作，导入内容包含这把 Key。
核对并保存供应商
名称填“纳雪”；确认目标客户端、地址、Key、模型与分组对应。GPT 分组会导入到 Codex；Claude 分组导入到 Claude Code。不要照搬导入模板里的默认模型，尤其科研专线需要改为该组支持的完整 ID。
启用，重开客户端，测试一条消息
启用供应商后重新打开目标客户端，发送“只回复 OK，不修改文件，不运行命令”。收到正常回复后，再在测试目录验证工具调用。
方法二：手动添加“纳雪”
CC Switch 左侧选中目标软件 → 添加供应商 → 自定义配置。Key 填自己的纳雪 Key，地址与协议按下表填写。
目标软件 | 协议 / 地址 | 模型与分组 |
Codex | Responses
https://api.xxxiai.com/v1 | 支持 Responses 的 GPT 分组；模型 ID 必须匹配该 Key 权限。 |
Claude Code | Anthropic Messages
https://api.xxxiai.com | Claude 分组；主模型和后台模型都需在分组支持范围内。 |
OpenCode | 选兼容的 provider
https://api.xxxiai.com/v1 | 下方提供明确使用 Chat Completions 的配置模板。 |
Gemini CLI | 需要 Google 原生协议 | 纳雪公网原生路径目前尚未接通验收，请先使用支持 OpenAI 兼容协议的客户端调用 Gemini。 |
点导入没反应 / 启用后仍然使用原服务商
先打开 CC Switch，确认系统已注册它的链接协议。不能唤起时用手动添加；启用后退出旧终端或窗口再重开。若软件缺少对应客户端页，先核对其版本。连接测试正常而对话失败时，再检查模型权限和协议。
通过 CC Switch 导入时，应在其私有 Key 字段保存密钥；下方 Codex 手动模板使用环境变量，是另一种配置方法，不要混用两套认证来源。
操作参考：CC Switch 添加供应商文档 ↗。本页不自动唤起应用、不生成含真实 Key 的分享链接。
聊天软件
适用于 Cherry Studio、Chatbox，以及支持自定义 OpenAI 兼容服务商的软件。不同版本的字段名称可能略有差异。
在服务商设置中新增 OpenAI 兼容 / 自定义服务商，名称填“纳雪”。
API 地址填 https://api.xxxiai.com/v1，密钥填你的纳雪 Key。
尝试获取模型列表；若获取失败，按分组说明手动添加完整模型 ID。
在对话中选择新添加的服务商和模型，发送“你好，请回复 OK”。
Cherry Studio：注意服务商的请求协议。需要 Responses 的 GPT 线路，请选择支持 Responses 的模式；默认 Chat Completions 的连通性按钮不能代表所有线路。
Chatbox：选择兼容 OpenAI 的自定义服务，并核对最终请求路径。出现 /v1/v1/ 时，将地址改为根域名。
Gemini 分组：使用 OpenAI 兼容模式按本页接入，不要把这里的 /v1 地址填进要求 Google 原生接口的软件。
软件“测试连接”成功只说明该次测试通过；若实际对话使用了另一模型、另一协议或工具调用，还需单独验证。
Codex
适用于支持自定义模型服务商的 Codex CLI / IDE 配置。先选一个支持 Responses 的 GPT 分组，并取得该分组可用模型 ID。
1. 设置环境变量
macOS / Linux：将占位符替换成自己的 Key，只在本机执行。此设置仅对当前终端及其启动的程序生效。
export NAXUE_API_KEY='YOUR_NAXUE_API_KEY'
Windows PowerShell 环境变量
$env:NAXUE_API_KEY = 'YOUR_NAXUE_API_KEY'
2. 修改用户级配置
编辑 ~/.codex/config.toml（Windows 为用户目录下的 .codex\config.toml）。先备份现有配置，合并下面的字段，避免重复同名配置段。把 MODEL_ID 换成完整模型 ID。
model_provider = "naxue"
model = "MODEL_ID"
[model_providers.naxue]
name = "纳雪"
base_url = "https://api.xxxiai.com/v1"
env_key = "NAXUE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
3. 重新启动并验证
从已设置环境变量的终端启动 Codex，先测试简短文本，再让它读取一个测试文件。若 GUI / IDE 提示环境变量缺失，检查它是否继承了该变量；只在终端执行 export 不会修改已经打开的应用。
配置项参考：Codex 官方配置文档 ↗。模型权限、工具兼容性与可用性以所选纳雪分组为准。
Claude Code
使用 Claude 分组的 Key，并选择该分组支持的 Claude 模型。此处 Base URL 填根地址，不加 /v1。
export ANTHROPIC_BASE_URL='https://api.xxxiai.com'
export ANTHROPIC_AUTH_TOKEN='YOUR_NAXUE_API_KEY'
export ANTHROPIC_MODEL='MODEL_ID'
claude
Windows PowerShell 配置
$env:ANTHROPIC_BASE_URL = 'https://api.xxxiai.com'
$env:ANTHROPIC_AUTH_TOKEN = 'YOUR_NAXUE_API_KEY'
$env:ANTHROPIC_MODEL = 'MODEL_ID'
claude
启动后用 /status 检查配置，先发送简短消息，再测试文件读取或工具调用。如果已经设置过 ANTHROPIC_API_KEY、其他网关变量或凭据助手，请先确认认证来源，避免多个配置互相覆盖。
Claude Code 的主模型、后台任务模型都必须在 Key 权限内。出现后台任务的 model not found 时，请检查是否仍在使用不支持的默认模型或旧模型别名。
环境变量参考：Claude Code 官方文档 ↗。
更多软件与配置模板
按软件展开步骤。聊天类模板使用 OpenAI 兼容协议；编程助手还需要模型支持工具调用。以下为配置指引，未逐一安装客户端完成付费端到端验收。
Hermes Agent
退出当前聊天，在终端运行 hermes model，选择 Custom endpoint。
Base URL 填 https://api.xxxiai.com/v1，填写纳雪 Key 与完整模型 ID。
若向导提供 API mode，聊天分组选 Chat Completions；GPT 编程线路按其支持情况选 Responses。保存后启动新会话测试。
聊天中的 /model 用于切换已配置模型，不能代替新增服务商向导。压缩、视觉等辅助任务也要使用有权限的模型。
官方配置说明 ↗
Cursor
打开 Cursor Settings → Models，找到 API Keys。
只有当前版本提供 Override OpenAI Base URL 等自定义入口时，才把地址改为 https://api.xxxiai.com/v1，并填写纳雪 Key。
添加或启用有权限的模型，在新对话中先测试普通问答。
自带 Key 与任意第三方地址支持不是一回事；没有自定义地址入口的版本不能按此接入。Tab 补全等功能不一定使用自定义 Key，且 Cursor 的请求会经过其后端。
官方配置说明 ↗
WorkBuddy
在设置中进入模型配置，添加模型并选择 自定义 / Custom。
按 URL 字段用途填写：基础地址用 https://api.xxxiai.com/v1；若要求完整聊天端点，填 https://api.xxxiai.com/v1/chat/completions。
填写 Key 和模型名称，保存后选为当前模型，发送简短消息。
选择支持 Chat Completions 和所需工具功能的分组；界面的能力选项须按实际模型填写。
官方配置说明 ↗
DeepSeek Harness
在已运行的 Web UI 中进入设置 → 模型 → 添加模型提供商，选择自定义模型 API。
使用兼容的 OpenAI 协议，Base URL 填 https://api.xxxiai.com/v1，Key 填纳雪密钥。
添加完整模型 ID，保存、启用并新建测试会话。若版本支持协议选择，确保它与所选分组一致。
供应商名称不限定只能用 DeepSeek；可用范围由纳雪 Key 的分组决定。先验证文字，再验证编程工具。
官方配置说明 ↗
ZCode
打开模型选择器，进入管理模型 / 模型设置，然后添加供应商。
选择当前版本提供的自定义或 OpenAI 兼容入口，填入 https://api.xxxiai.com/v1、纳雪 Key 和完整模型 ID。
保存后在新会话选择该供应商，先请求简短回复。
不同版本可选的 provider 和字段可能改变；如无自定义地址入口，先核对官方说明。
官方配置说明 ↗
Cline
进入 VS Code 的 Cline 面板 → 设置 → API Provider，选择 OpenAI Compatible。
Base URL 填 https://api.xxxiai.com/v1，API Key 填自己的 Key，Model ID 填完整模型 ID。
先测试普通问答，成功后在独立测试目录验证读取文件等工具。
上下文、图片能力、价格和输出限制按真实模型配置；支持文字不代表支持全部 Agent 功能。
官方配置说明 ↗
Continue
打开 Continue 的本地配置文件 config.yaml，合并下方模板。
通过 Continue 的 secrets 功能配置 NAXUE_API_KEY，将 MODEL_ID 换成真实模型。
重新加载配置，在聊天中选中“纳雪”，发送一条短消息。
模板明确使用 Chat Completions；仅对已确认支持 Responses 的分组与客户端配置启用 useResponsesApi。不要把聊天模型用作 embedding 或 rerank。
官方配置说明 ↗
Gemini CLI（待原生接口验收）
先确认用途：Gemini CLI 需要 Google 原生 generateContent 协议，不能直接使用 OpenAI 的 /v1/chat/completions。
当前纳雪公网 /v1beta 路径尚未接通验收；控制台能生成导入配置，不代表原生请求已可用。
现阶段使用 Cherry Studio、Chatbox 等兼容客户端，通过 https://api.xxxiai.com/v1 调用对应 Gemini 分组。
本页暂不提供看似可直接运行的 Gemini CLI 配置；原生线路完成验收后再更新。
官方配置说明 ↗
OpenCode
在 OpenCode 配置中添加自定义 provider；下方模板使用 @ai-sdk/openai-compatible。
在启动它的环境中设置 NAXUE_API_KEY，替换模型占位符。
打开 OpenCode 并选择 naxue/MODEL_ID，先测试文字，再测试工具。
本模板面向 Chat Completions 分组。Responses 线路需使用明确支持 Responses 的 provider 配置，不能只替换模型名。
官方配置说明 ↗
Aider
安装 Aider 后，在启动终端设置 OPENAI_API_BASE=https://api.xxxiai.com/v1。
将 OPENAI_API_KEY 设置成纳雪 Key，运行 aider --model openai/MODEL_ID。
把 MODEL_ID 换成完整 ID，在空测试目录先发简短问题，再尝试小范围文件修改。
使用 Chat Completions 兼容分组。未知模型可能需要额外的上下文长度、费用或编辑格式配置。
官方配置说明 ↗
Dify
在模型供应商中安装或选择 OpenAI-API-compatible 插件。
新增 LLM 模型，填写完整模型名、Endpoint URL https://api.xxxiai.com/v1 和纳雪 Key。
保存并验证，在测试应用中选择该模型后发消息。
实际请求由 Dify 服务端发起，服务端需要能访问纳雪。知识库的向量模型应另外配置。
官方配置说明 ↗
n8n
添加 HTTP Request 节点，方法选 POST，URL 用 https://api.xxxiai.com/v1/chat/completions。
使用 Header Auth 凭据：名称 Authorization，值为 Bearer 后接你的 Key。
请求体选择 JSON，填 model、messages 和 stream:false；先手动执行一个测试节点。
Key 保存在 n8n Credentials 中。请求超时后先查用量，避免自动重试导致重复生成。
官方配置说明 ↗
curl / Postman / Apifox
新建请求，或导入本页 API 示例 / OpenAPI 文件。
配置私有环境变量 NAXUE_API_KEY，认证选择 Bearer Token；Messages 示例也支持 x-api-key。
选择正确的 POST 接口，Body 用 JSON，先用最小请求测试。
使用完整接口地址，不能只请求根域名。分享集合或导出文件前移除真实凭据。
官方配置说明 ↗
Open WebUI
管理员进入 Connections / 连接设置，新增 OpenAI 兼容连接。
URL 填 https://api.xxxiai.com/v1，填写纳雪 Key，保存并获取模型。
在新聊天中选中模型，发送短消息；若连接受限，检查服务端出站网络。
需要管理员权限，菜单位置随版本变化；文字连接不会自动启用图片接口。
官方配置说明 ↗
AnythingLLM
进入 LLM Preference / 模型设置，寻找 Generic OpenAI。
填写 https://api.xxxiai.com/v1、纳雪 Key 和完整模型 ID。
保存并在测试工作区验证普通对话，再单独配置知识库所用的向量服务。
模型上下文限制按实际分组填写；聊天模型不能代替 embedding 模型。以安装版本的字段为准。
官方配置说明 ↗
ComfyUI
选用明确支持自定义 OpenAI Images 接口的可信节点；仅安装 ComfyUI 本体不会自动连接纳雪。
若节点要求完整 URL，填 https://api.xxxiai.com/v1/images/generations，使用图片分组 Key。
按节点说明填写图片模型、提示词及兼容尺寸，确认费用后再运行一张图。
节点协议和响应格式必须匹配 URL / Base64 的实际返回。本页没有指定或验证第三方节点，不能承诺任意工作流可用。
官方配置说明 ↗
Continue 配置模板
name: 纳雪
version: 1.0.0
schema: v1
models:
- name: 纳雪聊天
provider: openai
model: MODEL_ID
apiBase: https://api.xxxiai.com/v1
apiKey: ${{ secrets.NAXUE_API_KEY }}
useResponsesApi: false
roles:
- chat
OpenCode 配置模板
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"naxue": {
"npm": "@ai-sdk/openai-compatible",
"name": "纳雪",
"options": {
"baseURL": "https://api.xxxiai.com/v1",
"apiKey": "{env:NAXUE_API_KEY}"
},
"models": {
"MODEL_ID": {
"name": "纳雪聊天"
}
}
}
},
"model": "naxue/MODEL_ID"
}
合并模板时保留你原有的设置。下载 Codex 模板 · 下载 Continue 模板 · 下载 OpenCode 模板。模板不含真实密钥。
API 调用示例
下列 cURL 示例适用于 macOS / Linux / WSL。先设置 Key；每次生成会按所选分组计费。将 MODEL_ID 替换为真实模型 ID。
export NAXUE_API_KEY='YOUR_NAXUE_API_KEY'
查询可用模型
curl --fail-with-body --connect-timeout 15 \
'https://api.xxxiai.com/v1/models' \
-H "Authorization: Bearer $NAXUE_API_KEY"
模型列表用于确认 ID 和权限；列出模型不等于此刻推理一定成功。若分组说明限制了可用模型，请以分组说明为准。
Responses · GPT / Codex 线路
curl -N --fail-with-body --connect-timeout 15 --max-time 180 \
'https://api.xxxiai.com/v1/responses' \
-H "Authorization: Bearer $NAXUE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MODEL_ID",
"input": "你好，请简短回复 OK。",
"stream": true
}'
Chat Completions · 支持兼容协议的分组
curl --fail-with-body --connect-timeout 15 --max-time 180 \
'https://api.xxxiai.com/v1/chat/completions' \
-H "Authorization: Bearer $NAXUE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "你好，请简短回复 OK。"}],
"stream": false
}'
Messages · Claude 线路
curl --fail-with-body --connect-timeout 15 --max-time 180 \
'https://api.xxxiai.com/v1/messages' \
-H "x-api-key: $NAXUE_API_KEY" \
-H 'anthropic-version: 2023-06-01' \
-H 'Content-Type: application/json' \
-d '{
"model": "MODEL_ID",
"max_tokens": 256,
"messages": [{"role": "user", "content": "你好，请简短回复 OK。"}]
}'
Python · OpenAI 兼容 SDK
安装 openai 包后运行。下面使用 Chat Completions，需选择支持该协议的分组；支持 Responses 的 GPT 线路也可调用 client.responses.create(...)。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NAXUE_API_KEY"],
base_url="https://api.xxxiai.com/v1",
timeout=180.0,
max_retries=0, # 首次排查时关闭自动重试，避免重复请求
)
reply = client.chat.completions.create(
model="MODEL_ID",
messages=[{"role": "user", "content": "你好，请简短回复 OK。"}],
)
print(reply.choices[0].message.content)
如何判断流式请求完成？
看到 HTTP 200 或首段文字还不够。Responses 应以 response.completed 正常结束；Chat Completions 应收到结束原因及流结束标记；Messages 应正常收到 message_stop。遇到 error、response.failed 或流突然中断，应按失败排查。
较慢的推理模型可能等待较久。示例的 180 秒只是客户端超时设置，并非响应时长承诺；超时后先查用量记录，避免盲目重试。
图片生成
使用图片分组专用 Key，模型 ID 与尺寸参数以该分组说明为准。普通文字分组不能默认调用图片接口。
curl --fail-with-body --connect-timeout 15 --max-time 300 \
'https://api.xxxiai.com/v1/images/generations' \
-H "Authorization: Bearer $NAXUE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "IMAGE_MODEL_ID",
"prompt": "一只坐在雪地里的小猫，柔和自然光",
"n": 1,
"size": "1024x1024"
}'
将 IMAGE_MODEL_ID 替换成图片分组支持的模型。返回内容可能为图片 URL 或 Base64，请根据响应字段处理。生成时间、尺寸限制与计费方式取决于线路。
看图：在聊天接口传入图片
选择明确支持视觉输入和 Chat Completions 的模型。图片使用可访问的 HTTPS 地址或该模型支持的 data URL，不能填写本机文件路径。
{
"model": "VISION_MODEL_ID",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片。"
},
{
"type": "image_url",
"image_url": {
"url": "https://YOUR_IMAGE_HOST/example.png"
}
}
]
}
]
}
改图：multipart 上传原图
仅适用于支持图片编辑的分组。/v1/images/edits 路由已存在，但本页未逐条线路验证编辑能力；先确认该模型支持上传图片和对应参数。下面的 input.png 是本机文件。
curl --fail-with-body --connect-timeout 15 --max-time 300 'https://api.xxxiai.com/v1/images/edits' -H "Authorization: Bearer $NAXUE_API_KEY" -F 'model=EDIT_MODEL_ID' -F 'prompt=保留主体，把背景改成海边' -F 'image=@input.png'
让 cURL 自行生成 multipart 的 Content-Type 与边界。客户端生图入口可在 Cherry Studio 的绘画功能中配置图片端点；普通聊天窗口接收图片不代表具备生图或编辑能力。
分组与计费
一个 Key 所绑定的分组，决定它能使用的模型、请求协议、倍率和额度限制。配置相同地址并不代表不同分组能够互用。
文字请求：费用由模型输入 / 输出用量与计价规则计算，再结合分组倍率；缓存读写、长上下文等可能有独立单价。
加速档位：部分 ProMax 线路的 Fast / Ultrafast 有额外计费倍率，请先阅读对应分组说明，不能只按普通档倍率估算。
图片请求：按该图片分组的实际计价规则结算，尺寸、质量或张数可能影响消耗。
实际扣费：以控制台“使用记录”的请求详情为准；页面额度单位与充值人民币金额需按购买方案换算。
管理 API 密钥 ↗查看分组、额度限制与密钥状态。查看线路状态 ↗查看近期探测、耗时与具体错误。
状态监控是定时采样。绿色表示最近的探测通过，不能保证所有模型、协议和功能都可用；以你的 Key 实际调用结果为准。
让 AI 帮你接入
把下面的任务说明交给有联网能力的 AI，替换软件名称与用途。不能联网时，下载本页的纯文本和软件配方上传给它。
请帮我把【软件名称、版本】接入纳雪，我的用途是【聊天 / 编程 / 看图 / 生图】。
先阅读 https://api.xxxiai.com/status/guide.txt 和 https://api.xxxiai.com/status/software-recipes.json 。
按我实际安装的软件选择协议，不要给所有客户端套同一个地址。
模型 ID 以我的 Key 所属分组为准，不编造可用型号。
不要让我把真实 API Key 发到聊天里，请指导我在软件私有凭据区或本机环境变量中填写。
先帮我完成一条最小文字测试，再确认是否需要图片生成或修改文件。
标注哪些是配置说明，哪些已完成实际调用验证。若遇到不支持的协议，明确说明。
完整纯文本说明 ↗API、软件配置与排查步骤。20 类软件配置配方 ↗结构化字段、步骤和能力限制。OpenAPI 描述 ↗常用接口子集，可导入开发工具。AI 文档索引 ↗完整文档与配置模板的入口。
工具调用、工作流与验收
工具调用需要完整续接
为模型声明 tools 后，先检查返回的是文本还是工具请求。Chat Completions 的工具结果需带回对应 tool_call_id；Responses 的 function_call_output 需匹配 call_id；Claude 则使用 Messages 的 tool_use / tool_result 结构。不要把三种协议的工具消息混用，也不要丢弃上一轮工具请求。
Agent 会额外使用压缩、标题和辅助模型。主对话成功但后台请求失败时，优先检查这些模型是否也在 Key 权限内。先在测试目录验证一次只读工具，再开启写文件或命令执行。
把模型接入自己的应用
由你的服务端保存 Key 并调用纳雪，网页前端只调用自己的业务后端。
把用户、请求 ID、模型、分组和用量记录关联；日志隐藏 Key 和敏感正文。
分别处理连接超时、首字等待、SSE 中断与完整结束；HTTP 200 不是业务完成条件。
设置并发上限，429 按服务端提示退避；生成结果不明确时先核查，避免无条件重发。
实际调用验证模型、协议和工具；图片等能力需另做小样本测试，并核对使用记录。
视频与其他能力
上游文档中的视频、音频和原生协议并不会自动成为纳雪已开放能力。本次未确认纳雪已有可供用户调用的视频分组和完整任务流程，因此不提供可直接发起视频生成的配置。请以纳雪分组说明及后续开放公告为准。
问题排查
现象 | 优先检查 |
401 / Key 无效 | 是否使用纳雪 Key、是否多了空格，Key 是否启用或过期；Bearer 格式是否正确。 |
403 / 权限不足 | 分组权限、Key 限制、余额 / 订阅状态，或客户端是否使用了不允许的模型。 |
404 / model not found | 完整模型 ID、Key 对应分组及请求协议；排除 /v1/v1 和错误域名。 |
429 / 请求受限 | 额度、并发和速率限制；降低并发，按服务端提示稍后重试。 |
502 / 503 / 504 | 查看错误内容与状态监控，可能为线路不可用或超时；保留请求 ID 便于定位。 |
200 但返回 HTML | 通常请求到了网页。检查是否遗漏 /v1 或完整接口路径。 |
有首段文字后中断 | 检查 SSE 结束事件与错误详情；查使用记录后再决定是否重试。 |
软件能获取模型，为什么对话还是失败？
模型列表查询与实际生成是不同请求。请核对对话所用模型和协议，并查看完整错误；模型列出不代表当前上游线路一定可用。
换了分组，原来的 Key 还能直接用吗？
先在密钥管理中确认 Key 实际绑定的分组。仅在软件里更换模型名不会自动切换分组；不同系列请使用对应分组的 Key。
模型回复中自称别的版本，是调用错了吗？
模型的自我描述不能用于身份鉴定。请结合请求的模型 ID、分组说明与响应元数据排查；部分线路返回名称可能带别名，单靠名称差异也不能断定实际模型错误。
普通聊天正常，编程工具却失败怎么办？
依次核对 Responses / Messages 协议、主模型与后台模型权限、工具参数和客户端版本。文本输出正常不能证明工具调用、图片输入等扩展能力都兼容。
反馈问题时，需要提供什么？
提供发生时间及所在时区、软件名称 / 版本、分组名称、模型 ID、HTTP 状态码、已遮挡敏感信息的完整错误和请求 ID（如有）。请勿发送完整 API Key 或含隐私的对话正文。建议排查顺序：地址 → Key 与分组 → 模型 ID → 请求协议 → 完整错误 → 状态监控。先用最简请求定位，再逐步增加流式、工具等功能。