关于CPA配置GPT-IMAGE-2的一些收货(CLAUDE整理,大家也帮忙指正一下)

核心结论

CLIProxyAPI（CPA）是将 Codex CLI OAuth 会话包装成 OpenAI 兼容 REST API 的反代工具。其图像生成不是独立接口，而是通过 gpt-5.4-mini Chat 模型的 image_generation 工具调用实现的。暴露的 gpt-image-2 模型名是硬编码别名。

主要价值：调用走 chatgpt.com/backend-api/codex 路径，不产生聊天记录，无 chat 侧边栏副作用。

主要局限：Plus 订阅下质量封顶 medium，transparent 背景不支持。

部署要点（Docker）

docker-compose.yml 关键配置

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    pull_policy: always
    ports:
      - "8004:8317"               # 自定义宿主端口:容器内部端口(固定8317)
      - "127.0.0.1:1455:1455"     # OAuth 回调端口，LAN 隔离
    volumes:
      - ./auths:/root/.cli-proxy-api    # OAuth token 持久化
      - ./config/config.yaml:/CLIProxyAPI/config.yaml:ro
      - ./logs:/CLIProxyAPI/logs
    healthcheck:
      test: ["CMD-SHELL", "netstat -ltn 2>/dev/null | grep -q ':8317' || ss -ltn 2>/dev/null | grep -q ':8317' || exit 1"]
      interval: 30s; start_period: 20s; retries: 3
    logging:
      driver: json-file
      options: {max-size: "10m", max-file: "3"}

重要：docker-compose.yml 必须放在与 ./auths、./config、./logs 同级的目录，不能放在子目录（子目录时相对路径解析错误，Docker 会自动创建空目录导致 “is a directory” 错误）。

config.yaml 最小配置

port: 8317
debug: false
api-keys:
  - "<openssl rand -hex 32>"
auth-dir: "~/.cli-proxy-api"    # 保持默认，勿改

OAuth 登录（一次性）

Codex OAuth 使用 port 1455（非 54545 - 那是 Claude Code 的）。

# 1. Windows 建 SSH tunnel（保持打开）
ssh -L 1455:127.0.0.1:1455 root@<NAS_IP>

# 2. NAS 侧以 detached 方式启动 --codex-login（不要 -d docker exec，要带 shell -d）
docker exec -d cli-proxy-api sh -c '/CLIProxyAPI/CLIProxyAPI -no-browser --codex-login > /CLIProxyAPI/logs/oauth-session.log 2>&1'

# 3. 读取生成的 OAuth URL
cat /vol/Docker/cliproxyapi/logs/oauth-session.log

# 4. 浏览器访问 URL → 登录 ChatGPT Plus → 授权 → 成功
# Token 保存至 ./auths/codex-<email>-<tier>.json

Gotcha：用 docker compose exec 不加 -d 时，SSH 断开会杀死登录等待进程，导致 OAuth 回调失败（connection refused）。必须 detached 运行。

容器自动生成的 SSH 命令 使用服务器公网 IP，局域网部署时手动替换为内网 IP。

参数实测（/v1/images/generations）

参数 行为 实测结果 prompt 完全透传 正常 size 生效 1024x1024/1536x1024/2048x2048 均通过 quality Plus 封顶 medium “high” 请求流通但响应始终为 medium output_format 生效 png/webp 验证通过 background: "transparent" 不支持 HTTP 400，Codex 底层 image tool 拒绝 n 生效 n=2 成功，2 张图 response_format 未测试 — moderation 未测试 —

质量层级机制

质量实际由底层 gpt-5.4-mini image tool 决定，不由用户参数强制控制：

• output_tokens ~200 = low 质量（约 500KB PNG）
• output_tokens ~1400-1800 = medium 质量（约 1-2MB PNG）
• output_tokens >3500 = high 质量（Plus 层从未达到）
• 复杂 prompt 促进 low→medium 提升；Plus 订阅封顶 medium（Pro/Enterprise 可能解锁 high，未测）

响应结构

{
  "data": [{"b64_json": "...", "revised_prompt": "..."}],
  "quality": "medium",
  "size": "1024x1024",
  "background": "opaque",
  "output_format": "png",
  "usage": {"output_tokens": 1756, "input_tokens": 27, "total_tokens": 1783}
}

revised_prompt 字段显示模型对 prompt 的内部改写，调试时有参考价值。

自定义别名配置（社区方案）

来源：linux.do 社区 hKFirEs（topic/1993292），lostip.de blog/1109262072

