星月 API 接入文档

星月 API 完整接入参考

一个 API Key，连接 Claude、GPT、Gemini、Antigravity 等模型。

本文面向第一次使用 AI API 的用户。跟着“5 分钟快速上手”操作，你将完成：

1. 创建自己的 API Key；
2. 找到当前可用的模型名称；
3. 发送第一条 API 请求；
4. 将星月 API 接入 Codex、Claude Code、CC Switch 或其他客户端。

---

一、先认识 3 个概念

1. API Key

API Key 相当于调用接口的“密码”，通常以 sk- 开头。

本文统一使用下面的占位符：

sk-你的API密钥

实际使用时，请把它完整替换成你在星月 API 控制台创建的密钥。

不要把真实 API Key 发到群聊、截图、公开仓库或前端代码中。

2. Base URL

Base URL 是客户端连接星月 API 的接口地址。

不同客户端的填写规则不同：

3. 模型名称

模型名称决定本次请求使用哪个 AI 模型。

本文使用下面的占位符：

你的模型名称

请前往模型广场，复制当前可用的模型名称。模型名称必须完全一致，包括大小写、数字和连接符。

可用模型、分组和价格可能调整，以模型广场和你当前 API Key 所属分组为准。

---

二、开发者 5 分钟 API 调用

这一节适合需要使用 cURL、Python、Node.js 或其他代码调用 API 的用户。只想配置 ChatGPT 的新手请使用页面上方的 CC Switch 向导。

第 1 步：注册并登录

打开星月 API，点击“进入控制台”，完成注册或登录。

第 2 步：创建 API Key

1. 打开控制台的 API Keys 页面；
2. 点击“创建密钥”；
3. 填写一个容易识别的名称，例如 我的电脑；
4. 选择需要使用的分组；
5. 按需设置额度、有效期或 IP 限制；
6. 创建后复制并妥善保存 API Key。

如果只是第一次测试，建议先使用简单配置；确认调用成功后，再设置额度和 IP 限制。

第 3 步：复制模型名称

打开模型广场，找到与你的 API Key 分组匹配的模型，然后复制模型名称。

第 4 步：设置环境变量

这样做可以避免把真实 API Key 直接写进命令历史或代码文件。

macOS / Linux：

export XINGYUE_API_KEY="sk-你的API密钥"
export XINGYUE_MODEL="你的模型名称"

Windows PowerShell：

$env:XINGYUE_API_KEY="sk-你的API密钥"
$env:XINGYUE_MODEL="你的模型名称"

上述设置只对当前终端窗口生效。关闭终端后，需要重新设置。

第 5 步：先验证 API Key 和模型列表

macOS / Linux：

curl -fsS "https://api.xingyueapi.com/v1/models" \
  -H "Authorization: Bearer $XINGYUE_API_KEY"

Windows PowerShell：

