Euzhi 文档

选择你正在使用的工具

一次只看一种配置

默认展示 Codex。使用其他工具时切换标签，下面只会保留对应步骤。

CC Switch：推荐给多工具用户

安装一次，后面切换更省心

适合谁你同时用 Codex、Claude Code、OpenCode，或者经常切换不同工具，就用 CC Switch。

怎么接安装 CC Switch 后，在 Euzhi 令牌页点击对应聊天应用入口，浏览器会唤起 CC Switch 并导入 Euzhi 配置。

注意如果浏览器没有唤起，先确认 CC Switch 已安装并能打开；不行就按 Codex / OpenCode 的手动配置走。

CC Switch最短路径

1. 安装 CC Switch
https://github.com/farion1231/cc-switch/releases

2. 打开 Euzhi 令牌页面
https://api.euzhi.com/console/token

3. 找到要使用的令牌
点击右侧聊天应用入口，选择「CC Switch」对应工具

4. 在 CC Switch 中确认导入

5. 在 CC Switch 里选择 Euzhi

下载 CC Switch 打开令牌页面

Claude Desktop：接入 Euzhi

使用客户端内置的第三方推理网关

适合希望在 Claude 桌面客户端中直接对话的用户。无需配置 Anthropic 官方 API Key，使用 Euzhi 的 Kiro分组令牌即可。

1. 准备令牌打开 Euzhi「令牌管理」，新建或编辑令牌，将分组设为 Kiro分组。Claude 模型范围以模型广场实时展示为准。

2. 开启开发者模式在 Claude Desktop 登录界面进入 Help → Troubleshooting → Enable Developer Mode，开启后重新打开左上角菜单。

3. 配置推理网关进入 Developer → Configure third-party inference，按下方参数填写并点击 Apply locally。

Claude Desktop第三方推理配置

Gateway base URL
https://api.euzhi.com

Gateway auth scheme
x-api-key

Gateway API key
sk-你的Euzhi令牌

Skip login-mode chooser
开启

网关地址不要加 /v1Claude Desktop 会自行请求 /v1/messages。这里必须填写 https://api.euzhi.com，不能填写常规 OpenAI Base URL。

令牌使用 Kiro分组Claude 模型目前由 Kiro分组 提供。若提示无权调用，请检查令牌分组、模型权限和账户余额。

应用后直接发消息验证第三方网关模式通常不会显示“连接成功”或“测试通过”。点击 Apply locally 后返回对话页，发送一条消息即可验证。

首次对话的额外小额请求：新建对话并发送第一条消息后，消费记录中可能出现一笔模型名不同的小额调用，这是 Claude Desktop 自动生成会话标题产生的正常请求。

Windows 安装程序无法联网时

Claude Desktop 安装程序需要访问官方下载安装服务。若安装阶段出现网络错误，可先开启系统代理或 TUN 模式；也可以在安装包所在目录打开 CMD，将端口替换为本机代理的实际端口后执行：

Windows CMD仅用于安装阶段

set HTTP_PROXY=http://127.0.0.1:你的代理端口
set HTTPS_PROXY=http://127.0.0.1:你的代理端口
"Claude Setup.exe"

代理端口由本机代理软件决定，与 Euzhi API 配置无关。若 Claude Desktop 已正常安装，可跳过本段。

下载 Claude Desktop 打开令牌管理查看 Claude 模型

Codex：推荐给代码任务

推荐手动配置，兼容性更稳

macOS / Linux复制到终端执行，把 sk-你的令牌 换成自己的 Key。

TerminalKey + 配置目录

echo 'export OPENAI_API_KEY="sk-你的令牌"' >> ~/.zshrc
source ~/.zshrc
mkdir -p ~/.codex
nano ~/.codex/config.toml

Windows PowerShellsetx 后请重新打开终端，再启动 Codex。

PowerShellKey + 配置目录

setx OPENAI_API_KEY "sk-你的令牌"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

config.toml核心配置

model = "gpt-5.5"
model_provider = "euzhi"

