ApiMonth

ApiMonth API 接入说明

使用生效中的美元积分和你自己的 API 密钥，把兼容客户端接到模型网关。

1. 账户与密钥

先登录、兑换美元积分包，再在控制台「API 密钥」页创建密钥。创建时请立即复制完整密钥，之后不再展示。

  • Base URL：https://gw.apimonth.com/v1
  • 鉴权：Authorization: Bearer YOUR_APIMONTH_API_KEY
  • 选择当前余额支持的已开放模型。网站登录 Cookie 不是模型 API 密钥。

主域名连不上时，改用备用 Base URL： https://api.apimonth.com/v1

Claude Code 备用地址为主机根域名，不要加 /v1： https://api.apimonth.com

SDK 或桌面客户端里填写 Base URL，不要再拼 /chat/completions。兼容性取决于接口和客户端；只改 Base URL 并不能让所有厂商专用客户端都能用。

2. 发送 Chat Completions 请求

下面示例按 Grok 订阅。请换成你自己的密钥，不要把真实密钥写进源码或前端。

curl
curl https://gw.apimonth.com/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY' \
  -d '{"model":"grok-4.7","messages":[{"role":"user","content":"Explain binary search briefly."}]}'

使用 openai SDK 的 Python（pip install openai）：

Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gw.apimonth.com/v1",
    api_key=os.environ["APIMONTH_API_KEY"],
)
response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

已开放的 Grok、GPT、Gemini 路由支持 JSON 与流式 SSE。客户端支持流式时设置 stream: true。

3. 使用 Responses 与 WebSocket

当前已开放的对话模型均可使用 Responses（纯生图模型除外）。HTTP 为 POST /v1/responses。推理字段是 reasoning.effort；Chat Completions 用 reasoning_effort。Grok 4.7 与 Grok 4.6 支持 low/medium/high（默认）/xhigh，reasoning 不能关闭。GPT-5.5 接受 none/low/medium/high/xhigh（max 会被拒绝）。GPT-5.6 与 GPT-6 系列还可使用 max。

WebSocket 为 wss://gw.apimonth.com/v1/responses，不是 realtime 音频。握手时带 Authorization: Bearer YOUR_API_KEY，不要放进 URL。发送 response.create，等待 response.completed，再用 previous_response_id 续写。每个 socket 同时只能有一个 in-flight create。不支持 response.cancel。

复制给 AI（Responses / WebSocket）
为 ApiMonth 配置 OpenAI 兼容客户端。

HTTP Responses（当前月卡已开放的对话模型均可）
- Base URL: https://gw.apimonth.com/v1
- API Key: YOUR_API_KEY
- 鉴权头: Authorization: Bearer YOUR_API_KEY
- 接口: POST https://gw.apimonth.com/v1/responses
- 模型名（不要加厂商前缀）: 用 GET /v1/models 返回的对话路由。例如 gpt-5.5、grok-4.7、grok-4.6、gemini-4-argon、gemini-3.8-flash、deepseek-flash、claude-sonnet-5-5、claude-opus-5-5、claude-sonnet-4-6、claude-opus-4-6。纯生图模型不能走 Responses。
- 推理字段: reasoning.effort（例如 {"reasoning":{"effort":"high"}}）。Chat Completions 用 reasoning_effort。
- GPT-5.5: none / low / medium / high / xhigh（max 会被拒绝）
- GPT-5.6-* 与 GPT-6 系列: 以上再加上 max
- Grok 4.7 与 Grok 4.6: low, medium, high（默认）, xhigh；reasoning 不能关闭
- Claude 5.5 与 Gemini 4 Argon: low、medium、high（默认）；Opus 5.5 不能关闭思考
- 请求体上限 32MiB

curl:
curl https://gw.apimonth.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"hello","reasoning":{"effort":"high"}}'

Python:
from openai import OpenAI
client = OpenAI(base_url="https://gw.apimonth.com/v1", api_key="YOUR_API_KEY")
r = client.responses.create(model="gpt-5.5", input="hello", reasoning={"effort":"high"})
print(r.output_text)

WebSocket（Responses WS，不是 realtime 音频）
- URL: wss://gw.apimonth.com/v1/responses?model=gpt-5.5
- 只在握手头带 Authorization: Bearer YOUR_API_KEY（不要把密钥放进 URL）
- 可选 ?model=；查询参数与 JSON 同时有 model 时必须一致
- model 必须是当前月卡已开放的对话路由（与 HTTP Responses 相同）
- 发送一条文本 JSON:
{"type":"response.create","model":"gpt-5.5","input":[{"role":"user","content":"hello"}],"reasoning":{"effort":"high"}}
- 等 {"type":"response.completed",...} 后再在同一连接发下一轮
- 续写上下文用 previous_response_id = completed response.id
- 不要发送 response.cancel 或 session.update
- 每个 socket 同时只能有一个 in-flight create；并行请另开连接
- 空闲或一轮响应: 5 分钟；1024 轮后请重连
- WS 消息大小 128KiB

