快速开始

本教程带你完成一个可验证的 Nexly API 请求，全程通常需要 5～10 分钟。

API 服务地址https://nexly.guangnian.xin

你将完成

创建 API Key → 保存到环境变量 → 查询账号可用模型 → 发送第一条消息 → 根据响应确认接入成功。

开始前准备

请确认当前设备具备以下条件：

• 可以登录 Nexly API 控制台。
• 我的订阅中已有可用订阅或额度。
• 已安装 curl，或者已准备 Python 3.9+ / Node.js 18+。
• 使用终端执行示例，而不是在浏览器控制台中直接暴露 API Key。

本文使用两个环境变量：

环境变量	用途
NEXLY_API_KEY	保存从控制台创建的 API Key
NEXLY_MODEL	保存 /v1/models 返回的真实模型 ID

1. 创建 API Key

1. 登录 Nexly API 控制台。
2. 先在 我的订阅确认订阅有效。
3. 进入 API 密钥并点击 创建密钥。
4. 填写便于识别的名称，例如 quickstart-local。
5. 选择与订阅匹配的模型分组，按需设置有效期、额度和 IP 限制。
6. 保存、复制新 Key，并存放到安全位置。

不要公开 API Key

不要把真实 Key 写入 Git、网页前端、截图、聊天记录或客户端安装包。如果怀疑泄露，请立即删除旧 Key 并创建新 Key。

如果已安装 CC Switch，也可以创建 Key 后使用Nexly API 快速导入，跳过手工填写端点和模型的步骤。工作台详细操作见 Nexly API 工作台。

2. 设置环境变量

环境变量只在当前终端会话中生效，关闭终端后需要重新设置。

macOS / Linux

export NEXLY_API_KEY="粘贴你的 API Key"

Windows PowerShell

$env:NEXLY_API_KEY="粘贴你的 API Key"

只检查变量是否存在，不要把完整 Key 打印到屏幕：

macOS / Linux

test -n "$NEXLY_API_KEY" && echo "NEXLY_API_KEY 已设置"

Windows PowerShell

if ($env:NEXLY_API_KEY) { "NEXLY_API_KEY 已设置" }

预期结果：终端输出 NEXLY_API_KEY 已设置。

3. 查询并选择模型

不要直接照抄文档中的示例模型。不同账号可用模型可能不同，应先查询模型列表。

macOS / Linux

curl --fail-with-body https://nexly.guangnian.xin/v1/models \
  -H "Authorization: Bearer $NEXLY_API_KEY"

Windows PowerShell

$headers = @{ Authorization = "Bearer $env:NEXLY_API_KEY" }
Invoke-RestMethod `
  -Uri "https://nexly.guangnian.xin/v1/models" `
  -Headers $headers

成功时会返回模型列表：

{
  "object": "list",
  "data": [
    {
      "id": "账号实际可用的模型 ID",
      "object": "model"
    }
  ]
}

从 data 中选择一个 id，原样保存到 NEXLY_MODEL：

macOS / Linux

export NEXLY_MODEL="把模型 ID 填在这里"

Windows PowerShell

$env:NEXLY_MODEL="把模型 ID 填在这里"

预期结果：/v1/models 返回 HTTP 200，并且 data 数组中至少包含一个模型。

4. 发送第一条消息

下面四种方式任选一种。首次测试建议使用 cURL 或 PowerShell，以减少 SDK 环境带来的干扰。

cURL / PowerShell 使用含 /v1/... 的完整接口地址；SDK 示例填写服务根地址，由 SDK 拼接路径。两类地址不要混填，详见客户端地址类型。

cURL

curl --fail-with-body https://nexly.guangnian.xin/v1/chat/completions \
  -H "Authorization: Bearer $NEXLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$NEXLY_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"只回复：Nexly API 连接成功\"}
    ]
  }"

PowerShell

$headers = @{
  Authorization = "Bearer $env:NEXLY_API_KEY"
  "Content-Type" = "application/json"
}
$body = @{
  model = $env:NEXLY_MODEL
  messages = @(
    @{ role = "user"; content = "只回复：Nexly API 连接成功" }
  )
} | ConvertTo-Json -Depth 4

Invoke-RestMethod `
  -Method Post `
  -Uri "https://nexly.guangnian.xin/v1/chat/completions" `
  -Headers $headers `
  -Body $body

Python

# 安装依赖：python -m pip install --upgrade openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEXLY_API_KEY"],
    base_url="https://nexly.guangnian.xin",
)

response = client.chat.completions.create(
    model=os.environ["NEXLY_MODEL"],
    messages=[
        {"role": "user", "content": "只回复：Nexly API 连接成功"}
    ],
)

print(response.choices[0].message.content)

Node.js

// 安装依赖：npm install openai
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.NEXLY_API_KEY,
  baseURL: 'https://nexly.guangnian.xin',
})

const response = await client.chat.completions.create({
  model: process.env.NEXLY_MODEL,
  messages: [
    { role: 'user', content: '只回复：Nexly API 连接成功' },
  ],
})

console.log(response.choices[0].message.content)

5. 确认接入成功

满足以下条件表示基础接入已经完成：

• 请求返回 HTTP 200。
• 响应中包含 choices[0].message.content。
• 返回内容不是 HTML 登录页或网关错误页。
• Nexly API 控制台的 使用记录中可以看到刚才的请求。

如果请求失败，先按下表检查：

现象	优先检查
401	Key 是否完整、是否已删除，Bearer 后是否有一个空格
403	Key 的权限、有效期、账号状态和模型授权
404	地址是否包含正确的 /v1，模型是否支持当前接口
429	账号额度、并发、频率限制和错误消息
400 model not found	NEXLY_MODEL 是否与 /v1/models 返回的 id 完全一致

完整处理方法请查看错误处理。

接入检查清单

• [ ] API Key 只保存在本机环境变量或服务端密钥管理系统中。
• [ ] 模型 ID 来自当前账号的 /v1/models 响应。
• [ ] SDK 的 Base URL 使用 https://nexly.guangnian.xin，末尾没有 /v1。
• [ ] 第一个请求已返回 HTTP 200。
• [ ] 日志和错误反馈中没有包含完整 API Key。

下一步

• 阅读身份认证，了解 Key 的隔离、轮换和撤销。
• 阅读模型与能力，确认模型支持的接口和参数。
• 阅读OpenAI SDK或HTTP 请求，接入流式输出和错误处理。
• 打开 API Reference，查看完整请求参数和响应结构。