[model_providers.euzhi]
name = "Euzhi"
base_url = "https://api.euzhi.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

这里的 model_provider 是 Codex 固定配置字段，整段复制，改好 Key 后即可使用。

GPT-5.6：避免 272K 阶梯收费

config.toml200K 自动压缩

# 放在 config.toml 顶层、[model_providers.euzhi] 之前
model = "gpt-5.6-sol"
model_context_window = 272000
model_auto_compact_token_limit = 200000
model_auto_compact_token_limit_scope = "total"

下载 macOS / Linux 脚本下载 Windows 脚本

macOS / Linux下载后执行

curl -fsSLo /tmp/codex-gpt56-200k.sh https://api.euzhi.com/downloads/codex-gpt56-200k.sh
bash /tmp/codex-gpt56-200k.sh

Windows PowerShell下载后执行

$p = "$env:TEMP\codex-gpt56-200k.ps1"
Invoke-WebRequest https://api.euzhi.com/downloads/codex-gpt56-200k.ps1 -OutFile $p
powershell -ExecutionPolicy Bypass -File $p

避免触发 272K 阶梯收费： Codex 会按总上下文计数，并在约 200K tokens 时自动压缩，给系统提示、工具定义和下一轮输入预留约 72K 缓冲。缓存命中的 tokens 仍计入 272K 门槛；如对话增长较快，可提前执行 /compact。最终是否触发阶梯价，以消费日志中的实际 prompt_tokens 为准。查看 Codex 官方配置参考。脚本会先备份并仅修改上述 4 个顶层字段，不会覆盖 provider、API Key 引用或其他自定义配置；如确实需要超过 272K 的长上下文，请不要运行。

启动 Codex配置完成后再执行

codex

# 如果要打开桌面应用
codex app

只接 API：最小请求

适合后端、脚本、自动化平台

Responses对话/多模态请求

curl https://api.euzhi.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "用三句话解释 Euzhi 怎么接入"
  }'

Base URLSDK 里填 https://api.euzhi.com/v1。

鉴权请求头使用 Authorization: Bearer sk-...。

图片模型Image2、Sunburst 和 Flare 的模型名、文生图与参考图示例，见下方 Image2 图片生成。

常见问题遇到报错时再看这些高频问题

提示 command not found: codex

Codex CLI 没装好，先安装 Codex，再执行 codex --version 验证。

Codex 能打开但请求失败

检查 OPENAI_API_KEY 是否生效，config.toml 是否保存，Base URL 是否只写到 /v1。

调用无权限

令牌没有开启目标模型，或账户余额不足，先去控制台确认令牌和余额。

Image2 报错

从图片模型列表复制准确模型名，并确认令牌有该模型权限。文生图走 /v1/images/generations，参考图走 /v1/images/edits。

Claude Desktop 无法对话

确认 Gateway 只填写 https://api.euzhi.com、鉴权选择 x-api-key，并使用 Kiro分组令牌。

Claude Desktop 没有测试成功提示

第三方推理网关不依赖测试按钮。点击 Apply locally 后直接发送消息，以实际回复结果为准。

OpenCode

支持文本，也支持上传图片

opencode.json稳定版

{
  "$schema": "https://opencode.ai/config.json",
  "model": "euzhi/gpt-5.5",
  "provider": {
    "euzhi": {
      "npm": "@ai-sdk/openai",
      "name": "Euzhi",
      "options": {
        "baseURL": "https://api.euzhi.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}",
        "setCacheKey": true,
        "timeout": 300000,
        "chunkTimeout": 90000
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5",
          "reasoning": true,
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "options": {
            "reasoningEffort": "medium"
          }
        }
      }
    }
  }
}

setCacheKey：Euzhi 专属缓存优化 请保留 "setCacheKey": true。Euzhi 针对 OpenCode 调用 GPT 做了专属缓存优化，开启后会为请求设置稳定的缓存键，帮助连续对话和长上下文更好地复用缓存，降低重复输入消耗。配置同时明确使用 @ai-sdk/openai，并设置 5 分钟总超时和 90 秒分块超时。先把 Euzhi 令牌写入 OPENAI_API_KEY 环境变量，再整段复制并选择 euzhi/gpt-5.5。