4. Codex / OpenCode / Pi / Claude Code

把 YOUR_API_KEY 换成控制台密钥。模型用 GET /v1/models 返回的当前已开放对话路由。Responses 与 Responses WebSocket 对已开放对话模型均可用。

复制给 AI（全部客户端说明）
为 ApiMonth 配置常见编程代理（优先 Responses）。

协议建议
- 编码工具优先 Responses，客户端版本和供应商实现支持时优先 Responses WebSocket；不支持时使用 HTTP Responses（SSE）。
- 不建议编码工具默认采用 Chat Completions。SSE 流式响应不等于 WebSocket。
- Codex：wire_api = "responses"，supports_websockets = true。
- Pi：api = "openai-responses"；支持的版本在 /settings 中优先选择 Transport websocket-cached。
- OpenCode：使用支持 Responses 的 OpenAI 供应商实现与版本，并核对实际接口。仅在支持时开启 WebSocket，不要编造传输配置字段。
- Claude Code 例外：走 Anthropic Messages，不是 Responses/WebSocket。

共用
- Base URL: https://gw.apimonth.com/v1
- API Key: YOUR_API_KEY（控制台密钥；不要放进 URL）
- 模型: 用 GET /v1/models 返回的当前月卡路由标识（不要加厂商前缀）。对话模型支持 Chat Completions、Responses、Responses WebSocket；纯生图模型不行。
- 示例: gpt-5.5、gpt-5.6-sol、grok-4.7、grok-4.6、gemini-4-argon、gemini-3.8-flash、deepseek-flash、claude-sonnet-5-5、claude-opus-5-5、claude-sonnet-4-6、claude-opus-4-6
- Claude 5.5 与 Gemini 4 Argon 支持 low/medium/high，默认 high；Opus 5.5 不能关闭思考。

Codex CLI——保留原有会话和登录状态
1. 先备份 ~/.codex/config.toml 与 ~/.codex/auth.json。只把下方 provider 表合并进 config.toml，绝不能覆盖整个文件或 auth.json：
# MERGE this provider table into ~/.codex/config.toml.
# Do not replace the file, set CODEX_HOME, overwrite auth.json, or change the
# existing top-level model_provider: those actions can hide existing sessions.
[model_providers.apimonth]
name = "ApiMonth"
base_url = "https://gw.apimonth.com/v1"
experimental_bearer_token = "YOUR_API_KEY"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true
2. 新建独立 profile 文件：
# ~/.codex/apimonth.config.toml — Codex CLI 0.134+
# This profile activates ApiMonth only for an explicit CLI launch.
model = "gpt-5.5" # Or an admitted chat model from GET /v1/models
model_provider = "apimonth"
model_reasoning_effort = "high"
# plan_mode_reasoning_effort = "xhigh"
3. 显式启动：
codex --profile apimonth
Codex 当前会按活动 model provider 过滤普通历史记录和 resume 列表。启用 apimonth profile 时，openai 或其他 provider 创建的会话可能看起来消失，但文件通常仍在本机。去掉 --profile 按原方式启动，即可回到原 provider/历史。如果旧教程已经覆盖 auth.json，请恢复其备份；没有备份时，通过 Codex 正常的 ChatGPT 登录流程重新认证。绝不要把 ApiMonth 密钥写进 auth.json。Codex Desktop 目前没有可靠的跨 provider profile/全部历史选择器；把全局顶层 model_provider 改成 apimonth 可能隐藏原有 Desktop 会话。

