Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cliproxy-image-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

cliproxy-image-cli

English

可安装的 Codex 原生图片 CLI。它会自动复用本机 Codex 的 OpenAI 兼容配置，把图片生成与图片编辑能力直接带到命令行。

项目亮点

Codex 原生复用：自动读取本地 Codex 的 base_url 与 OPENAI_API_KEY
双命令覆盖：同时支持 generate 与 edit
多种图片输入：支持本地文件、URL、data: 图片
本地文件友好：支持文件输出、目录输出、覆盖保护与 metadata 导出
自动接口偏好记忆：同一上游成功过的链路会被缓存，后续优先复用
适合 Skill / Shell / 自动化：可直接用于 Codex skill、终端脚本和流水线

功能特性

generate：调用 /v1/images/generations
edit：调用 /v1/images/edits
自动发现本地 Codex 配置与认证信息
自动把本地图片转换为 data: URL 再上送
当直连图片接口不可用时，可回退到 /v1/responses
支持输出保存结果对应的 metadata JSON

运行要求

Node.js 18+
本机已安装 Codex
Codex 已配置可用的 OpenAI 兼容上游
上游至少支持以下其中一种：
- /v1/images/*
- 基于 /v1/responses 的图片生成 / 编辑链路

安装方式

npm

npm install -g cliproxy-image-cli

Homebrew

brew tap noooob-coder/tap
brew install cliproxy-image-cli

项目结构

bin/
  cliproxy-image-cli.js        # CLI 入口
lib/
  image-cli.js                 # 核心命令流程、接口调用、保存逻辑
Formula/
  cliproxy-image-cli.rb        # Homebrew Formula
skill_src/
  cliproxy-image-cli/          # Codex skill 包装与 agent 配置
README.md                      # 中文说明
README.en.md                   # 英文说明
package.json                   # npm 包定义

这个结构对应三层能力：

CLI 运行层：bin/ 与 lib/
分发安装层：package.json 与 Formula/
Codex 集成层：skill_src/

快速开始

CLI 默认会从本机 Codex 目录读取：

~/.codex/config.toml
~/.codex/auth.json

所以通常不需要手动传 base URL、端口或 API key。

生成图片

cliproxy-image-cli generate \
  --output ./astronaut-cat.png \
  --size 1024x1024 \
  --quality high \
  "一只戴着宇航员头盔的电影感橘猫"

编辑图片

cliproxy-image-cli edit \
  --image ./input.png \
  --mask ./mask.png \
  --output ./edited.png \
  "保留主体不变，把背景替换成雪山"

同时保存 metadata

cliproxy-image-cli \
  --metadata-path ./request.json \
  generate \
  --output ./result.png \
  "日出时分的水彩风景"

如果省略 --output，CLI 会默认把图片保存到当前工作目录，并自动生成清晰的默认文件名，避免直接覆盖已有文件。尺寸策略与 imagegen 一致：默认 1024x1024，可选 1024x1024、1536x1024、1024x1536 或 auto。

架构图

运行链路

flowchart LR
    user[用户 / Codex Skill]
    cli[cliproxy-image-cli]
    parser[参数解析与命令分发]
    codex[读取 ~/.codex/config.toml 与 auth.json]
    normalize[规范化 prompt / image / mask / output]
    direct[/v1/images/generations 或 /v1/images/edits/]
    fallback[/v1/responses 回退链路/]
    upstream[OpenAI 兼容上游]
    decode[解析 b64_json / data URL / output item]
    save[保存文件、metadata、摘要]

    user --> cli --> parser
    parser --> codex
    parser --> normalize
    codex --> direct
    codex --> fallback
    normalize --> direct
    normalize --> fallback
    direct --> upstream --> decode --> save
    fallback --> upstream

自动发现与接口偏好缓存

flowchart TD
    start[启动命令]
    home[确定 CODEX_HOME 或 ~/.codex]
    config[读取 config.toml]
    auth[读取 auth.json]
    cache[读取接口偏好缓存]
    prefer{该 base_url + 动作是否已有成功链路}
    call1[优先走缓存中的链路]
    call2[按默认顺序探测可用链路]
    ok{请求成功?}
    refresh[刷新偏好缓存]
    done[输出图片与 metadata]
    retry[自动尝试另一条链路]

    start --> home --> config --> auth --> cache --> prefer
    prefer -- 是 --> call1 --> ok
    prefer -- 否 --> call2 --> ok
    ok -- 是 --> refresh --> done
    ok -- 否 --> retry --> ok

命令说明

全局参数

--timeout <seconds>：请求超时秒数，默认 300
--metadata-path <file>：把保存结果与响应信息写入 JSON
--overwrite：允许覆盖已有输出文件

`generate`

cliproxy-image-cli generate [options] [--output <file|dir>] <prompt>

可选参数：

--model <name>：默认 gpt-image-2
--prompt-file <file>
--output <file|dir>
--size <WxH>：1024x1024|1536x1024|1024x1536|auto（默认 1024x1024）
--quality <value>
--background <value>
--moderation <value>
--partial-images <count>
--output-format png|jpeg|webp
--response-format b64_json|url

`edit`

cliproxy-image-cli edit [options] --image <path|url> [--output <file|dir>] <prompt>

可选参数：

--image <path|url>：可重复，必填
--mask <path|url>
--output <file|dir>
其余生成共享参数与 generate 一致
--input-fidelity <value>

自动发现机制

CLI 按以下顺序解析运行凭据：

优先读取 CODEX_HOME，否则使用 ~/.codex
从 config.toml 读取当前 model_provider 及其 base_url
从 auth.json 读取 OPENAI_API_KEY

如果 Codex 指向的是一个暴露 /v1 的 OpenAI 兼容上游，CLI 会自动把图片请求映射到：

.../v1/images/generations
.../v1/images/edits

用户无需关心端口或 base URL。

接口偏好缓存

如果某个上游只有一条链路真正可用：

直连图片接口：/v1/images/generations / /v1/images/edits
或 Responses 回退：/v1/responses

CLI 会把这次成功的传输方式缓存到：

~/.codex/cliproxy-image-cli-preferences.json

后续同一 base_url 下的同类请求会优先复用已成功的链路，而不是每次都循环探测所有接口。

缓存规则：

按 base_url + generate/edit 分开记录
generate 和 edit 分别维护自己的成功链路
如果缓存的优先链路失效，CLI 会自动尝试另一条链路并刷新缓存

故障排查

如果自动发现成功，但当前 Codex 上游并没有真正实现图片接口，CLI 会输出更明确的诊断信息，包括：

发现到的 Codex base URL
实际调用的图片端点
当前模型名
上游返回的错误文本

典型输出示例：

Error: The local Codex configuration was discovered successfully, but the current upstream provider does not support image generation.
Base URL: http://your-provider/v1
Endpoint: http://your-provider/v1/images/generations
Model: gpt-image-2
Upstream response: upstream did not return image output
Action: point Codex at an OpenAI-compatible provider that implements the image endpoints.

如果看到这类报错，通常说明：

CLI 本身工作正常
当前需要调整的是 Codex 的 model_provider / base_url
目标上游需要支持 /v1/images/* 或支持图片的 /v1/responses

许可证

本项目不再使用 MIT。

允许：个人学习、研究、评估、内部非商用测试
禁止：未获授权的商用、转售、付费分发、SaaS/托管/API 商业服务集成
商用与出售：必须事先获得作者单独书面授权，并支付商业许可费用

完整条款见 LICENSE。