Hermes：使用 Responses 模式

开源客户端兼容配置

Hermes 可以通过 Responses API 获得更好的流式和多轮对话兼容性。以下配置针对支持 HERMES_CHAT_API_STYLE 的官方 Hermes 版本。

1. 打开 Hermes 配置编辑 Hermes 实例的 .env。默认路径为 ~/.hermes-codex-agent/.env；如果你的安装方式使用其他实例目录，以该实例下的 .env 为准。

2. 设置 Responses将 HERMES_CHAT_API_STYLE 设为 responses，使用稳定的 SSE 流式请求。

3. 重启并验证修改后重启 Hermes 服务，检查请求路径是 /v1/responses，而不是 /v1/chat/completions。

Hermes 实例 .env对话配置

HERMES_CHAT_MODEL=gpt-5.5
HERMES_CHAT_BASE_URL=https://api.euzhi.com/v1
HERMES_CHAT_API_STYLE=responses
HERMES_CHAT_API_KEY=sk-你的Euzhi令牌
HERMES_CHAT_WEB_SEARCH=auto

重启命令如使用 Hermes 常驻服务，执行 hermes-codex-agent service restart。也可按你的安装方式重启 Hermes。

Base URL 只写到 /v1请填 https://api.euzhi.com/v1，不要把 /responses 加到 Base URL 末尾。

如何判断成功在使用日志或请求详情中查看路径：应为 /v1/responses。如仍是 /v1/chat/completions，说明当前 Hermes 版本不支持或 .env 未被服务加载。

与 OpenCode 分开setCacheKey: true 是 OpenCode 配置项，不要添加到 Hermes。Hermes 的缓存行为以官方开源版本实现为准。

没有生效时：先确认用户使用的是官方 Hermes 版本，再检查 .env 路径、变量名和服务是否已重启。不要修改 Sub2 的「会话 IP/UA 绑定」，它与模型缓存无关。

Image2 图片生成Image2 / Sunburst / Flare 接入与在线测试

三个模型使用同一套图片接口

已有 Image2 接入只需更换 model，Base URL、Bearer 鉴权和请求格式保持一致。SDK 的 Base URL 填 https://euzhi.vip/v1；下面 curl 示例使用完整接口地址。

模型	请求中的 model（直接复制）	接口
Image2	`gpt-image-2`	文生图 generations / 参考图 edits
Image2.5 Sunburst	`gpt-image-2.5-sunburst`	文生图 generations / 参考图 edits
Image2.5 Flare	`gpt-image-2.5-flare`	文生图 generations / 参考图 edits

模型名不要改写：Sunburst 和 Flare 均使用小数点 2.5。不要把页面显示名 Image2.5 Sunburst 或 Image2.5 Flare 当作 API 模型名。

使用有目标模型权限的 Euzhi 令牌，将它设置为环境变量 OPENAI_API_KEY。如果令牌启用了模型限制，须加入要调用的新模型；同时确认令牌分组支持该模型。两个新模型当前与 Image2 同价，按次计费并叠加分组倍率，具体金额以模型价格页和消费记录为准。

Live Demo · Image2 / Sunburst / Flare

选择模型，用一句话生成图片

API Key 只保留在当前浏览器输入框，不会写入页面存储。图片生成通常需要 60-120 秒，请耐心等待进度完成。

如果上传参考图，就会自动切到参考图编辑；没有参考图时，保持正常文生图流程。

API Key

图片模型

图片描述

参考图（可选）

不上传参考图时自动走文生图；上传后自动切到参考图编辑，最多支持 8 张。

准备就绪，选择模型并填写 API Key 和图片描述后开始生成。

生成结果会显示在这里 建议先用 1024x1024 测试，确认 Key 可用后再接入后端。

打开图片