可选 Codex 生图（需要单独明确选择）
对话配置不保证内置生图工具可用，也不会配置图片 CLI。参见 https://www.apimonth.com/docs#codex-images-zh。如我要求配置生图，先请我明确确认以下模式选择，再采用：
我明确选择：本项目需要生图或改图时，使用 imagegen skill 自带 scripts/image_gen.py 的 CLI/API 模式，通过 ApiMonth 调用 gpt-image-2。这是对 CLI fallback 的明确授权，不是要求修改系统 skill。
- 只执行我请求的图片任务；本次配置只检查，不生成付费图片。
- OPENAI_BASE_URL=https://gw.apimonth.com/v1；OPENAI_API_KEY 使用我自己的 ApiMonth 控制台密钥，不是 OpenAI 官方密钥。不需要另买 OpenAI API。
- config.toml / auth.json 的配置不会自动成为 Python CLI 的环境变量。检查实际运行 CLI 的进程是否同时收到上述两个变量，只报告是否存在和目标地址，绝不输出密钥。
- 不读取其他账户凭据，不把密钥写入 AGENTS.md、源码、命令历史或聊天。缺少密钥时指导我在本机安全设置。
- 使用已安装 skill 的脚本，尊重 CODEX_HOME；未设置时默认 ~/.codex。脚本缺失或 Python/openai 依赖未安装时明确报告，不编造脚本或修改系统 skill。
- 显式 --model gpt-image-2 --n 1；产物保存到项目 output/imagegen/。不要把 Codex 对话模型改成 gpt-image-2。
- 所有生图/改图模型（GPT Image、Grok Imagine，以及内置工具）统一在原图成功落盘后做独立无损优化，不修改请求、JSON/SSE、计费或系统 skill。先从 https://www.apimonth.com/tools/optimize-image.py 下载并审阅脚本，保存为项目 tools/optimize-image.py；缺失或下载受阻时保留原图并报告，不绕过审批。
- 图片生成完成后运行 python tools/optimize-image.py <原图路径>。仅较小的静态非交错 PNG 会写入独立 .optimized.png；尺寸、位深、透明度、原始扫描行和元数据不变。JPEG/WebP、动画、带签名图片或无收益时保持原文件，不声称所有格式都压缩成功。向用户同时提供原图与脚本返回的 download 路径。
- 优化器仅本地运行，无依赖包、不联网、不需要密钥，不产生额外模型费用。优化失败只保留原图，绝不因此重新生图。仅配置检查或 --dry-run 时不执行产物优化。第三方客户端需接入这个保存后步骤，API 不会自动替换图片。
- 先用 --dry-run 检查参数；它不联网，也不能证明鉴权、余额或上游可用。实际生成按 ApiMonth 图片价格扣费。
- 内置 image_gen 是否可用取决于客户端版本与登录上下文；requires_openai_auth=true 不是开启生图工具的开关。不要仅凭模型自述认定工具可用。
- 保留现有沙箱和审批边界。若环境变量被客户端过滤，报告问题；不要关闭沙箱或扩大密钥继承范围。可在已安全配置的终端直接运行 CLI。
- 失败时报告脱敏错误、HTTP 状态和请求时间，不自动切换 OpenAI 官方、其他模型或供应商，不无限重试。网关不支持 mask，每次仅一张。

OpenCode（~/.config/opencode/opencode.json）
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://gw.apimonth.com/v1",
        "apiKey": "YOUR_API_KEY"
      }
    }
  },
  "model": "gpt-5.5"
}

Pi（~/.pi/agent/models.json）
{
  "providers": {
    "apimonth": {
      "baseUrl": "https://gw.apimonth.com/v1",
      "api": "openai-responses",
      "apiKey": "YOUR_API_KEY",
      "models": [
        { "id": "gpt-5.5", "reasoning": true },
        { "id": "gpt-5.6-sol", "reasoning": true },
        { "id": "grok-4.7", "reasoning": true },
        { "id": "grok-4.6", "reasoning": true },
        { "id": "gemini-4-argon", "reasoning": true },
        { "id": "gemini-3.8-flash", "reasoning": true },
        { "id": "deepseek-flash", "reasoning": true },
        { "id": "claude-sonnet-5-5", "reasoning": true },
        { "id": "claude-opus-5-5", "reasoning": true },
        { "id": "claude-sonnet-4-6", "reasoning": true },
        { "id": "claude-opus-4-6", "reasoning": true }
      ]
    }
  }
}
然后在 Pi 里用 /model 选择 apimonth 下的模型。若客户端走 Responses WebSocket，建议在 /settings 把 Transport 设为 websocket-cached。

Claude Code
# Claude Code talks Anthropic Messages. Base URL is the host root, not /v1.
export ANTHROPIC_BASE_URL=https://gw.apimonth.com
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
# Optional equivalent: export ANTHROPIC_API_KEY=YOUR_API_KEY
# Chat models: Claude, GPT, Grok (e.g. claude-sonnet-5-5, claude-opus-5-5, claude-sonnet-4-6, gpt-5.5, grok-4.7, grok-4.6). Gemini is not available in Claude Code.
- 只走 Anthropic Messages：POST /v1/messages。可用 Claude、GPT、Grok 对话路由（claude-sonnet-5-5、claude-opus-5-5、claude-sonnet-4-6、gpt-5.5、grok-4.7、grok-4.6 等），不要加厂商前缀。
- Gemini、DeepSeek 编码任务请在其他兼容客户端中使用 Responses。纯生图模型使用 Images 接口；Claude Code 不会列出或调用这些路由。

Codex CLI / Codex App

