接入文档

01快速开始

准备好三个信息：接入地址、纳雪 API Key、完整模型 ID。

1. 登录纳雪，确认账户有可用额度

   在控制台查看余额或订阅，并通过“充值购买”补充额度。

2. 创建 API Key，选择要使用的分组

   进入 API 密钥，为所需线路创建密钥。Key 绑定的分组决定模型权限与计费倍率。

3. 填写地址和 Key，选一个支持的模型

   从分组说明或模型列表复制完整 ID，先发一条简短消息；确认收到完整回复后，再配置工具调用等功能。

02地址与密钥

若软件自动添加 /v1，只填 https://api.xxxiai.com。如果填写项叫“完整接口地址”，请使用下表中的完整路径。

接口是否适用于某个模型，取决于分组及线路支持的协议。GPT 编程优先使用 Responses；Claude 使用 Messages；Gemini / Grok / 国模可按对应分组说明使用 OpenAI 兼容 Chat Completions。图片接口需要图片分组。

03CC Switch 一键配置

用 CC Switch 管理编程助手的服务商，不必反复手动改配置。先安装目标客户端，再从 CC Switch 官方发布页 ↗ 安装对应系统版本。

方法一：从纳雪控制台导入

1. 进入 API 密钥

   在 API 密钥 找到你要使用的 Key，确认它所属的分组。

2. 点击该行“导入到 CC Switch”

   按钮可能显示为导入图标。浏览器提示打开 CC Switch 时，核对目标应用后打开。请在自己的电脑操作，导入内容包含这把 Key。

3. 核对并保存供应商

   名称填“纳雪”；确认目标客户端、地址、Key、模型与分组对应。GPT 分组会导入到 Codex；Claude 分组导入到 Claude Code。不要照搬导入模板里的默认模型，尤其科研专线需要改为该组支持的完整 ID。

4. 启用，重开客户端，测试一条消息

   启用供应商后重新打开目标客户端，发送“只回复 OK，不修改文件，不运行命令”。收到正常回复后，再在测试目录验证工具调用。

方法二：手动添加“纳雪”

CC Switch 左侧选中目标软件 → 添加供应商 → 自定义配置。Key 填自己的纳雪 Key，地址与协议按下表填写。

操作参考：CC Switch 添加供应商文档 ↗。本页不自动唤起应用、不生成含真实 Key 的分享链接。

04聊天软件

适用于 Cherry Studio、Chatbox，以及支持自定义 OpenAI 兼容服务商的软件。不同版本的字段名称可能略有差异。

1. 在服务商设置中新增 OpenAI 兼容 / 自定义服务商，名称填“纳雪”。
2. API 地址填 https://api.xxxiai.com/v1，密钥填你的纳雪 Key。
3. 尝试获取模型列表；若获取失败，按分组说明手动添加完整模型 ID。
4. 在对话中选择新添加的服务商和模型，发送“你好，请回复 OK”。

软件“测试连接”成功只说明该次测试通过；若实际对话使用了另一模型、另一协议或工具调用，还需单独验证。

05Codex

适用于支持自定义模型服务商的 Codex CLI / IDE 配置。先选一个支持 Responses 的 GPT 分组，并取得该分组可用模型 ID。

1. 设置环境变量

macOS / Linux：将占位符替换成自己的 Key，只在本机执行。此设置仅对当前终端及其启动的程序生效。

export NAXUE_API_KEY='YOUR_NAXUE_API_KEY'

$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 官方配置文档 ↗。模型权限、工具兼容性与可用性以所选纳雪分组为准。

06Claude 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

$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 官方文档 ↗。

07更多软件与配置模板

按软件展开步骤。聊天类模板使用 OpenAI 兼容协议；编程助手还需要模型支持工具调用。以下为配置指引，未逐一安装客户端完成付费端到端验收。

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 模板。模板不含真实密钥。

08API 调用示例

下列 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)

09图片生成

使用图片分组专用 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 的绘画功能中配置图片端点；普通聊天窗口接收图片不代表具备生图或编辑能力。

10分组与计费

一个 Key 所绑定的分组，决定它能使用的模型、请求协议、倍率和额度限制。配置相同地址并不代表不同分组能够互用。

• 文字请求：费用由模型输入 / 输出用量与计价规则计算，再结合分组倍率；缓存读写、长上下文等可能有独立单价。
• 加速档位：部分 ProMax 线路的 Fast / Ultrafast 有额外计费倍率，请先阅读对应分组说明，不能只按普通档倍率估算。
• 图片请求：按该图片分组的实际计价规则结算，尺寸、质量或张数可能影响消耗。
• 实际扣费：以控制台“使用记录”的请求详情为准；页面额度单位与充值人民币金额需按购买方案换算。

状态监控是定时采样。绿色表示最近的探测通过，不能保证所有模型、协议和功能都可用；以你的 Key 实际调用结果为准。

11让 AI 帮你接入

把下面的任务说明交给有联网能力的 AI，替换软件名称与用途。不能联网时，下载本页的纯文本和软件配方上传给它。

请帮我把【软件名称、版本】接入纳雪，我的用途是【聊天 / 编程 / 看图 / 生图】。
先阅读 https://api.xxxiai.com/status/guide.txt 和 https://api.xxxiai.com/status/software-recipes.json 。
按我实际安装的软件选择协议，不要给所有客户端套同一个地址。
模型 ID 以我的 Key 所属分组为准，不编造可用型号。
不要让我把真实 API Key 发到聊天里，请指导我在软件私有凭据区或本机环境变量中填写。
先帮我完成一条最小文字测试，再确认是否需要图片生成或修改文件。
标注哪些是配置说明，哪些已完成实际调用验证。若遇到不支持的协议，明确说明。

12工具调用、工作流与验收

工具调用需要完整续接

为模型声明 tools 后，先检查返回的是文本还是工具请求。Chat Completions 的工具结果需带回对应 tool_call_id；Responses 的 function_call_output 需匹配 call_id；Claude 则使用 Messages 的 tool_use / tool_result 结构。不要把三种协议的工具消息混用，也不要丢弃上一轮工具请求。

Agent 会额外使用压缩、标题和辅助模型。主对话成功但后台请求失败时，优先检查这些模型是否也在 Key 权限内。先在测试目录验证一次只读工具，再开启写文件或命令执行。

把模型接入自己的应用

1. 由你的服务端保存 Key 并调用纳雪，网页前端只调用自己的业务后端。
2. 把用户、请求 ID、模型、分组和用量记录关联；日志隐藏 Key 和敏感正文。
3. 分别处理连接超时、首字等待、SSE 中断与完整结束；HTTP 200 不是业务完成条件。
4. 设置并发上限，429 按服务端提示退避；生成结果不明确时先核查，避免无条件重发。
5. 实际调用验证模型、协议和工具；图片等能力需另做小样本测试，并核对使用记录。

视频与其他能力

上游文档中的视频、音频和原生协议并不会自动成为纳雪已开放能力。本次未确认纳雪已有可供用户调用的视频分组和完整任务流程，因此不提供可直接发起视频生成的配置。请以纳雪分组说明及后续开放公告为准。

13问题排查