文生图接口 三种模型均使用 POST /v1/images/generations，请求体为 JSON，将 model 填为所选模型名。不要放到聊天接口或 Playground 对话入口里调用。

参考图接口 带参考图时使用 POST /v1/images/edits，请求体为 multipart/form-data，图片字段写 image[]，model 仍填写所选模型名。不要手动设置 Content-Type，让 curl 或 SDK 自动生成 multipart boundary。

curlSunburst 文生图示例

curl https://euzhi.vip/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "一张极简科技感海报，蓝绿色渐变背景，主体是发光的 AI 图片工作台",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

切换模型左侧文生图示例使用 Sunburst，右侧参考图示例使用 Flare。两种请求中的 model 都可以替换为上表任意一个准确模型名，其他字段无需因切换模型而改变。

参考图上传把 ./reference.png 换成实际文件路径。多图时重复添加 -F 'image[]=@./另一张图.png'，在线测试最多选择 8 张图片；不要将本地路径写进 JSON 代替上传。

参数起步先使用示例中的 size=1024x1024、quality=medium、n=1 完成联调。prompt 填图片描述或编辑要求；不上传参考图时不要请求 edits。

读取结果从 data[0].url 获取图片地址；返回 data[0].b64_json 时按 Base64 解码保存。超时后先检查消费记录，避免连续重复提交。

curlFlare 参考图编辑示例

curl https://euzhi.vip/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'model=gpt-image-2.5-flare' \
  -F 'prompt=保留参考图主体，将背景改为明亮的咖啡店，保持自然光与真实质感' \
  -F 'size=1024x1024' \
  -F 'quality=medium' \
  -F 'n=1' \
  -F 'image[]=@./reference.png'

Grok Imagine 图片 APIgrok-imagine-image-pro 文生图与 grok-imagine-image-edit 参考图编辑

Base URL https://api.euzhi.com/v1，下面示例均使用完整接口地址。

鉴权请求头使用 Authorization: Bearer $OPENAI_API_KEY，Key 在令牌管理中创建。

计费按次计费并叠加令牌所在分组倍率，实际扣费以平台实时模型价格和消费日志为准。

令牌的模型限制列表应留空，或同时包含 grok-imagine-image-pro 和 grok-imagine-image-edit。文生图与参考图编辑是两个模型，不能只开放 pro 后再用它提交参考图。

1. 文生图：grok-imagine-image-pro

使用 OpenAI Images 兼容的 JSON 接口。该模型用于无参考图的文本生成图片，请勿改走聊天接口。

POST https://api.euzhi.com/v1/images/generations

参数	必填	类型 / 默认值	说明
`model`	是	string	固定为 `grok-imagine-image-pro`。
`prompt`	是	string	图片描述。建议明确主体、环境、构图、风格、光线、镜头和画面内文字。
`n`	否	integer，默认 `1`	生成数量，支持 `1-10`。批量数量越高，等待时间和扣费次数越高。
`size`	否	string，默认 `1024x1024`	支持 `1024x1024`、`1280x720`、`720x1280`、`1792x1024`、`1024x1792`，分别对应 1:1、16:9、9:16、3:2、2:3。
`response_format`	否	string，默认 `url`	支持 `url` 或 `b64_json`。使用 URL 时建议在生成完成后及时下载并转存。

curl文生图请求

curl https://api.euzhi.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-pro",
    "prompt": "一张现代产品海报，白色背景，中央是一台银色咖啡机，柔和棚拍光，正面构图，无多余文字",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

200 ResponseURL 格式

{
  "created": 1784876400,
  "data": [
    {
      "url": "https://example.com/generated-image.jpg"
    }
  ]
}

2. 参考图编辑：grok-imagine-image-edit

经 Euzhi 公共网关调用时，推荐使用 Chat Completions 多模态 JSON 格式。这样可以稳定传递单张或多张参考图，避免不同 SDK 重写 multipart 数组字段。

POST https://api.euzhi.com/v1/chat/completions