不要整份覆盖 ~/.codex/config.toml 或 auth.json，也不要另设 CODEX_HOME。Codex 当前会按活动 model_provider 过滤历史列表；全局切换到自定义 provider 后，原 provider 的会话可能看起来全部消失，但通常仍保存在 ~/.codex/sessions 与本地状态库中。

安全接入方式：先备份原文件，只把 ApiMonth provider 表合并进原 config.toml；再新建独立的 ~/.codex/apimonth.config.toml，用 codex --profile apimonth 显式启动 CLI。退出后按原方式启动即可回到原 provider 的历史。Codex Desktop 当前没有可靠的跨 provider profile/全部历史选择器，不建议需要保留统一历史的用户把全局顶层 model_provider 改成 apimonth。

设置 supports_websockets = true。Codex CLI 0.155.1 已通过 ApiMonth Responses WebSocket 端到端验证。

合并到 ~/.codex/config.toml（不要覆盖）
# MERGE this provider table into ~/.codex/config.toml.
# Do not replace the file, set CODEX_HOME, overwrite auth.json, or change the
# existing top-level model_provider: those actions can hide existing sessions.
[model_providers.apimonth]
name = "ApiMonth"
base_url = "https://gw.apimonth.com/v1"
experimental_bearer_token = "YOUR_API_KEY"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true
~/.codex/apimonth.config.toml
# ~/.codex/apimonth.config.toml — Codex CLI 0.134+
# This profile activates ApiMonth only for an explicit CLI launch.
model = "gpt-5.5" # Or an admitted chat model from GET /v1/models
model_provider = "apimonth"
model_reasoning_effort = "high"
# plan_mode_reasoning_effort = "xhigh"
启动 Codex CLI
codex --profile apimonth

恢复已有会话：完全退出 Codex App，把顶层 model_provider/model 恢复为接入前的值（通常 provider 是 openai），保留 provider 定义即可。如果旧教程已经覆盖 auth.json，请恢复备份；没有备份时，通过 Codex 正常的 ChatGPT 登录流程重新认证，绝不要把 ApiMonth 密钥写进 auth.json。不要删除或批量改写 sessions、SQLite 或 JSONL。重新打开后历史通常会恢复显示。

对话能用不代表生图已配置。纯 API Key 模式可能没有内置图片工具；请继续阅读 Codex 生图配置，无需另外购买 OpenAI API。

OpenCode

创建或编辑 ~/.config/opencode/opencode.json。使用支持 Responses 的 OpenAI 供应商实现；客户端版本支持时优先 Responses WebSocket，否则使用 HTTP Responses。此配置不保证自动启用 WebSocket，不要添加未经确认的传输参数。

~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://gw.apimonth.com/v1",
        "apiKey": "YOUR_API_KEY"
      }
    }
  },
  "model": "gpt-5.5"
}

Pi

在 ~/.pi/agent/models.json 增加 openai-responses 供应商（不要对 ApiMonth 使用 CLIProxyAPI 专用 npm 插件）。再用 /model 选择。若支持 Responses WebSocket，可在 /settings 把 Transport 设为 websocket-cached。

~/.pi/agent/models.json
{
  "providers": {
    "apimonth": {
      "baseUrl": "https://gw.apimonth.com/v1",
      "api": "openai-responses",
      "apiKey": "YOUR_API_KEY",
      "models": [
        { "id": "gpt-5.5", "reasoning": true },
        { "id": "gpt-5.6-sol", "reasoning": true },
        { "id": "grok-4.7", "reasoning": true },
        { "id": "grok-4.6", "reasoning": true },
        { "id": "gemini-4-argon", "reasoning": true },
        { "id": "gemini-3.8-flash", "reasoning": true },
        { "id": "deepseek-flash", "reasoning": true },
        { "id": "claude-sonnet-5-5", "reasoning": true },
        { "id": "claude-opus-5-5", "reasoning": true },
        { "id": "claude-sonnet-4-6", "reasoning": true },
        { "id": "claude-opus-4-6", "reasoning": true }
      ]
    }
  }
}

Claude Code

设置 ANTHROPIC_BASE_URL=https://gw.apimonth.com（根域名，不要加 /v1）和 ANTHROPIC_AUTH_TOKEN。可用 Claude、GPT、Grok 对话模型，例如 claude-sonnet-4-6、gpt-5.5、grok-4.7、grok-4.6。Gemini、DeepSeek 和纯生图不能走 Claude Code，请继续用 Chat Completions / Responses。

