Euzhi 接入指南

3 分钟接入 Euzhi

复制令牌，选择你正在使用的工具，粘贴对应配置即可。

1 复制令牌

从控制台拿到自己的 API Key。

2 选择工具

CC Switch、Codex、OpenCode 或直接 API。

3 填入配置

Base URL、模型名和 Key 对上即可。

去拿令牌 开始配置 查看充值

选择你正在使用的工具

一次只看一种配置

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

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
base_url 只写到 /v1 wire_api 必须是 responses GPT-5.6 约 200K 自动压缩 超过 272K 整次阶梯计费 配置完成后直接运行 codex 桌面应用运行 codex app 不要把 Key 写进仓库

进阶能力

基础接入完成后，再按需展开图片和排错说明。

常见问题遇到报错时再看这 4 个高频问题
提示 command not found: codex

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

Codex 能打开但请求失败

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

调用无权限

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

Image2 报错

确认模型是 gpt-image-2，文生图走 /v1/images/generations，参考图走 /v1/images/edits。

Image2 图片生成在线测试文生图和参考图编辑
Live Demo · gpt-image-2

用一句话生成一张 Image2 图片

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

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

不上传参考图时自动走文生图；上传后自动切到参考图编辑，最多支持 8 张。
准备就绪，填写 API Key 和图片描述后开始生成。
生成结果会显示在这里 建议先用 1024x1024 测试，确认 Key 可用后再接入后端。
Image2 生成结果
打开图片
文生图接口 不上传参考图时使用 POST /v1/images/generations，模型固定 gpt-image-2，请求体为 JSON。不要把 gpt-image-2 放到聊天接口或 Playground 对话入口里调用。
参考图接口 带参考图时自动改走 POST /v1/images/edits，请求体为 multipart/form-data，图片字段写 image[]。
curl同等后端请求
curl https://api.euzhi.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张极简科技感海报，蓝绿色渐变背景，主体是发光的 AI 图片工作台",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'
两个输入框即可测试 不保存 API Key 有参考图自动走 edits 文生图走 JSON 参考图编辑走 multipart 不要走聊天接口
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上游生成、上传参考图或结果下载阶段临时失败或超时。先确认消费日志是否已有成功结果，避免未知状态下重复提交；无结果时再降低并发重试。先查结果再决定。
成功但没有图片上游未返回可用结果，或响应被内容安全策略过滤。缩短并明确提示词，去掉冲突、违法或露骨描述；编辑时确认参考图可访问且内容清晰。修改输入后再试。