参数	必填	类型 / 默认值	说明
`model`	是	string	固定为 `grok-imagine-image-edit`。
`messages`	是	array	至少包含一条 `role=user` 消息；其 `content` 使用下方多模态内容块。
`messages[].content[].type=text`	是	object	编辑指令放在 `text` 字段。多图时可用 `@IMAGE1`、`@IMAGE2` 按上传顺序指定图片。
`messages[].content[].type=image_url`	是	object，`1-7` 个	`image_url.url` 支持公网 HTTP(S) 图片地址，或 `data:image/...;base64,...`。地址必须能被服务端直接访问。
`stream`	否	boolean，推荐 `false`	非流式结果更容易直接读取最终 Markdown 图片链接。

当前公共网关的编辑输出固定为 1 张、1024x1024、URL 格式。号池原生 /v1/images/edits 虽支持 image[]、n=1-2 和 response_format，但经公共网关调用时不作为默认接入方式；请优先使用上面的多模态 JSON 接口。

curl两张参考图编辑

curl https://api.euzhi.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-edit",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "保留 @IMAGE1 的人物和服装，将人物放入 @IMAGE2 的室内场景，保持自然光和真实比例"
          },
          {
            "type": "image_url",
            "image_url": { "url": "https://example.com/person.jpg" }
          },
          {
            "type": "image_url",
            "image_url": { "url": "data:image/png;base64,你的Base64内容" }
          }
        ]
      }
    ]
  }'

200 Response从 message.content 读取

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "grok-imagine-image-edit",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "![image](https://example.com/edited-image.jpg)"
      },
      "finish_reason": "stop"
    }
  ]
}

本地图片需要先转换为 Base64 Data URI；不要只传本机文件路径，例如 C:\\image.png 或 /Users/.../image.png。
多张参考图按 content 中出现的顺序编号：第一张是 @IMAGE1，第二张是 @IMAGE2。
响应图片地址位于 choices[0].message.content 的 Markdown 中，不在 data[0].url。

3. 常见错误与处理

状态 / 表现	常见原因	处理方式	是否建议立即重试
`400 / 422`	模型与接口不匹配、缺少提示词或参考图、图片格式错误。	文生图使用 `pro + /images/generations`；参考图使用 `edit + /chat/completions`，逐项核对必填参数。	修正参数后再试。
`401`	未带 Bearer Key、Key 错误或已失效。	重新创建令牌并确认请求头格式；不要把 Key 放在 URL 查询参数中。	否。
`403`	令牌模型限制未开放目标模型，或当前分组无该模型权限。	将令牌模型限制留空，或同时加入两个 Grok 图片模型，并确认余额和分组。	否。
`413`	参考图或 Base64 请求体过大。	缩放并压缩参考图，优先使用 JPG/WebP；公网 URL 可减少 JSON 请求体体积。	压缩后再试。
`429` / `Image rate limit exceeded`	当前可用账号的 Imagine 独立额度暂时受限；聊天额度正常不代表生图额度正常。	降低并发并等待后重试。号池会先自动切换可用账号，全部受限时才返回 429。	建议等待几分钟。
`502 / 504`	上游生成、上传参考图或结果下载阶段临时失败或超时。	先确认消费日志是否已有成功结果，避免未知状态下重复提交；无结果时再降低并发重试。	先查结果再决定。
成功但没有图片	上游未返回可用结果，或响应被内容安全策略过滤。	缩短并明确提示词，去掉冲突、违法或露骨描述；编辑时确认参考图可访问且内容清晰。	修改输入后再试。

3 分钟接入 Euzhi

选择你正在使用的工具

CC Switch：推荐给多工具用户

Claude Desktop：接入 Euzhi

Codex：推荐给代码任务

只接 API：最小请求

进阶能力

OpenCode

Hermes：使用 Responses 模式

三个模型使用同一套图片接口

选择模型，用一句话生成图片

1. 文生图：grok-imagine-image-pro

2. 参考图编辑：grok-imagine-image-edit

3. 常见错误与处理