Claude Code 环境变量
# Claude Code talks Anthropic Messages. Base URL is the host root, not /v1.
export ANTHROPIC_BASE_URL=https://gw.apimonth.com
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
# Optional equivalent: export ANTHROPIC_API_KEY=YOUR_API_KEY
# Chat models: Claude, GPT, Grok (e.g. claude-sonnet-5-5, claude-opus-5-5, claude-sonnet-4-6, gpt-5.5, grok-4.7, grok-4.6). Gemini is not available in Claude Code.

5. 查看当前套餐的模型列表

已开放路由标识示例：

  • Grok：grok-4.7、grok-4.6、grok-4.5（对话 / Responses / Anthropic Messages；grok-4.7 上下文 500k，官方长 context 规则：以 prompt/input tokens 含缓存判定阈值，≥ 200k 时整个请求含输出全额按 2 倍长 context 费率计费，非 input+output 总量判定，亦非超出部分阶梯累进；折后短档输入 $0.60 / 缓存 $0.15 / 输出 $1.80 每 1M，长档整请求输入 $1.20 / 缓存 $0.30 / 输出 $3.60 每 1M，线上按 CNY 平价 credits 结算）；生图：grok-imagine-image、grok-imagine-image-2.0、grok-imagine-image-quality；视频：grok-imagine-video-1.5（别名 grok-imagine-video）
  • GPT：gpt-6-astra、gpt-6-sol、gpt-6-luna、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5（对话 / Responses / Anthropic Messages）。GPT-6 Sol 官方短上下文价为输入 $2 / 缓存 $0.20 / 输出 $10，本站三折后为 $0.60 / $0.06 / $3；GPT-6 Luna 官方价为 $0.10 / $0.01 / $0.50，本站八折后为 $0.08 / $0.008 / $0.40。GPT-6 Sol / Luna 上下文 1.05M，输入超过 272k 时整次请求的输入与缓存按 2 倍、输出按 1.5 倍结算。gpt-6.1-sol 与 gpt-6.1-sol-fast 仅 Responses；Fast 由网关改写为 gpt-6.1-sol 并设置 service_tier: priority，按 2 倍计价。gpt-6-sol-fast 和 gpt-6-luna-fast 由网关追加 service_tier: priority，按对应标准或长上下文价格的 2 倍计费。生图：gpt-image-1.5、gpt-image-2、gpt-image-2.5
  • GPT Fast（Codex 快速通道，service_tier: priority）：gpt-5.6-sol-fast、gpt-5.6-terra-fast、gpt-5.6-luna-fast、gpt-5.5-fast。同一模型、更快返回，上游按 2 倍额度计费，因此单价是普通路由的 2 倍。快速通道只由路由决定：普通路由里手写的 service_tier 会被网关移除，Fast 路由会自动带上 priority。
  • Gemini：gemini-3.8-flash（对话 / Responses）。思考强度用 reasoning_effort，不要把 high/low 写成独立模型。Gemini 生图未开放。
  • DeepSeek：deepseek-flash（DeepSeek V4.1 Flash，对话 / Responses）。不分高峰和低谷。标价输入 $1、输出 $4，五折后输入 $0.50、输出 $2（每百万 token）。生图未开放。
  • Claude：claude-sonnet-4-6、claude-opus-4-6（对话 / Responses / Anthropic Messages）。不要加 anthropic/ 前缀。生图未开放。Claude Code 列出 Claude、GPT、Grok 对话模型，不支持 Gemini。

这不是完整或永久列表。不要加厂商前缀，也不要用展示名代替路由标识。公开 模型目录 以及 GPT、Grok、Gemini、DeepSeek、Claude 模型页可对照。查询当前可用模型：

curl
curl https://gw.apimonth.com/v1/models \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY'

6. 图片与视频生成

Qwen Image 2.1 Turbo：画布客户端接入

Base URL：https://gw.apimonth.com/v1；鉴权：Authorization: Bearer YOUR_API_KEY。模型名固定为 qwen-image-2.1，后端使用官方 Turbo、MLX Q8、8 步。生图使用 POST /v1/images/generations；改图使用 POST /v1/images/edits，JSON 的 images 为包含 image_url 的对象数组，值为完整图片 data URL。

stream=false（默认）返回 JSON，图片读取 data[0].b64_json。stream=true 返回 text/event-stream：开始及等待期间发送 : keepalive 注释心跳（约每 10 秒），完成事件为 image_generation.completed 或 image_edit.completed，图片读取事件的 b64_json，output_format=png。成功结算后发送完成事件；失败发送 event: error。没有局部预览图，流式不会缩短推理时间，也不能保证客户端不会主动超时。