oauth-model-alias:
  codex:
    - name: gpt-5.4-mini
      alias: gpt-image-1024x1024
      fork: true              # fork=true 保留原名同时暴露别名
    - name: gpt-5.4
      alias: gpt-image-full
      fork: true

payload:
  override-raw:
    - models:
        - name: gpt-image-1024x1024
          protocol: codex
      params:
        tools: '[{"type":"image_generation","size":"1024x1024","quality":"high","background":"auto"}]'
        tool_choice: '{"type":"image_generation"}'

实测限制：quality:"high" 写入 override-raw 仍然无法突破 Plus 封顶（响应仍 medium）。别名主要用途是选择底层模型（mini vs full）和固定 size。

/v1/responses 端点（Codex 原生，更丰富）

比 /v1/images/generations 支持更多参数：

curl -X POST http://<host>:8004/v1/responses \
  -d '{
    "model": "gpt-image-full",
    "input": [{"type":"message","role":"user","content":[{"type":"input_text","text":"<prompt>"}]}],
    "parallel_tool_calls": true,
    "reasoning": {"effort":"high","summary":"auto"},
    "stream": true,
    "store": false
  }'

SSE 响应 → 解析 event: response.output_item.done → output[].type=="image_generation_call" → result 字段为 base64 PNG。

架构：为何无 chat 窗口

chatgpt2api CLIProxyAPI 出站路径 chatgpt.com/backend-api/**conversation** chatgpt.com/backend-api/**codex** 产生 chat 记录 是（sidebar 可见） 否（Codex API，无 chat） CF 对抗 curl-cffi edge101 指纹 官方 Codex OAuth，免 CF 挑战 鉴权方式 手动粘 AccessToken（10d 过期） Codex OAuth（官方支持，长效）

已知局限

1. Plus 封顶 medium：high 质量需 Pro/Enterprise 订阅（未测）
2. transparent 不支持：Codex image tool 不接受此背景参数
3. gpt-image-2 非真实模型：实为 gpt-5.4-mini + image tool 的别名，不等同于 OpenAI 文档中 gpt-image-2 native 功能
4. OAuth token 不可跨机迁移：refresh token 单次使用（openai/codex#15502）
5. 高发布频率：建议 pin image digest
6. 共享账号风险：Plus 账号被封时所有依赖服务同时失效

适用场景决策矩阵

需求 建议 无 chat 窗口副作用的 gpt-image-2 调用 CPA 首选 高画质（print 级）图像 需 BYO API key + 原生 gpt-image-2 透明背景 BYO key 方案 Claude Code / Codex CLI OAuth 反代 CPA 专为此场景设计 多账号轮询 CPA 原生 round-robin

来源

• 官方 docs：Five: Docker Server Deployment | CLIProxyAPI
• 社区教程：抛砖引玉，教你如何使用CLIProxyAPI来自定义GPT画图模型
• 镜像：抛砖引玉，教你如何使用CLIProxyAPI来自定义GPT画图模型 - 失落之地
• PoC 验证文档：docs/task-files/2604/260423_cliproxyapi-poc_verification.md

Update 2026-04-24 — 提分辨率即提画质（重要修正）

之前文档说 “quality 参数无效、Plus 封顶 medium”，不够准确。实测补充：

Size → output_tokens → 实际画质（正相关）

Size Pixels output_tokens PNG 大小 标签 quality 1024x1024 simple prompt 1.0 MP ~200 500KB low 1024x1024 complex prompt 1.0 MP ~1400-1800 1.3 MB medium 3840x2160 (4K 横) 8.3 MP 3336 3.1 MB medium 2160x3840 (4K 竖) 8.3 MP 3336 3.7 MB medium 3072x3072 (超预算) 9.4 MP HTTP 400 — —

关键认知

• label quality 字段封顶 medium，但真实 compute budget 随 size 走
• 像素预算封顶 ≈ 8.3MP（8,294,400 像素），对应 3840x2160 或 2160x3840 长宽比 4K
• 实际画质 3-3.7MB PNG ≈ 1K medium 的 2-3 倍，实质达到 high tier 附近的 token budget（3336 / 3500 = 95%）
• 实用规避：要高画质 → size: "3840x2160" 不动 quality 参数，不走 override-raw 复杂配置

Implication

• 原文"要真正高画质需 BYO API key"修正为"4K 分辨率 on CPA 已基本达到 high 等效算力"
• 参数控制的正确姿势：用 size 控算力，quality 参数装饰品

1 个帖子 - 1 位参与者

阅读完整话题