UGF-API 接入教程

快速开始

首次使用按下面顺序操作，可以减少大部分配置问题。

1. 打开主站并注册 / 登录账号：https://ai.ugf.cc/login。
2. 进入 API Keys 页面创建密钥，复制形如 sk-... 的 API Key。
3. 进入“可用渠道 / 系统模型”页面，确认当前账号分组支持的模型和实时价格。
4. 在客户端里选择 OpenAI Compatible、Anthropic Compatible 或 Gemini Compatible，再填入对应 Base URL 和 API Key。
5. 保存后先用短消息测试，例如“只回复 ok”。确认成功后再放到正式工作流里使用。

Base URL 填写规则

多数接入失败都来自 Base URL 多写或少写路径。下面按客户端类型选择，不要把具体接口路径重复填进客户端。

OpenAI 兼容客户端

适用于 OpenAI SDK、Cherry Studio、Open WebUI、LobeChat、Cursor、Cline、Roo Code 等支持自定义 OpenAI 端点的客户端。

Responses API 测试

curl https://ai.ugf.cc/v1/responses \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"只回复 ok","max_output_tokens":16}'

Chat Completions 测试

curl https://ai.ugf.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"只回复 ok"}]}'

IDE / 编程插件

VS Code、Cursor、JetBrains 系列插件通常选择 OpenAI Compatible Provider。模型列表为空时，可以先手动填写一个当前可用模型测试。

1. 新增自定义 Provider，类型选择 OpenAI Compatible。
2. Base URL 填 https://ai.ugf.cc/v1。
3. API Key 填 sk-...。
4. Model 填 gpt-5.5、gpt-5.4、gpt-5.4-mini 或系统页面里显示的模型。
5. 保存后重启插件或刷新模型列表，再发起短消息测试。

Codex CLI / Codex App

Codex 使用 Responses API。配置时 Base URL 填到 /v1，不要把 /responses 写进配置项。

config.toml 示例

model_provider = "ugf"
model = "gpt-5.5"
review_model = "gpt-5.5"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.ugf]
name = "UGF-API"
base_url = "https://ai.ugf.cc/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
goals = true

auth.json 示例

{
  "OPENAI_API_KEY": "sk-xxxx",
  "auth_mode": "apikey"
}

Windows 配置目录通常是 %USERPROFILE%\.codex，Linux / macOS 通常是 ~/.codex。

使用 ccSwitch 路由非 GPT 模型

如果希望 Codex 里继续保持 model = "gpt-5.5" 这类 OpenAI 兼容配置，但实际请求路由到 claude-opus-4.8、claude-sonnet 等非 GPT 模型，可以在 ccSwitch 里开启本地路由并配置模型映射。

1. 打开 ccSwitch 首页，进入本地路由相关配置。
2. 开启本地路由，让 Codex 请求先进入 ccSwitch。
3. 在模型映射里把 Codex 侧使用的模型名映射到目标模型，例如把 gpt-5.5 映射为 claude-opus-4.8。
4. 确认路由开关全部打开，再重新启动 Codex 测试短消息。

Codex 一直显示 Reconnecting... 5/5

如果启动 Codex 后连续出现 Reconnecting... 2/5、3/5、4/5、5/5， 通常不是你的网络问题，也不是 UGF-API 站点故障。Codex 启动时会先尝试用 WebSocket 连接后端， 但本站中转走标准 HTTP 接口，不提供 WebSocket 握手；Codex 会把这类失败当成网络抖动重试，等 5 次后才降级到 HTTP。

推荐方案是在 ~/.codex/config.toml 里使用自定义 provider，并加上 supports_websockets = false，让 Codex 从一开始就走 HTTP。

model_provider = "ugf"
model = "gpt-5.5"

[model_providers.ugf]
name = "UGF-API"
base_url = "https://ai.ugf.cc/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

备选：本地代理端口导致握手超时

如果你连接的是 ChatGPT 后端，并且只是 WebSocket 握手超时，可以把代理写进 Codex 自己的 ~/.codex/.env。 这一步不会关闭 WebSocket；对本站中转场景，优先使用上面的 supports_websockets = false。

可以把下面这段话直接发给 Codex，让它自动定位你本地真实代理端口，并替换示例里的 15236。

帮我在 ~\.codex\.env，写入代理信息，需要帮我定位到我本地的代理端口，修改下方的 15236：

HTTP_PROXY="http://127.0.0.1:15236"
HTTPS_PROXY="http://127.0.0.1:15236"
ALL_PROXY="http://127.0.0.1:15236"
NO_PROXY="localhost,127.0.0.1,::1"

执行代理方案时，可能仍然会先重连 5 次，等 Codex 改好 .env 后，完全退出并重新打开 Codex 即可。

Claude Code / Anthropic 兼容

Claude Code 走 Anthropic Messages 兼容端点，环境变量里的 Base URL 填站点根地址。

Linux / macOS

export ANTHROPIC_BASE_URL="https://ai.ugf.cc"
export ANTHROPIC_AUTH_TOKEN="sk-xxxx"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Windows PowerShell

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://ai.ugf.cc", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxxx", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1", "User")

Claude Messages 测试

curl https://ai.ugf.cc/v1/messages \
  -H "x-api-key: sk-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","max_tokens":64,"messages":[{"role":"user","content":"只回复 ok"}]}'

Chatbox

Chatbox 选择 OpenAI API Compatible 模式即可，不需要单独的专用接口。

Gemini CLI / Gemini 兼容客户端

如果当前分组支持 Gemini 兼容模型，Base URL 使用 /v1beta。

export GOOGLE_GEMINI_BASE_URL="https://ai.ugf.cc/v1beta"
export GEMINI_API_KEY="sk-xxxx"
export GEMINI_MODEL="gemini-2.0-flash"

图片生成

图片生成使用 OpenAI Images API。首页当前展示 Image2 4K 规格为 0.05/张，具体可用规格、价格和限制以站内系统页面为准。

推荐：流式生图

curl -N https://ai.ugf.cc/v1/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"一张干净的产品展示图","size":"1024x1024","n":1,"response_format":"b64_json","stream":true}'

兼容：非流式生图

curl https://ai.ugf.cc/v1/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"一张干净的产品展示图","size":"1024x1024","n":1,"response_format":"b64_json"}'

非流式请求会等待图片完成后一次性返回。如果客户端支持 SSE，优先使用 stream: true。

充值、余额与倍率

UGF-API 首页展示的是说明信息，实时价格以登录后的系统页面为准。

常见错误排查