仅支持 n=1、response_format=b64_json 和 PNG。宽高均为 256–1024 内的 64 倍数；生图默认 1024×1024，改图默认 512×512。quality 省略或 auto；partial_images 省略或 0。不支持 input_fidelity、output_compression、透明背景。改图支持 1–5 张 PNG/JPEG/WebP data URL，每张最多 8 MiB，总 JSON 最多 32 MiB，不支持远程图片 URL。每次成功生成按目录每张价格结算一次；生成失败不扣费。断流不代表生成失败，不要自动重发，应保留 X-Request-ID 核对。

Qwen SSE JSON
{"model":"qwen-image-2.1","prompt":"白色桌面上的红苹果","size":"512x512","n":1,"response_format":"b64_json","output_format":"png","stream":true}

SHUO Canvas 接入 Grok / GPT：文档地址使用 https://www.apimonth.com/zh-cn/docs#images-zh，Base URL 为 https://gw.apimonth.com/v1，协议为 OpenAI Images。可选模型 grok-imagine-image-2.0、gpt-image-2、gpt-image-2.5。需要流式时设置 stream=true，解析最终 image_generation.completed / image_edit.completed 事件的 b64_json，不要按 Chat Completions 解析。Grok 2.0 配合 output_format=png 时，网关对 JSON 及 SSE 中实际返回的 JPEG 执行 PNG 转换，流式预览和最终图均适用；生成与计费不重复。已生成但最终转换失败时，返回 image_delivery_unavailable，应保留请求 ID 核对，不要自动重试。GPT 的局部预览可设置 partial_images；Grok 建议省略，不保证提供预览。重新读取文档并保存模型配置后再使用。

Grok Imagine 与 GPT Image 使用 POST /v1/images/generations 和 POST /v1/images/edits，不能走 Chat Completions。每次一张。size 与 quality 会转发但不保证；实测 GPT Image 1024x1024 返回 1254×1254。改图使用 data: 图片，不能用远程 http 图链。Gemini 生图未开放。生图按目录「每张」计价（默认三折，当前折扣以官网实时模型价为准），不按上下文 token。已开始的请求保留当时快照。宣传范围不含缓存写入。

必填 model、prompt（1–4000 字符）。可选 n=1、size、quality、background（auto/opaque/transparent）、response_format=b64_json、output_format（png/jpeg/webp）、output_compression（0–100 整数）、moderation（auto/low）、user（最多 256 字节）、stream；流式请求另可设置 partial_images（0–3）。编辑另支持 input_fidelity（high/low）。模型支持情况以上游为准。

省略 stream 或设为 false 时返回 JSON。设为 true 时返回 SSE：中间事件为 image_generation.partial_image / image_edit.partial_image，最终事件为对应的 .completed，Base64 在 b64_json。GPT Image 可返回局部预览；Grok Imagine 可能只有心跳与最终图。最终事件会在用量验证和结算成功后发送；收到局部图或心跳后断流时不要自动重发，以免重复生成和扣费。partial_images 大于 0 时必须同时设置 stream=true。

编辑可用 JSON 的 images 数组，也可用 multipart 的 image、image[]、images 或 images[] 同名字段上传 1–5 张 PNG/JPEG/WebP，每张最多 8 MiB；不支持 mask。生成请求最多 128 KiB，编辑最多 32 MiB。400 请查看 error.message / error.param；请求体超限返回 413，不要盲目重试。不要把 gpt-image-2 当作 Responses 对话模型。

所有生图模型：保存后无损优化

GPT Image、Grok Imagine 和内置图片工具均可在保存原图后，使用同一个离线优化脚本。下载、审阅后保存为项目 tools/optimize-image.py，使用 Python 3.9+ 运行：

离线优化已有图片，不调用模型
python tools/optimize-image.py "output/imagegen/result.png"

仅较小的静态非交错 PNG 另存为 .optimized.png；保留原图、像素、尺寸、位深、透明度和元数据。JPEG/WebP、动画、签名图片及无收益的文件保持原样。脚本输出 JSON 中的 download 是最终可用文件路径，原图仍可单独下载。工具不联网、不需要密钥，不新增生成费用；失败不重试生图。

这是客户端保存后的独立处理，不会改写 API 的 JSON/SSE、压缩中间预览或修改系统 skill。第三方客户端需自行接入；不能据此声称所有 API 调用已自动压缩，也不会减少已经发生的 API 传输量、图片 token 或生成单价。

Codex 生图：单独配置 CLI/API 模式

内置 image_gen 的可用性取决于客户端版本、登录上下文及工具是否暴露；requires_openai_auth=true 不保证开启工具。若出现「没有内置图片工具」或「需要确认 fallback」，这不等于网关生图故障。不要修改系统 skill 来绕过确认，也不要将 Codex 对话模型改成 gpt-image-2。