curl.exe -sS "https://api.xingyueapi.com/v1/models" `
  -H "Authorization: Bearer $env:XINGYUE_API_KEY"

如果返回模型数据，说明 Base URL 和 API Key 已经可以正常使用。

第 6 步：发送第一条对话请求

下面使用兼容性较好的 Chat Completions 接口。

macOS / Linux：

curl -X POST "https://api.xingyueapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $XINGYUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$XINGYUE_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"你好，请用一句话介绍你自己。\"}
    ]
  }"

Windows PowerShell：

$body = @{
  model = $env:XINGYUE_MODEL
  messages = @(
    @{
      role = "user"
      content = "你好，请用一句话介绍你自己。"
    }
  )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "https://api.xingyueapi.com/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:XINGYUE_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

看到 AI 返回的文本，就表示接入成功。

如果当前分组不支持 Chat Completions，请改用后文对应的 Responses 或 Anthropic Messages 接口。

---

三、接口和 Base URL 怎么选

先根据你使用的工具选择协议，再填写地址。

最容易出错的地方

• Codex 的 Base URL 带 /v1；
• Claude Code 的 Base URL 不带 /v1；
• 直接请求接口时，URL 中需要包含完整路径；
• 最终请求地址中通常只应出现一次 /v1，不要写成 /v1/v1/...；
• OpenAI 和 Anthropic 协议的请求体格式不同，不能混用。

---

四、手动配置 Codex CLI（高级）

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

如果你使用的是 Windows 电脑端 ChatGPT，请返回顶部使用 CC Switch 向导，不需要手动修改 config.toml。

适合使用 Codex CLI 或 Codex app 的用户。Codex 使用 Responses API。

1. 找到配置文件

如果目录或文件不存在，可以手动创建。

2. 写入配置

model = "你的模型名称"
model_provider = "xingyue"

[model_providers.xingyue]
name = "星月 API"
base_url = "https://api.xingyueapi.com/v1"
env_key = "XINGYUE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

3. 设置 API Key

macOS / Linux：

export XINGYUE_API_KEY="sk-你的API密钥"
codex

Windows PowerShell：

$env:XINGYUE_API_KEY="sk-你的API密钥"
codex

4. 验证是否成功

启动 Codex 后发送一个很短的任务，例如：

请回复：星月 API 已连接。

如果出现问题，请先检查：

1. base_url 是否为 https://api.xingyueapi.com/v1；
2. wire_api 是否为 responses；
3. 启动 Codex 的同一个终端是否能够读取 XINGYUE_API_KEY；
4. model 是否与模型广场中的名称完全一致；
5. 当前 API Key 分组是否支持该模型和 Responses API。

---

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

五、接入 Claude Code

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

Claude Code 使用 Anthropic Messages 兼容协议。

方法一：当前终端临时配置

macOS / Linux：

export ANTHROPIC_BASE_URL="https://api.xingyueapi.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的API密钥"
export ANTHROPIC_MODEL="你的模型名称"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://api.xingyueapi.com"
$env:ANTHROPIC_AUTH_TOKEN="sk-你的API密钥"
$env:ANTHROPIC_MODEL="你的模型名称"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
claude

方法二：写入用户级配置

配置文件位置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xingyueapi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API密钥",
    "ANTHROPIC_MODEL": "你的模型名称",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

用户级配置文件中包含真实 API Key 时，不要上传或提交该文件。更安全的方式是只在终端设置 ANTHROPIC_AUTH_TOKEN。

验证是否成功

启动 Claude Code 后，可以运行：

/status

重点确认：

• Base URL 为 https://api.xingyueapi.com；
• API Key 已被当前进程读取；
• 模型名称属于当前 API Key 分组；
• Base URL 末尾没有手动添加 /v1。

---

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

六、接入 CC Switch 推荐方式

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

最简单的方法：控制台一键导入

1. 登录星月 API；
2. 打开 API Keys 页面；
3. 找到需要使用的 API Key；
4. 点击该 Key 右侧的“导入到 CCS”或“导入 CC Switch”；
5. 选择对应客户端并完成导入；
6. 在 CC Switch 中保存并切换到星月 API 配置。

手动填写规则

CC Switch 手动配置：本教程的 CC Switch 配置会自动补上 /v1，所以填写根域 https://api.xingyueapi.com。如果你当前版本明确要求完整路径，再填写 https://api.xingyueapi.com/v1。最终请求地址只能出现一次 /v1。

其他字段：

导入后先发送一条最短消息。确认成功后，再开始正式任务。

---

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

七、接入 OpenCode

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

适合谁

终端里的开源 AI 编程工具，适合在项目目录中直接让 AI 修改代码。

配置入口：先点哪里

在项目目录打开终端，运行 opencode；首次进入后打开设置或 Provider 配置。若版本支持配置文件，也可编辑项目根目录的 opencode.json。

要填写什么

最小可复制配置

{
  "provider": "xingyue",
  "baseURL": "https://api.xingyueapi.com/v1",
  "apiKey": "sk-你的API密钥",
  "model": "你的模型名称"
}

API Key 只在本机配置界面粘贴，不要提交到代码仓库。模型名以模型广场或上游模型列表当前显示的值为准。

保存并测试

1. 点击“保存”“应用”或“测试连接”。
2. 重新选择刚添加的 Provider 和 Model。
3. 发送一条最短消息，确认出现模型回复。

保存后发送 请用一句话说明这个项目的作用。看到模型回复且没有 401/404，说明接入成功。

常见错误

• 401 Unauthorized：重新复制 API Key，确认没有多余空格。
• 404 Not Found：检查 Base URL 是否重复添加 /v1。
• 400 Bad Request：检查协议类型和模型名称是否匹配。
• 超时或连接失败：检查网络、代理和客户端超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

八、接入 OpenClaw

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

适合谁

带有模型服务商设置的 AI 编程或自动化客户端，适合管理多个模型。

配置入口：先点哪里

打开 OpenClaw 设置，进入 Model Providers、模型服务商 或 Custom Provider，点击“新增服务商”。

要填写什么

最小可复制配置

Provider：星月 API
Protocol：OpenAI Compatible
Base URL：https://api.xingyueapi.com/v1
API Key：sk-你的API密钥
Model：你的模型名称

API Key 只在本机配置界面粘贴，不要提交到代码仓库。模型名以模型广场或上游模型列表当前显示的值为准。

保存并测试

1. 点击“保存”“应用”或“测试连接”。
2. 重新选择刚添加的 Provider 和 Model。
3. 发送一条最短消息，确认出现模型回复。

点击“测试连接”或“保存并测试”，然后发一条最短消息，看到模型回复即可。

常见错误

• 401 Unauthorized：重新复制 API Key，确认没有多余空格。
• 404 Not Found：检查 Base URL 是否重复添加 /v1。
• 400 Bad Request：检查协议类型和模型名称是否匹配。
• 超时或连接失败：检查网络、代理和客户端超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

九、接入 Hermes Agent

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

适合谁

可执行多步任务的 AI Agent，适合读取文件、调用工具或连续完成任务。

配置入口：先点哪里

打开 Hermes Agent 模型设置，查找 Model、Provider、Custom endpoint 或 Environment variables。

要填写什么

最小可复制配置

export OPENAI_API_KEY="sk-你的API密钥"
export OPENAI_API_BASE="https://api.xingyueapi.com/v1"
export OPENAI_MODEL="你的模型名称"

API Key 只在本机配置界面粘贴，不要提交到代码仓库。模型名以模型广场或上游模型列表当前显示的值为准。

保存并测试

1. 点击“保存”“应用”或“测试连接”。
2. 重新选择刚添加的 Provider 和 Model。
3. 发送一条最短消息，确认出现模型回复。

启动 Agent 后输入 列出当前目录中的一个文件名。看到 Agent 返回结果，说明模型连接正常。

常见错误

• 401 Unauthorized：重新复制 API Key，确认没有多余空格。
• 404 Not Found：检查 Base URL 是否重复添加 /v1。
• 400 Bad Request：检查协议类型和模型名称是否匹配。
• 超时或连接失败：检查网络、代理和客户端超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

十、接入 Cherry Studio

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

适合谁

桌面端多模型客户端，适合用图形界面管理模型。

配置入口：先点哪里

打开 Cherry Studio → 左下角“设置” → “模型服务商” → “添加” → 选择 OpenAI 或 OpenAI Compatible。

要填写什么

最小可复制配置

服务商：星月 API
API 地址：https://api.xingyueapi.com/v1
API Key：sk-你的API密钥
模型：你的模型名称

API Key 只在本机配置界面粘贴，不要提交到代码仓库。模型名以模型广场或上游模型列表当前显示的值为准。

保存并测试

1. 点击“保存”“应用”或“测试连接”。
2. 重新选择刚添加的 Provider 和 Model。
3. 发送一条最短消息，确认出现模型回复。

点击“检查”或“保存”，新建聊天后选中模型，发送 你好，请回复“连接成功”。

常见错误

• 401 Unauthorized：重新复制 API Key，确认没有多余空格。
• 404 Not Found：检查 Base URL 是否重复添加 /v1。
• 400 Bad Request：检查协议类型和模型名称是否匹配。
• 超时或连接失败：检查网络、代理和客户端超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

十一、接入 Cline

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

适合谁

VS Code 中的 AI 编程插件，适合解释、修改和生成代码。

配置入口：先点哪里

在 VS Code 打开 Cline → 点击 Cline 面板右上角设置图标 → 找到 API Provider。

要填写什么

最小可复制配置

API Provider：OpenAI Compatible
API URL：https://api.xingyueapi.com/v1
API Key：sk-你的API密钥
Model ID：你的模型名称

API Key 只在本机配置界面粘贴，不要提交到代码仓库。模型名以模型广场或上游模型列表当前显示的值为准。

保存并测试

1. 点击“保存”“应用”或“测试连接”。
2. 重新选择刚添加的 Provider 和 Model。
3. 发送一条最短消息，确认出现模型回复。

让 Cline 执行 解释当前文件，不要修改代码。看到分析结果且没有认证错误即可。

常见错误

• 401 Unauthorized：重新复制 API Key，确认没有多余空格。
• 404 Not Found：检查 Base URL 是否重复添加 /v1。
• 400 Bad Request：检查协议类型和模型名称是否匹配。
• 超时或连接失败：检查网络、代理和客户端超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

十二、其他 OpenAI Compatible 客户端

前置条件：已安装本软件，并准备好星月 API Key。模型优先使用“获取上游模型”，获取失败时再手动粘贴模型名称。

如果你使用上面列出的五个软件，请优先点击对应的独立教程。本节只给其他 OpenAI Compatible 客户端使用。

通用配置

通用操作顺序

1. 打开客户端设置、模型、Provider 或 API 页面。
2. 新增自定义 OpenAI Compatible 服务商。
3. 填入 Base URL、API Key 和 Model。
4. 保存后测试连接，再发送一条最短消息。

客户端自动拼接路径怎么办？

最终地址应只出现一次 /v1，不要写成 /v1/v1。如果 404，在根地址和带 /v1 的完整地址之间切换一次。

其他客户端的排错

• 401：重新复制 API Key。
• 404：检查 Base URL 和自动拼接规则。
• 400：检查协议类型、模型名称和请求格式。
• 超时：检查网络、代理和超时设置。

成功标志：发送一条“你好”测试消息后，能看到模型返回内容，并且没有出现 401、404 或“模型不存在”。

返回软件入口 ↑

十三、Python 示例

1. 安装 SDK

pip install openai

2. Chat Completions 示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XINGYUE_API_KEY"],
    base_url="https://api.xingyueapi.com/v1",
)

response = client.chat.completions.create(
    model=os.environ["XINGYUE_MODEL"],
    messages=[
        {"role": "user", "content": "请用一句话解释什么是 API。"}
    ],
)

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

运行前先设置：

export XINGYUE_API_KEY="sk-你的API密钥"
export XINGYUE_MODEL="你的模型名称"
python app.py

Windows PowerShell：

$env:XINGYUE_API_KEY="sk-你的API密钥"
$env:XINGYUE_MODEL="你的模型名称"
python app.py

3. Responses API 示例

适合当前分组支持 Responses API 的模型：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XINGYUE_API_KEY"],
    base_url="https://api.xingyueapi.com/v1",
)

response = client.responses.create(
    model=os.environ["XINGYUE_MODEL"],
    input="请回复：Responses API 已连接。",
)

print(response.output_text)

---

十四、Node.js 示例

1. 安装 SDK

npm install openai

2. 创建 app.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XINGYUE_API_KEY,
  baseURL: "https://api.xingyueapi.com/v1",
});

const response = await client.chat.completions.create({
  model: process.env.XINGYUE_MODEL,
  messages: [
    { role: "user", content: "请用一句话解释什么是 API。" },
  ],
});

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

3. 运行

macOS / Linux：

export XINGYUE_API_KEY="sk-你的API密钥"
export XINGYUE_MODEL="你的模型名称"
node app.mjs

Windows PowerShell：

$env:XINGYUE_API_KEY="sk-你的API密钥"
$env:XINGYUE_MODEL="你的模型名称"
node app.mjs

4. Responses API 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XINGYUE_API_KEY,
  baseURL: "https://api.xingyueapi.com/v1",
});

const response = await client.responses.create({
  model: process.env.XINGYUE_MODEL,
  input: "请回复：Responses API 已连接。",
});

console.log(response.output_text);

---

十五、常见问题

1. 返回 401 Unauthorized

表示 API Key 没有被正确接受。

依次检查：

1. API Key 是否完整，前后有没有空格；
2. 请求头是否为 Authorization: Bearer 你的Key；
3. 环境变量是否为空；
4. API Key 是否已被禁用、删除或过期；
5. 请求是否误发到了其他域名。

查看环境变量时不要直接把完整 Key 发到截图或工单中。

2. 返回 403 Forbidden

403 通常表示 Key 已被识别，但当前调用条件不满足。常见原因：

• 账户余额不足；
• API Key 额度已经用完；
• API Key 已过期；
• 当前分组不允许使用目标模型；
• API Key 设置了 IP 白名单或黑名单；
• 订阅或分组当前不可用。

请回到控制台检查 Key 状态、余额、分组、额度、有效期和 IP 限制。

3. 返回 404 Not Found

通常是地址或路径错误。

重点检查：

• Codex 是否填写了 https://api.xingyueapi.com/v1；
• Claude Code 是否误填成了 https://api.xingyueapi.com/v1；
• 是否出现了重复的 /v1/v1；
• 是否把 OpenAI 协议的路径用于 Anthropic 客户端。

4. 返回 429 Too Many Requests

可能是请求过快、并发过高、Key 总额度或时间窗口用量达到限制，也可能是多次使用错误 Key 触发了鉴权保护。

建议：

1. 先阅读返回的错误消息，区分 Key 额度、时间窗口额度、请求频率或上游限流；
2. 降低并发，并按照响应中的 Retry-After 等待后再试；
3. 程序中使用指数退避；
4. 检查 Key 的速率限制、额度和订阅用量。

不要无间隔地无限重试。

5. 提示模型不存在或模型不可用

1. 前往模型广场重新复制模型名称；
2. 确认 API Key 所属分组支持该模型；
3. 确认名称没有多余空格；
4. 不要长期依赖网上旧教程中的模型名称。

6. 提示模型不受支持或服务暂时不可用

• 404 model_not_found：模型名称错误，或者当前分组没有账号支持该模型；
• 503 api_error：模型存在，但当前账号池暂时没有可承接请求的资源。

遇到 404 时重新核对模型和分组；遇到 503 时稍后退避重试，或换用模型广场中当前可用、且与 Key 分组匹配的模型。

7. 返回 502 或 503

• 502 通常表示上游服务暂时异常；
• 503 可能表示账号池暂时无可用资源、鉴权或计费服务繁忙，或者上游处于过载状态。

此类错误适合有限次数的退避重试。不要立即高频重复提交同一个请求。

8. 请求一直没有返回

• 先用很短的提示词测试；
• 暂时关闭流式输出，观察完整错误；
• 检查本地网络、代理和客户端超时时间；
• 查看控制台用量记录或错误记录；
• 记录请求时间和返回的 request ID，联系支持时一并提供。

9. 联系支持时应该提供什么？

建议提供：

• 问题发生时间；
• 使用的客户端；
• 请求接口；
• 模型名称；
• HTTP 状态码；
• request ID；
• 已脱敏的错误响应。

不要提供完整 API Key。请通过星月 API 控制台当前显示的官方支持入口联系支持。

---

十六、API Key 安全提醒

请遵守以下规则：

1. 不要把 Key 写进公开 Git 仓库；
2. 不要把 Key 写死在浏览器前端、网页 JavaScript 或公开客户端代码中；
3. 不要在聊天群、截图、视频、直播或工单中展示完整 Key；
4. 服务器程序优先通过环境变量或密钥管理服务读取 Key；
5. 测试环境和正式环境使用不同的 Key；
6. 为 Key 设置合理额度和有效期；
7. 不再使用的 Key 及时禁用或删除；
8. 怀疑泄露时，立即禁用旧 Key 并创建新 Key。

.gitignore 示例：

.env
.env.*
!.env.example

.env.example 只保留占位符：

XINGYUE_API_KEY=sk-请在本地填写
XINGYUE_MODEL=请填写模型名称

---

十七、一页速查

常用入口

地址速查

认证速查

Authorization: Bearer sk-你的API密钥
Content-Type: application/json

配置公式

选择协议 → 填写 Base URL → 填写 API Key → 复制可用模型名称 → 发送最短测试请求

最后检查

• [ ] API Key 完整且处于启用状态；
• [ ] Key 的分组支持所选模型；
• [ ] 模型名称来自当前模型广场；
• [ ] Codex 地址带 /v1；
• [ ] Claude Code 地址不带 /v1；
• [ ] 最终请求中没有重复的 /v1/v1；
• [ ] 没有把真实 Key 写进公开文件。

---

文档更新时间：2026 年 8 月 12 日。