下方模板由你主动复制并发送给 Codex，即明确选择 CLI/API 模式。若希望作为项目默认，可将确认后的规则追加到 AGENTS.md（不写密钥，不覆盖原规则）。仅配置不会生成图片；实际调用按 ApiMonth 价格扣费。

明确选择图片 CLI（复制给 Codex）
我明确选择：本项目需要生图或改图时，使用 imagegen skill 自带 scripts/image_gen.py 的 CLI/API 模式，通过 ApiMonth 调用 gpt-image-2。这是对 CLI fallback 的明确授权，不是要求修改系统 skill。
- 只执行我请求的图片任务；本次配置只检查，不生成付费图片。
- OPENAI_BASE_URL=https://gw.apimonth.com/v1；OPENAI_API_KEY 使用我自己的 ApiMonth 控制台密钥，不是 OpenAI 官方密钥。不需要另买 OpenAI API。
- config.toml / auth.json 的配置不会自动成为 Python CLI 的环境变量。检查实际运行 CLI 的进程是否同时收到上述两个变量，只报告是否存在和目标地址，绝不输出密钥。
- 不读取其他账户凭据，不把密钥写入 AGENTS.md、源码、命令历史或聊天。缺少密钥时指导我在本机安全设置。
- 使用已安装 skill 的脚本，尊重 CODEX_HOME；未设置时默认 ~/.codex。脚本缺失或 Python/openai 依赖未安装时明确报告，不编造脚本或修改系统 skill。
- 显式 --model gpt-image-2 --n 1；产物保存到项目 output/imagegen/。不要把 Codex 对话模型改成 gpt-image-2。
- 所有生图/改图模型（GPT Image、Grok Imagine，以及内置工具）统一在原图成功落盘后做独立无损优化，不修改请求、JSON/SSE、计费或系统 skill。先从 https://www.apimonth.com/tools/optimize-image.py 下载并审阅脚本，保存为项目 tools/optimize-image.py；缺失或下载受阻时保留原图并报告，不绕过审批。
- 图片生成完成后运行 python tools/optimize-image.py <原图路径>。仅较小的静态非交错 PNG 会写入独立 .optimized.png；尺寸、位深、透明度、原始扫描行和元数据不变。JPEG/WebP、动画、带签名图片或无收益时保持原文件，不声称所有格式都压缩成功。向用户同时提供原图与脚本返回的 download 路径。
- 优化器仅本地运行，无依赖包、不联网、不需要密钥，不产生额外模型费用。优化失败只保留原图，绝不因此重新生图。仅配置检查或 --dry-run 时不执行产物优化。第三方客户端需接入这个保存后步骤，API 不会自动替换图片。
- 先用 --dry-run 检查参数；它不联网，也不能证明鉴权、余额或上游可用。实际生成按 ApiMonth 图片价格扣费。
- 内置 image_gen 是否可用取决于客户端版本与登录上下文；requires_openai_auth=true 不是开启生图工具的开关。不要仅凭模型自述认定工具可用。
- 保留现有沙箱和审批边界。若环境变量被客户端过滤，报告问题；不要关闭沙箱或扩大密钥继承范围。可在已安全配置的终端直接运行 CLI。
- 失败时报告脱敏错误、HTTP 状态和请求时间，不自动切换 OpenAI 官方、其他模型或供应商，不无限重试。网关不支持 mask，每次仅一张。

Windows PowerShell：在项目目录运行。密钥填写 ApiMonth 控制台密钥，不是 OpenAI 官方密钥。下例隐藏输入，不将密钥写进命令历史；两个环境变量必须在实际执行 Python 的进程中生效。只配置 config.toml 或 auth.json 不够。

PowerShell：安全配置与 dry-run
# Run from the project directory. Requires Python and the installed imagegen skill.
python -m pip install openai
$env:OPENAI_BASE_URL = "https://gw.apimonth.com/v1"
$secret = Read-Host "ApiMonth API key (hidden input)" -AsSecureString
$env:OPENAI_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
$secret.Dispose()
Remove-Variable secret
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$imageGen = Join-Path $codexHome "skills/.system/imagegen/scripts/image_gen.py"
if (!(Test-Path $imageGen)) { throw "Installed imagegen script not found: $imageGen" }
python -c "import os; from openai import OpenAI; c=OpenAI(); assert str(c.base_url).rstrip('/') == 'https://gw.apimonth.com/v1'; print('ApiMonth endpoint configured; key present:', bool(os.getenv('OPENAI_API_KEY')))"
# No network call or image charge. Remove --dry-run only to request a paid image.
python $imageGen generate --model gpt-image-2 --n 1 --prompt "A kitten drinking water" --out "output/imagegen/kitten.png" --dry-run
# Optional post-save setup: download from https://www.apimonth.com/tools/optimize-image.py, review,
# and save the script as tools/optimize-image.py (do not modify the system skill).
# After a requested live image is saved, not during --dry-run:
# python tools/optimize-image.py "output/imagegen/kitten.png"
# On failure keep the original; never repeat a paid generation to optimize it.
# When finished with all image requests in this terminal:
# Remove-Item Env:OPENAI_API_KEY

此配置仅对当前终端及继承其环境的子进程有效，不会更新已打开的 Codex App。客户端可能过滤含 KEY 的环境变量；请在实际执行进程中只检查是否存在，不打印值。若无法继承，可直接在此终端运行图片 CLI，不要关闭沙箱。macOS/Linux 同样需要在执行 CLI 的进程中安全设置 OPENAI_BASE_URL 和 OPENAI_API_KEY。

dry-run 不联网，不能证明鉴权或上游可用。准备生成时去掉 --dry-run；成功后确认 output/imagegen/ 下存在实际图片。缺少 Python/openai/skill 脚本时先修复安装；401/403 核对目标地址、密钥及权限，400 核对参数，429/5xx 保留脱敏错误和时间，不无限重试。不要发送密钥给客服。

images/generations
curl https://gw.apimonth.com/v1/images/generations \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY' \
  -d '{"model":"gpt-image-2","prompt":"A red circle on white","n":1,"stream":false,"output_format":"png"}'
images/generations（SSE 流式）
curl -N https://gw.apimonth.com/v1/images/generations \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY' \
  -d '{"model":"gpt-image-2","prompt":"A red circle on white","n":1,"stream":true,"partial_images":2,"output_format":"png"}'

改已有 PNG（JSON）。Grok Imagine 要求源图至少 8×8。

images/edits
curl https://gw.apimonth.com/v1/images/edits \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY' \
  -d '{"model":"gpt-image-2","prompt":"Make the circle blue","images":[{"image_url":"data:image/png;base64,SOURCE_PNG_BASE64"}]}'

Grok 视频

grok-imagine-video-1.5 先调用 POST /v1/videos/generations，再用返回的 request_id 调用 GET /v1/videos/{request_id} 轮询。当前开放文本生成视频；时长 1–15 秒，默认 8 秒。按完成视频的实际秒数以 $0.05/秒计费；提交时冻结请求时长额度，失败或过期全额解冻。

videos/generations
curl https://gw.apimonth.com/v1/videos/generations \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APIMONTH_API_KEY' \
  -d '{"model":"grok-imagine-video-1.5","prompt":"A paper boat at sunrise","duration":6,"aspect_ratio":"16:9","resolution":"720p"}'

Python 先生成，再用本地文件改图：

Python
import base64, os
from openai import OpenAI

client = OpenAI(
    base_url="https://gw.apimonth.com/v1",
    api_key=os.environ["APIMONTH_API_KEY"],
)
image = client.images.generate(
    model="gpt-image-2",
    prompt="A red circle on white",
)
print(image.data[0].b64_json is not None)

with open("source.png", "rb") as f:
    png = base64.b64encode(f.read()).decode()
edited = client.post(
    "/images/edits",
    body={
        "model": "gpt-image-2",
        "prompt": "Make the circle blue",
        "images": [{"image_url": f"data:image/png;base64,{png}"}],
    },
    cast_to=object,
)

7. 余额与失败

用量默认三折，Gemini 与 GPT Luna 系列八折，Grok 对话三折，生图按模型每张 $0.01–$0.08，Grok Video 1.5 为 $0.05 / 秒，当前折扣以官网实时模型价为准，从共用额度扣费，不一定等于上游发票单价。新积分包兑换后 30 天有效；历史卡转为不可提现的永久余额。请在账户中查看余额与扣费流水。

到账规则：余额与模型价用同一个 $ 单位，¥1 = $1 额度。微信/支付宝 1:1 到账（¥220 → $220）；PayPal 收美元，按 1 美元 = ¥6.8 折算（钱包 $10 → $68；¥40 积分包收 $5.88）。汇率在下单时锁定。

  • 鉴权或模型权限错误：检查密钥、账户状态、余额是否有效，以及所选模型。
  • HTTP 429：阅读错误信息。可能是余额、并发或速率限制；减少并行或稍后再试。
  • 上游错误：保留错误详情与请求时间再排查，避免无控制重试。

断开客户端不一定会取消上游计算。已完成的上游用量仍可能写入扣费流水。

8. 购卡与退款

  • 可在商店用微信/支付宝，或在控制台用 PayPal 购买美元积分包，再到本站兑换。新包 30 天自兑换起算。
  • 未兑换的微信/支付宝积分包按商店原支付路径退款。
  • 已兑换不能退款，积分不可提现。

打开控制台