flexgate 0.6.0__tar.gz → 0.8.0__tar.gz

{flexgate-0.6.0 → flexgate-0.8.0}/CLAUDE.md

@@ -22,6 +22,7 @@ flexgate service install                    # install + enable + start systemd u
 flexgate service {install|start|stop|restart|reload|status|uninstall}
 flexgate run                                # foreground/debug only
 flexgate status                             # providers, fallback chains, per-key usage, active routes
+flexgate usage [--force]                    # per-key usage/quota only; --force rechecks cached failures
 flexgate log                                # service journal (-f follow, -r route lines only)
 
 # Config
@@ -73,10 +74,13 @@ without a systemd user instance.
 
 ```
 Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
-  → server.py   (Starlette app, single route)
+  → server.py   (Starlette app, /v1/messages + /v1/images/* routes)
   → router.py   (resolve(): regex match model, check schedule windows first, then default routes)
   → proxy.py    (rewrite model field if override, swap x-api-key, SSE streaming pass-through)
   → Upstream provider (z.ai, minimax, xiaomi, etc.)
+
+OpenAI-style client → POST /v1/images/generations
+  → images.py   (translate to MiniMax /v1/image_generation; provider auto-detected by base_url)
 ```
 
 ### Source files (`flexgate/`)
@@ -89,7 +93,9 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 | `router.py` | `resolve(config, model)` — schedule-first then default routes, first regex match wins; model aliases normalized before matching |
 | `proxy.py` | `handle_request()` — httpx async proxy, per-key fallback retry loop, SSE streaming + JSON pass-through |
 | `usage.py` | `flexgate status` usage queries — per-platform adapters (MiniMax coding_plan API, Kimi Code usages API, z.ai quota API, LiteLLM `/key/info`) plus a minimal chat probe fallback |
-| `server.py` | Starlette app creation, `POST /v1/messages` endpoint, `SIGUSR1` lifespan reload |
+| `server.py` | Starlette app creation, `POST /v1/messages` + `POST /v1/images/{generations,edits}` endpoints, `SIGUSR1` lifespan reload |
+| `images.py` | OpenAI Images API → MiniMax `/v1/image_generation` translation (`image-01`, size→width/height clamped to 512–2048 mult of 8, `data.image_base64[]`→`data[].b64_json`); edits endpoint returns 501; unknown image model names get 501 `model_not_supported` |
+| `fallback.py` | Catch-all route: merged Anthropic/OpenAI-shaped JSON errors for every unserved path — 404 `route_not_found` (lists valid routes), 405 `method_not_allowed`, 501 `endpoint_not_supported` per recognized API family with an actionable reason |
 | `main.py` | Thin bootstrap: load config → create app → run uvicorn |
 | `service.py` | Authoritative systemd user-service install/start/stop/restart/reload/status and legacy PID migration |
 | `healthcheck.py` | Upstream connectivity probing (`POST /v1/messages`, max_tokens=1) for each referenced (provider, model) pair; called by `doctor` (`flexgate check` is a deprecated alias of doctor) |
@@ -106,7 +112,7 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 - **Model resolution & `available_models` fallback**: A route may omit `model`; `router.resolve()` then falls back to the provider's first `available_models` entry, so `model_override` handed to the proxy is always a concrete name. `config._parse_routes` rejects routes that omit `model` on a provider with no `available_models` — so adding a provider without models requires an explicit `model` on every route using it.
 - **Proxy rewrite contract** (`proxy.py`): the upstream request gets the provider's `x-api-key` plus a fixed header set, and the JSON `model` field is rewritten only when the route set an override. Streaming responses are forwarded as raw bytes (`aiter_bytes`), never parsed.
 - **Key fallback** (`proxy.py`): a provider's `api_keys` list holds one or more keys for the same upstream (entries are key strings or `{key, note}` mappings; `note` is a free-form label shown by `flexgate status` and in fallback logs). Multiple accounts on one upstream — e.g. several MiniMax subscriptions — belong in ONE provider, not separate ones. Each *route* has an active-key pointer (`active_key` in YAML, 1-based; `RouteConfig.key_index` 0-based, default first key): requests on that route start from the pointed key, and on a retryable failure (HTTP 401/402/403/429/500/502/503/529, connect error, or timeout) the next key is tried and the pointer advances with it (in memory only, wrapping around — it is not written back to the file); every key is tried at most once and a full circle of failures returns the last error. The pointer is set interactively via `flexgate config edit` → "api keys" (pick a route, with live per-key usage) or by editing the route's `active_key` directly. `resolve()` (`router.py`) returns the matched `RouteConfig` so the proxy can read/advance its pointer. Streaming requests can only fall back before the upstream returns 200. `_regular_proxy`/`_stream_proxy` return `(response, retryable)`; `handle_request` owns the loop and returns the last error when all keys fail. The legacy `api_key` + `fallback_keys` schema is still parsed (`config._parse_api_keys`); migration v3 → v4 rewrites it to `api_keys`. `ProviderConfig.api_key` remains as a first-key property (getter/setter) for the settings import code.
-- **Usage inspection** (`usage.py`): `flexgate status` maps `base_url` to a platform adapter (`_ADAPTERS`): MiniMax → `{origin}/v1/api/openplatform/coding_plan/remains` (only the "general" text-model quota entry is used; its counts are usually 0/0, so usage is read from the `*_remaining_percent` fields), Kimi Code → `{base}/v1/usages` (undocumented, same endpoint as the CLI's `/usage`; reports weekly quota, 5-hour window and parallel limit), z.ai/bigmodel → `{origin}/api/monitor/usage/quota/limit` (undocumented but used by z.ai's own plugin), USTC/LiteLLM → `{origin}/key/info`. Hosts in `_PROBE_ONLY_MARKERS` (e.g. xiaomimimo.com — no key-based usage API) and unknown platforms get the minimal chat probe: `POST /v1/messages` with input `"hi"`, `max_tokens=128`. A failed adapter call also degrades to the probe.
+- **Usage inspection** (`usage.py`): `flexgate status` maps `base_url` to a platform adapter (`_ADAPTERS`): MiniMax → `{origin}/v1/api/openplatform/coding_plan/remains` (only the "general" text-model quota entry is used; its counts are usually 0/0, so usage is read from the `*_remaining_percent` fields), Kimi Code → `{base}/v1/usages` (undocumented, same endpoint as the CLI's `/usage`; reports weekly quota, 5-hour window and parallel limit), z.ai/bigmodel → `{origin}/api/monitor/usage/quota/limit` (undocumented but used by z.ai's own plugin), USTC/LiteLLM → `{origin}/key/info`. Hosts in `_PROBE_ONLY_MARKERS` (e.g. xiaomimimo.com — no key-based usage API) and unknown platforms get the minimal chat probe: `POST /v1/messages` with input `"hi"`, `max_tokens=128`. A failed adapter call also degrades to the probe. Any key whose usage query errored — a hard failure (adapter AND probe), or an adapter error merely recovered by the probe — is recorded in `~/.flexgate/usage-cache.json` (sha256 fingerprint, never key material; entry keeps the `ok` flag and output lines) and skipped by later `status`/`usage` runs, shown as `cached (… ago)` / `cached failure (… ago)` with a hint; `flexgate usage --force` rechecks them and a clean success clears the entry. Placeholder keys are never cached.
 - **Multimodal degradation**: `MULTIMODAL_MODELS` (currently `{"MiniMax-M3", "glm-4.6v"}`) is the allowlist. Requests carrying image blocks aimed at any other model have images stripped and a `[flexgate]` text note injected into both the outgoing request and the returned response, so non-multimodal backends don't 4xx.
 - **Schedule-based overrides**: Optional time windows (e.g. 22:00-06:00) override default routes. Overnight wrap is supported.
 - **Service-first lifecycle**: `flexgate.service` is the sole persistent runtime. systemd owns restart, boot startup, logs, and process state.

{flexgate-0.6.0 → flexgate-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.6.0
+Version: 0.8.0
 Summary: Flexible local API gateway for Claude Code — route models to different providers
 Project-URL: Homepage, https://github.com/Agony5757/flexible-gateway
 Project-URL: Repository, https://github.com/Agony5757/flexible-gateway
@@ -89,6 +89,7 @@ systemd **用户服务**是 Linux 上唯一推荐的持久化运行方式，负
 ```bash
 flexgate service install             # 安装、启用并立即启动
 flexgate service install --no-start  # 仅安装并启用，不立即启动
+flexgate service install --no-claude-settings  # 跳过修改 ~/.claude/settings.json 的交互询问
 flexgate service start               # 启动；自动修复旧格式或失效的 unit
 flexgate service stop                # 停止
 flexgate service restart             # 重启
@@ -113,7 +114,7 @@ flexgate service uninstall           # 停止、禁用并删除 unit
 ```bash
 flexgate --version               # 打印版本号（service status / 裸 flexgate 也会显示）
 flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings、上游连通性
-flexgate doctor --offline        # 跳过 PyPI 检查
+flexgate doctor --offline        # 跳过全部网络检查（PyPI 新版检查 + 上游探测）
 flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
 flexgate update --check          # 只报告将要做什么，不改动
 flexgate update --config-only    # 只迁移配置，不升级包
@@ -170,6 +171,7 @@ flexgate status --no-usage       # 跳过用量查询，只看配置
 flexgate status --usage-timeout 30
 flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
 flexgate usage --usage-timeout 30
+flexgate usage --force           # 重查上次失败的 key（默认跳过，读缓存）
 ```
 
 `flexgate status` 展示当前配置中的所有 provider、每个 provider 的 key 及
@@ -190,6 +192,24 @@ fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/
 如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
 
+**查询失败缓存**：用量查询中报错的 key（彻底失败，或专用接口报错但 probe
+证明 key 仍可用，例如智谱的按量付费 key）会记入
+`~/.flexgate/usage-cache.json`（只存 key 指纹，不存明文），此后 `status` /
+`usage` 默认跳过这些 key 并显示缓存错误与提示（`cached failure`）；
+`flexgate usage --force` 强制重查并更新缓存，干净成功后自动恢复实时查询。
+
+### HTTP API（图像生成与结构化错误）
+
+除 `POST /v1/messages` 外，网关还提供 OpenAI 兼容的图像生成端点
+`POST /v1/images/generations`：自动发现配置中的 MiniMax provider，把请求
+翻译为 MiniMax `image-01` 文生图（模型名提示如 `gpt-image`/`dall-e` 均可，
+`size` 钳制到 512–2048 的 8 倍数，响应为 `data[].b64_json`）。
+`/v1/images/edits` 固定返回 501（上游仅支持文生图）。
+
+所有未支持的路径（如 `/v1/chat/completions`、`/v1/embeddings`、`count_tokens`）
+返回 Anthropic/OpenAI 双兼容的结构化 JSON 错误（404/405/501），而不是裸
+404。详见[HTTP API 文档](https://agony5757.github.io/flexible-gateway/api.html)。
+
 ### 前台调试
 
 `run` 是独立的顶层调试命令，不属于持久化服务模式：
@@ -244,16 +264,19 @@ flexgate config set haiku MiniMax-M3
 
 ```text
 Flexgate config  —  ~/.flexgate/config.yaml
-↑/↓ move · Enter edit tier · s save · q quit
+↑/↓ move · Enter edit · s save · q quit
 
 ▶ opus      ustc / deepseek-v4-pro
   sonnet    ustc / deepseek-v4-pro
   haiku     ustc / deepseek-v4-pro
+  fallback  ustc / deepseek-v4-pro
+  api keys  select the active key per route
 
 ○ no unsaved changes
 ```
 
-- 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- 方向键选中某个 tier（opus/sonnet/haiku）或 `fallback`（兜底路由 `.*`，未命中任何 tier 的请求走它），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- 选中 `api keys` 回车进入：先选一条**路由**，再选它的 **active key**；key 列表会实时查询每个 key 的用量/有效性（与 `flexgate status` 相同），并标注当前 active 的 key。
 - model 列表包含：`available_models` 中的各个模型、「使用 provider 默认（首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
 - 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），按 `q` 退出（有未保存改动时会询问 "Config changed — activate now?"：选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 `Esc`/`←` 返回上一级。
 - 需要交互式终端（TTY）；非交互场景请改用 `flexgate config set`。
@@ -286,6 +309,7 @@ API_TIMEOUT_MS、三个 `ANTHROPIC_DEFAULT_*_MODEL`），settings.json 中的
 | `~/.flexgate/config.yaml` | 主配置文件 |
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
+| `~/.flexgate/usage-cache.json` | 用量查询失败缓存（key 指纹 + 错误文本；`usage --force` 重查后更新） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
 | systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 
@@ -337,6 +361,7 @@ routes:                          # 从上到下匹配，首个命中生效
   - pattern: "^claude-sonnet"
     provider: minimax
     model: "MiniMax-M3"
+    active_key: 2               # 可选：该路由从 minimax 的第 2 个 key 开始用（1 起始，默认 1）
   - pattern: "^claude-haiku"
     provider: minimax
     model: "MiniMax-M3"
@@ -354,9 +379,10 @@ routes:                          # 从上到下匹配，首个命中生效
 | `providers.<name>.api_keys` | API key 列表（一个或多个，互为 fallback）；每项为 key 字符串或 `{key, note}`，`note` 是存在配置里的备注 |
 | `providers.<name>.available_models` | 该 provider 的可用模型列表，首个条目作为路由省略 `model` 时的回退模型 |
 | `claude_settings.*` | 写入 settings.json 的模型和超时配置 |
-| `routes[].pattern` | 正则匹配请求中的 model 字段 |
+| `routes[].pattern` | 正则匹配请求中的 model 字段（匹配前归一化裸别名 `sonnet`/`opus`/`haiku`/`default` 与旧编号名） |
 | `routes[].provider` | 路由到的 provider 名称 |
 | `routes[].model` | 可选，替换发给 provider 的模型名 |
+| `routes[].active_key` | 可选，1 起始的 provider api_keys 序号，该路由的请求从哪个 key 开始（默认 1，即第一个 key） |
 | `schedule[].name` | 定时规则名称 |
 | `schedule[].start/end` | 时间窗口（HH:MM 格式，支持跨夜如 22:00-06:00） |
 | `schedule[].routes` | 该时间窗口内生效的路由（格式同 `routes`） |
@@ -368,7 +394,13 @@ routes:                          # 从上到下匹配，首个命中生效
 `{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
 都会显示 note，方便分辨是哪个账号的 key）：
 
-- 请求先走第一个 key；失败时按列表顺序自动重试后续 key，直到某个 key
+- 每条路由有一个「当前 key」指针（路由上的 `active_key`，默认指向
+  provider 的第一个 key）：该路由的请求从指针指向的 key 开始；key 失败
+  时自动换用下一个 key（循环一圈），指针也随之自动前进——后续请求直接
+  从能用的 key 开始。**所有 key 轮换一圈都失败时，请求返回最后一次的
+  错误**。指针的运行时前进只存在于网关进程内存中，不写回配置文件；
+  可通过 `flexgate config edit` → "api keys" 交互切换。
+- 请求先走 active key；失败时按列表顺序自动重试后续 key，直到某个 key
   成功或返回不可重试的错误。
 - 触发切换的条件：HTTP **401 / 402 / 403 / 429 / 500 / 502 / 503 / 529**
   （key 失效、余额/额度耗尽、限流、平台过载）以及连接错误、超时。

{flexgate-0.6.0 → flexgate-0.8.0}/README.md

@@ -72,6 +72,7 @@ systemd **用户服务**是 Linux 上唯一推荐的持久化运行方式，负
 ```bash
 flexgate service install             # 安装、启用并立即启动
 flexgate service install --no-start  # 仅安装并启用，不立即启动
+flexgate service install --no-claude-settings  # 跳过修改 ~/.claude/settings.json 的交互询问
 flexgate service start               # 启动；自动修复旧格式或失效的 unit
 flexgate service stop                # 停止
 flexgate service restart             # 重启
@@ -96,7 +97,7 @@ flexgate service uninstall           # 停止、禁用并删除 unit
 ```bash
 flexgate --version               # 打印版本号（service status / 裸 flexgate 也会显示）
 flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings、上游连通性
-flexgate doctor --offline        # 跳过 PyPI 检查
+flexgate doctor --offline        # 跳过全部网络检查（PyPI 新版检查 + 上游探测）
 flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
 flexgate update --check          # 只报告将要做什么，不改动
 flexgate update --config-only    # 只迁移配置，不升级包
@@ -153,6 +154,7 @@ flexgate status --no-usage       # 跳过用量查询，只看配置
 flexgate status --usage-timeout 30
 flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
 flexgate usage --usage-timeout 30
+flexgate usage --force           # 重查上次失败的 key（默认跳过，读缓存）
 ```
 
 `flexgate status` 展示当前配置中的所有 provider、每个 provider 的 key 及
@@ -173,6 +175,24 @@ fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/
 如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
 
+**查询失败缓存**：用量查询中报错的 key（彻底失败，或专用接口报错但 probe
+证明 key 仍可用，例如智谱的按量付费 key）会记入
+`~/.flexgate/usage-cache.json`（只存 key 指纹，不存明文），此后 `status` /
+`usage` 默认跳过这些 key 并显示缓存错误与提示（`cached failure`）；
+`flexgate usage --force` 强制重查并更新缓存，干净成功后自动恢复实时查询。
+
+### HTTP API（图像生成与结构化错误）
+
+除 `POST /v1/messages` 外，网关还提供 OpenAI 兼容的图像生成端点
+`POST /v1/images/generations`：自动发现配置中的 MiniMax provider，把请求
+翻译为 MiniMax `image-01` 文生图（模型名提示如 `gpt-image`/`dall-e` 均可，
+`size` 钳制到 512–2048 的 8 倍数，响应为 `data[].b64_json`）。
+`/v1/images/edits` 固定返回 501（上游仅支持文生图）。
+
+所有未支持的路径（如 `/v1/chat/completions`、`/v1/embeddings`、`count_tokens`）
+返回 Anthropic/OpenAI 双兼容的结构化 JSON 错误（404/405/501），而不是裸
+404。详见[HTTP API 文档](https://agony5757.github.io/flexible-gateway/api.html)。
+
 ### 前台调试
 
 `run` 是独立的顶层调试命令，不属于持久化服务模式：
@@ -227,16 +247,19 @@ flexgate config set haiku MiniMax-M3
 
 ```text
 Flexgate config  —  ~/.flexgate/config.yaml
-↑/↓ move · Enter edit tier · s save · q quit
+↑/↓ move · Enter edit · s save · q quit
 
 ▶ opus      ustc / deepseek-v4-pro
   sonnet    ustc / deepseek-v4-pro
   haiku     ustc / deepseek-v4-pro
+  fallback  ustc / deepseek-v4-pro
+  api keys  select the active key per route
 
 ○ no unsaved changes
 ```
 
-- 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- 方向键选中某个 tier（opus/sonnet/haiku）或 `fallback`（兜底路由 `.*`，未命中任何 tier 的请求走它），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- 选中 `api keys` 回车进入：先选一条**路由**，再选它的 **active key**；key 列表会实时查询每个 key 的用量/有效性（与 `flexgate status` 相同），并标注当前 active 的 key。
 - model 列表包含：`available_models` 中的各个模型、「使用 provider 默认（首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
 - 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），按 `q` 退出（有未保存改动时会询问 "Config changed — activate now?"：选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 `Esc`/`←` 返回上一级。
 - 需要交互式终端（TTY）；非交互场景请改用 `flexgate config set`。
@@ -269,6 +292,7 @@ API_TIMEOUT_MS、三个 `ANTHROPIC_DEFAULT_*_MODEL`），settings.json 中的
 | `~/.flexgate/config.yaml` | 主配置文件 |
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
+| `~/.flexgate/usage-cache.json` | 用量查询失败缓存（key 指纹 + 错误文本；`usage --force` 重查后更新） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
 | systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 
@@ -320,6 +344,7 @@ routes:                          # 从上到下匹配，首个命中生效
   - pattern: "^claude-sonnet"
     provider: minimax
     model: "MiniMax-M3"
+    active_key: 2               # 可选：该路由从 minimax 的第 2 个 key 开始用（1 起始，默认 1）
   - pattern: "^claude-haiku"
     provider: minimax
     model: "MiniMax-M3"
@@ -337,9 +362,10 @@ routes:                          # 从上到下匹配，首个命中生效
 | `providers.<name>.api_keys` | API key 列表（一个或多个，互为 fallback）；每项为 key 字符串或 `{key, note}`，`note` 是存在配置里的备注 |
 | `providers.<name>.available_models` | 该 provider 的可用模型列表，首个条目作为路由省略 `model` 时的回退模型 |
 | `claude_settings.*` | 写入 settings.json 的模型和超时配置 |
-| `routes[].pattern` | 正则匹配请求中的 model 字段 |
+| `routes[].pattern` | 正则匹配请求中的 model 字段（匹配前归一化裸别名 `sonnet`/`opus`/`haiku`/`default` 与旧编号名） |
 | `routes[].provider` | 路由到的 provider 名称 |
 | `routes[].model` | 可选，替换发给 provider 的模型名 |
+| `routes[].active_key` | 可选，1 起始的 provider api_keys 序号，该路由的请求从哪个 key 开始（默认 1，即第一个 key） |
 | `schedule[].name` | 定时规则名称 |
 | `schedule[].start/end` | 时间窗口（HH:MM 格式，支持跨夜如 22:00-06:00） |
 | `schedule[].routes` | 该时间窗口内生效的路由（格式同 `routes`） |
@@ -351,7 +377,13 @@ routes:                          # 从上到下匹配，首个命中生效
 `{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
 都会显示 note，方便分辨是哪个账号的 key）：
 
-- 请求先走第一个 key；失败时按列表顺序自动重试后续 key，直到某个 key
+- 每条路由有一个「当前 key」指针（路由上的 `active_key`，默认指向
+  provider 的第一个 key）：该路由的请求从指针指向的 key 开始；key 失败
+  时自动换用下一个 key（循环一圈），指针也随之自动前进——后续请求直接
+  从能用的 key 开始。**所有 key 轮换一圈都失败时，请求返回最后一次的
+  错误**。指针的运行时前进只存在于网关进程内存中，不写回配置文件；
+  可通过 `flexgate config edit` → "api keys" 交互切换。
+- 请求先走 active key；失败时按列表顺序自动重试后续 key，直到某个 key
   成功或返回不可重试的错误。
 - 触发切换的条件：HTTP **401 / 402 / 403 / 429 / 500 / 502 / 503 / 529**
   （key 失效、余额/额度耗尽、限流、平台过载）以及连接错误、超时。

flexgate-0.8.0/docs/api.md

@@ -0,0 +1,66 @@
+# HTTP API
+
+Flexgate 在本地监听（默认 `127.0.0.1:8765`）提供以下端点：
+
+| 端点 | 说明 |
+|------|------|
+| `POST /v1/messages` | Anthropic Messages API 代理（核心端点） |
+| `POST /v1/images/generations` | OpenAI 兼容图像生成（转 MiniMax `image-01`） |
+| `POST /v1/images/edits` | 固定返回 501（上游仅支持文生图） |
+| 其他路径 | 结构化 JSON 错误（404 / 405 / 501，见下文） |
+
+## POST /v1/messages
+
+标准的 Anthropic Messages 格式代理。请求体中的 `model` 字段用于路由：
+
+- **模型别名归一化**：匹配路由前，裸别名（`sonnet` / `opus` / `haiku` /
+  `default`，大小写不敏感，可带 `[plan]` 后缀）映射为对应的
+  `claude-<tier>` 前缀（`default` → sonnet）；旧编号名
+  （如 `claude-3-7-sonnet-latest`）归约为 tier 前缀；其余名称原样匹配。
+- 命中路由后，仅当路由显式配置了 `model` 时才改写上游请求的 model 字段；
+  认证头替换为该 provider 当前 active key 的 `x-api-key`。
+- 流式（SSE）响应按原始字节透传，不做解析；非流式 JSON 原样转发。
+- key 级 fallback：可重试错误按 `api_keys` 顺序切换（详见
+  [配置文件](configuration.md#key-fallback)）。
+- **多模态降级**：请求携带图片块且目标模型不在多模态允许列表
+  （`MULTIMODAL_MODELS`，当前为 `MiniMax-M3`、`glm-4.6v`）中时，图片会被
+  剥离，并在请求与响应中注入 `[flexgate]` 文本说明，避免非多模态上游报 4xx。
+
+## POST /v1/images/generations
+
+OpenAI Images API 兼容端点，让 OpenAI 风格的客户端无需任何额外配置即可
+通过网关生成图片：
+
+- **上游自动发现**：使用配置中 `base_url` 指向 MiniMax
+  （`api.minimaxi.com` / `api.minimax.io`）的 provider 及其 key，无需单独
+  配置图像 provider。
+- **模型名映射**：请求中的 `model` 含已知图像模型提示（`gpt-image`、
+  `dall-e`、`image-01`、`seedream`、`flux`、`sdxl`、`stable-diffusion`、
+  `minimax` 等）即接受并映射为 MiniMax 的 `image-01`；无法识别的模型名
+  返回 501 `model_not_supported`。
+- **尺寸**：`size: "WxH"` 映射为 width/height，各边钳制到 512–2048 并取
+  8 的倍数；无法解析的 size 忽略（用上游默认值）。
+- **prompt** 超过 1500 字符会被截断。
+- **响应**：MiniMax 返回的 `data.image_base64[]`（JPEG）原样转发为 OpenAI
+  风格的 `data[].b64_json`，不引入转码依赖。
+
+## POST /v1/images/edits
+
+固定返回 501：MiniMax `image-01` 仅支持文生图，没有通用的图像编辑 /
+inpainting 能力。
+
+## 未支持端点的结构化错误
+
+所有未匹配的请求都不会得到裸 404，而是返回 Anthropic / OpenAI 双兼容
+的 JSON 错误体，客户端可以据此判断"端口错了"还是"网关不支持该能力"：
+
+```json
+{"type": "error", "error": {"type": "...", "message": "...", "code": "..."}}
+```
+
+| 状态码 | code | 触发条件 |
+|--------|------|----------|
+| 404 | `route_not_found` | 完全未知的路径；message 中列出全部有效路由 |
+| 405 | `method_not_allowed` | 路径有效但 HTTP 方法不对 |
+| 501 | `endpoint_not_supported` | 识别出的 API 家族但网关不服务（`/v1/chat/completions`、`/v1/responses`、`/v1/messages/count_tokens`、`/v1/embeddings` 等），message 给出可操作的建议 |
+| 501 | `capability_not_supported` / `model_not_supported` | 有效路由上不支持的操作或模型名（由所属模块返回） |

{flexgate-0.6.0 → flexgate-0.8.0}/docs/cli.md

@@ -19,6 +19,7 @@ systemd **用户服务**是 Linux 上唯一推荐的持久化运行方式，负
 ```bash
 flexgate service install             # 安装、启用并立即启动
 flexgate service install --no-start  # 仅安装并启用，不立即启动
+flexgate service install --no-claude-settings  # 跳过修改 ~/.claude/settings.json 的交互询问
 flexgate service start               # 启动；自动修复旧格式或失效的 unit
 flexgate service stop                # 停止
 flexgate service restart             # 重启
@@ -55,9 +56,13 @@ flexgate status --no-usage       # 跳过用量查询，只看配置
 flexgate status --usage-timeout 30
 flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
 flexgate usage --usage-timeout 30
+flexgate usage --force           # 重查上次失败的 key（默认跳过，读缓存）
 ```
 
-各平台的用量查询适配器详见[用量查询](usage.md)。
+查询失败的 key 会被缓存并在此后的 `status` / `usage` 中默认跳过
+（显示为 `cached failure` 并附带提示），`--force` 强制重新查询；
+详见[用量查询](usage.md)。各平台的用量查询适配器同样见
+[用量查询](usage.md)。
 
 ## 查看日志（log）
 

{flexgate-0.6.0 → flexgate-0.8.0}/docs/conf.py

@@ -29,6 +29,9 @@ myst_enable_extensions = [
     "linkify",
 ]
 
+# Allow cross-document links to implicit heading anchors (e.g. configuration.md#key-fallback)
+myst_heading_anchors = 3
+
 source_suffix = {".md": "markdown"}
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

{flexgate-0.6.0 → flexgate-0.8.0}/docs/configuration.md

@@ -7,6 +7,7 @@
 | `~/.flexgate/config.yaml` | 主配置文件 |
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
+| `~/.flexgate/usage-cache.json` | 用量查询失败缓存（key 指纹 + 错误文本；`usage --force` 重查后更新，见[用量查询](usage.md)） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
 | systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 

{flexgate-0.6.0 → flexgate-0.8.0}/docs/development.md

@@ -9,8 +9,11 @@
 | `flexgate/config.py` | dataclass 配置模型（`GatewayConfig`、`ProviderConfig`、`RouteConfig` 等），YAML 加载/保存，`is_placeholder_key` |
 | `flexgate/router.py` | `resolve(config, model)` — 先定时路由后默认路由，首个正则命中生效；匹配前归一化模型别名（`sonnet`/`claude-3-7-sonnet-latest` → `^claude-<tier>`） |
 | `flexgate/proxy.py` | `handle_request()` — httpx 异步代理，per-key fallback 重试，SSE 流式 + JSON 透传；记录每个请求由哪把 key 服务 |
-| `flexgate/usage.py` | `flexgate status` / `flexgate usage` 的用量查询 — 各平台适配器 + minimal chat probe 兜底 |
-| `flexgate/server.py` | Starlette 应用，`POST /v1/messages` 端点，SIGUSR1 热重载 |
+| `flexgate/usage.py` | `flexgate status` / `flexgate usage` 的用量查询 — 各平台适配器 + minimal chat probe 兜底 + 查询失败缓存（`usage --force` 强制重查） |
+| `flexgate/server.py` | Starlette 应用，`POST /v1/messages` + `POST /v1/images/{generations,edits}` 端点，SIGUSR1 热重载 |
+| `flexgate/images.py` | OpenAI Images API → MiniMax `/v1/image_generation` 翻译（模型名映射、size 钳制、`b64_json` 透传；edits 返回 501） |
+| `flexgate/fallback.py` | 兜底路由：所有未服务路径返回 Anthropic/OpenAI 双兼容的结构化 JSON 错误（404 `route_not_found` / 405 / 501 `endpoint_not_supported`） |
+| `flexgate/main.py` | 启动引导：加载配置 → 创建 app → 跑 uvicorn |
 | `flexgate/service.py` | systemd 用户服务的安装/启停/重载/状态（持久化运行的唯一入口）；journal 日志查看 |
 | `flexgate/healthcheck.py` | 上游连通性探测（`POST /v1/messages`，`max_tokens=1`），由 `doctor` 调用（`flexgate check` 为弃用别名） |
 | `flexgate/settings.py` | config.yaml ↔ `~/.claude/settings.json` 双向桥接（apply 非破坏性：只改托管 env 键） |

{flexgate-0.6.0 → flexgate-0.8.0}/docs/index.md

@@ -23,12 +23,17 @@ Claude Code → localhost:8765 → opus  → z.ai (glm-5.1)
 
 ## 特性一览
 
-- **按 model 路由**：正则匹配请求中的 model 字段，首个命中生效，支持兜底路由
+- **按 model 路由**：正则匹配请求中的 model 字段，首个命中生效，支持兜底路由；
+  裸别名（`sonnet`/`opus`/`haiku`）与旧编号名自动归一化
 - **定时路由**：按时间窗口自动切换路由（支持跨夜，如 22:00-06:00）
 - **多 key fallback**：同一上游配置多个 key，遇到 401/402/403/429/5xx/529
   或连接错误时自动切换到下一个 key
+- **多模态降级**：非多模态模型的请求自动剥离图片块并注入说明，避免上游 4xx
+- **OpenAI 兼容图像生成**：`POST /v1/images/generations` 自动转 MiniMax
+  `image-01`，详见 [HTTP API](api.md)
 - **用量查询**：`flexgate status` / `flexgate usage` 按平台适配器查询每个
-  key 的实时额度（MiniMax、Kimi Code、z.ai、LiteLLM 等）
+  key 的实时额度（MiniMax、Kimi Code、z.ai、LiteLLM 等）；查询失败的 key
+  自动缓存跳过，`usage --force` 强制重查
 - **Claude Code settings 管理**：import / apply 双向同步
 - **配置同步**：`flexgate sync` 通过 confsync 服务器加密同步配置
 - **自愈升级**：`flexgate doctor` 体检、`flexgate update` 一键升级并迁移配置
@@ -40,6 +45,7 @@ Claude Code → localhost:8765 → opus  → z.ai (glm-5.1)
 
 quickstart
 configuration
+api
 cli
 usage
 development

{flexgate-0.6.0 → flexgate-0.8.0}/docs/usage.md

@@ -8,7 +8,7 @@
 |------|----------|------|
 | MiniMax（api.minimaxi.com / api.minimax.io） | `GET /v1/api/openplatform/coding_plan/remains`（Bearer 认证，复用 provider key） | 官方 token plan 接口，返回 5 小时窗口和周窗口的**剩余**次数（注意响应里 `*_usage_count` 字段实际是剩余量） |
 | Kimi Code（api.kimi.com） | `GET {base}/v1/usages`（Bearer 认证，复用 provider key） | 未公开文档、与 Kimi Code CLI `/usage` 相同的接口，返回周配额、5 小时滚动窗口剩余量和并发上限 |
-| z.ai / 智谱（api.z.ai / open.bigmodel.cn） | `GET /api/monitor/usage/quota/limit`（Authorization 直接带 key） | 未公开文档、但 z.ai 官方 coding 插件在用的接口，返回各窗口已用百分比与重置时间 |
+| z.ai / 智谱（api.z.ai / open.bigmodel.cn） | `GET /api/monitor/usage/quota/limit`（Authorization 直接带 key） | 未公开文档、但 z.ai 官方 coding 插件在用的接口，返回各窗口已用百分比与重置时间。**仅对 GLM Coding Plan 订阅有效**：普通按量付费 key 会返回"当前用户不存在coding plan"并退化为 probe（余额只能在网页控制台查看） |
 | USTC（api.llm.ustc.edu.cn，LiteLLM） | `GET /key/info`（Bearer 认证） | LiteLLM proxy 自带的 key 信息接口，返回 spend / max_budget / 限速等 |
 | 小米 MiMo（token-plan-cn.xiaomimimo.com） | **无 key 可用的官方接口**（控制台内部接口需要浏览器 cookie，不采用） | 退化为 minimal probe |
 | 其他/未知平台 | minimal chat probe | 发一条输入 `"hi"`、`max_tokens=128` 的最小 `/v1/messages` 请求，验证 key 是否还能正常服务（会消耗极少量额度） |
@@ -20,15 +20,42 @@
 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
 :::
 
+## 查询失败缓存与 `--force`
+
+用量查询中**报错的 key**（彻底失败，或专用接口报错但 probe 证明 key 仍
+可用）会记录到 `~/.flexgate/usage-cache.json`（只存 key 的 sha256 指纹和
+结果文本，不存 key 明文），此后 `flexgate status` / `flexgate usage`
+默认**跳过**这些 key——不再发起任何网络请求，直接显示缓存的错误和一行
+提示：
+
+```text
+Usage (timeout 15s per key)
+  2 key(s) skipped — last check failed (recheck with: flexgate usage --force)
+  zhipu
+    ✓ key #1 (0b4d***MZTV) [fangyuan]  cached (15s ago)
+        z.ai quota API (unofficial) failed (platform error: 当前用户不存在coding plan); probe: key can serve glm-5.3
+        recheck with: flexgate usage --force
+  ustc
+    ✗ key #1 (sk-G***jJYg)  cached failure (8s ago)
+        LiteLLM /key/info failed (ConnectError: ); probe: ConnectError:
+        recheck with: flexgate usage --force
+```
+
+- 跳过的 key 按**上次结果**显示状态：key 仍可用的显示暗色 ✓ +
+  `cached (… ago)`，彻底失败的显示暗色 ✗ + `cached failure (… ago)`。
+- `flexgate usage --force` 忽略缓存、重新查询所有 key 并更新缓存；
+  重查干净成功（无任何报错）的 key 会自动清除缓存条目，恢复默认实时查询。
+- 占位符 key（未填写的默认值）不会进入缓存。
+
 ## 输出示例
 
 ```text
 Usage (timeout 15s per key):
   minimax:
-    ✓ key #1 (sk-c***abcd) [main]  [MiniMax coding_plan API]
+    ✓ key #1 (sk-c***abcd) [main]  MiniMax coding_plan API
         MiniMax-M3: 5h window remaining 450/450 (reset 08-24 00:00); weekly remaining 900/900 (reset 08-24 00:00)
   kimi:
-    ✓ key #1 (sk-k***66N6) [ywj]  [Kimi Code usages API (unofficial)]
+    ✓ key #1 (sk-k***66N6) [ywj]  Kimi Code usages API (unofficial)
         plan: advanced
         weekly remaining 63/100 (reset 08-28 22:17)
         5h window remaining 74/100 (reset 08-23 14:17)

{flexgate-0.6.0 → flexgate-0.8.0}/flexgate/__init__.py

@@ -1,3 +1,3 @@
 """Flexgate — Flexible API Gateway for Claude Code."""
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"

{flexgate-0.6.0 → flexgate-0.8.0}/flexgate/cli.py

@@ -137,21 +137,30 @@ def cmd_usage(args: argparse.Namespace) -> None:
         err(f"Config not found: {config_path} — run 'flexgate config init' to create one.", 1)
 
     config = load_config(config_path)
-    _print_usage(config, getattr(args, "usage_timeout", 15.0))
+    _print_usage(config, getattr(args, "usage_timeout", 15.0), force=getattr(args, "force", False))
 
 
-def _print_usage(config, timeout: float) -> None:
-    from flexgate.usage import run_usage_check
+def _print_usage(config, timeout: float, force: bool = False) -> None:
+    from flexgate.usage import FORCE_HINT, run_usage_check
 
     print("\n" + _bold("Usage") + _dim(f" (timeout {timeout:g}s per key)"))
-    usage = run_usage_check(config, timeout=timeout)
+    usage = run_usage_check(config, timeout=timeout, force=force)
+    skipped = sum(1 for results in usage.values() for r in results if r.skipped)
+    if skipped:
+        print(_dim(f"  {skipped} key(s) skipped — last check failed ({FORCE_HINT})"))
     for name, results in usage.items():
         print(f"  {_bold(_cyan(name))}")
         for r in results:
-            marker = _green("✓") if r.ok else _red("✗")
+            if r.skipped:
+                marker = _dim("✓") if r.ok else _dim("✗")
+            else:
+                marker = _green("✓") if r.ok else _red("✗")
             print(f"    {marker} {r.key_label}  {_dim(r.method)}")
             for line in r.lines:
-                print(f"        {line if r.ok else _red(line)}")
+                if line == FORCE_HINT:
+                    print(f"        {_dim(line)}")
+                else:
+                    print(f"        {line if r.ok else _red(line)}")
 
 
 # ── settings subcommands ────────────────────────────────────────────
@@ -213,6 +222,10 @@ def _set_route(
     """Update the default route for a pattern, or insert one before the catch-all."""
     for route in config.routes:
         if route.pattern.pattern == pattern:
+            if route.provider_name != provider_name:
+                # Stale active-key pointer from the old provider may point past
+                # the new provider's key list and make the config unloadable.
+                route.key_index = 0
             route.provider_name = provider_name
             route.model = model_override
             return
@@ -1066,6 +1079,10 @@ def main() -> None:
         "--usage-timeout", type=float, default=15.0,
         help="Per-key usage query timeout in seconds (default: 15.0)"
     )
+    usage_p.add_argument(
+        "--force", action="store_true",
+        help="Recheck keys whose last usage check failed (skipped by default)"
+    )
 
     # flexgate log ...
     log_p = sub.add_parser("log", help="Show gateway logs from the systemd journal")

flexgate-0.8.0/flexgate/fallback.py

@@ -0,0 +1,99 @@
+"""Structured errors for every route and capability flexgate does not serve.
+
+A bare Starlette 404 tells an API client nothing: it cannot tell "wrong port"
+apart from "right gateway, unsupported endpoint". Every unmatched request
+instead gets a JSON error explaining what was asked for and what flexgate
+does support, so client-side fallback logic (and humans reading logs) can
+react without guessing.
+
+Error payload shape is a merge of the Anthropic and OpenAI conventions so
+both client families parse it:
+
+    {"type": "error", "error": {"type": ..., "message": ..., "code": ...}}
+
+Status code policy:
+- 404 route_not_found        unknown path entirely; message lists valid routes
+- 405 method_not_allowed     known path, wrong HTTP method
+- 501 endpoint_not_supported recognized API family flexgate does not serve
+- 501 capability_not_supported / model_not_supported for valid routes with
+  unsupported operations or model names (raised by the owning module)
+"""
+
+from __future__ import annotations
+
+import re
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+SUPPORTED_ROUTES = ("POST /v1/messages", "POST /v1/images/generations")
+
+
+def error_json(message: str, status: int, error_type: str, code: str) -> JSONResponse:
+    return JSONResponse(
+        {"type": "error", "error": {"type": error_type, "message": message, "code": code}},
+        status_code=status,
+    )
+
+
+# Recognized-but-unsupported API families: (path regex, human reason).
+# Order matters; first match wins. Keep reasons actionable: say what the
+# caller probably wanted and where that capability lives, if anywhere.
+_UNSUPPORTED_FAMILIES: list[tuple[re.Pattern[str], str]] = [
+    (
+        re.compile(r"^/v1/messages/count_tokens$"),
+        "Token counting is not proxied; flexgate only forwards POST /v1/messages. "
+        "Count tokens client-side (e.g. with a tokenizer) instead.",
+    ),
+    (
+        re.compile(r"^/v1/(chat/completions|responses)(/.*)?$"),
+        "OpenAI chat is not served: flexgate proxies Anthropic-style POST /v1/messages only. "
+        "Point an Anthropic-compatible client at this gateway, or call the upstream provider directly.",
+    ),
+    (
+        re.compile(r"^/v1/images/edits$"),
+        # Owning module (images.py) normally answers this first; kept as a safety net.
+        "Image editing/inpainting is not available: the MiniMax image-01 backend is text-to-image only. "
+        "Use POST /v1/images/generations, or edit the image with another tool and upload the result.",
+    ),
+    (
+        re.compile(r"^/v1/embeddings"),
+        "Embeddings are not proxied: no configured provider exposes an embedding endpoint. "
+        "Call an embedding-capable provider directly.",
+    ),
+    (
+        re.compile(r"^/v1/(audio|videos?)(/.*)?$"),
+        "Audio/video endpoints are not proxied by flexgate. "
+        "Call the upstream provider's native API directly.",
+    ),
+    (
+        re.compile(r"^/v1/(models|files|fine_tuning|batches|moderations|vector_stores|assistants|threads|uploads)(/.*)?$"),
+        "This OpenAI platform endpoint is not proxied: flexgate is a routing gateway, not an API platform. "
+        "It only serves POST /v1/messages and POST /v1/images/generations.",
+    ),
+]
+
+
+async def fallback(request: Request) -> JSONResponse:
+    """Catch-all handler for every path/method flexgate does not serve."""
+    path = request.url.path.rstrip("/") or "/"
+
+    if path in ("/v1/messages", "/v1/images/generations"):
+        return error_json(
+            f"{request.method} is not allowed on {path}; use POST.",
+            405,
+            "invalid_request_error",
+            "method_not_allowed",
+        )
+
+    for pattern, reason in _UNSUPPORTED_FAMILIES:
+        if pattern.match(path):
+            return error_json(reason, 501, "not_implemented", "endpoint_not_supported")
+
+    return error_json(
+        f"Unknown route: {request.method} {path}. "
+        f"flexgate serves exactly: {', '.join(SUPPORTED_ROUTES)}.",
+        404,
+        "not_found_error",
+        "route_not_found",
+    )

flexgate-0.8.0/flexgate/images.py

@@ -0,0 +1,192 @@
+"""OpenAI-compatible Images API endpoint, backed by MiniMax image generation.
+
+Exposes `POST /v1/images/generations` so OpenAI-style clients (e.g. editppt's
+openai-compatible-api image backend) can generate images through the gateway
+without any per-provider configuration: the upstream is derived from whichever
+configured provider points at MiniMax (`api.minimaxi.com` / `api.minimax.io`).
+
+Translation notes:
+- MiniMax only has text-to-image (`POST /v1/image_generation`, model
+  `image-01`). `size` ("WxH") is mapped to width/height clamped to 512-2048
+  and rounded to multiples of 8; unrecognized sizes are omitted.
+- MiniMax replies with `data.image_base64[]` (JPEG bytes); it is forwarded
+  verbatim as OpenAI `data[].b64_json` — downstream tools sniff the real
+  content type, so no transcoding dependency is introduced here.
+- `/v1/images/edits` is answered 501: MiniMax has no general image-editing or
+  inpainting capability (its subject_reference is character-only).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from urllib.parse import urlsplit
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from flexgate.config import GatewayConfig, ProviderConfig
+from flexgate.fallback import error_json
+
+logger = logging.getLogger("flexgate.images")
+
+MINIMAX_MODEL = "image-01"
+MINIMAX_MIN_EDGE = 512
+MINIMAX_MAX_EDGE = 2048
+MINIMAX_MAX_PROMPT_CHARS = 1500
+
+# Requested model names containing any of these hints are accepted and mapped
+# to MiniMax image-01 (the only image backend behind this gateway).
+_IMAGE_MODEL_HINTS = (
+    "gpt-image",
+    "dall-e",
+    "image-01",
+    "seedream",
+    "flux",
+    "sdxl",
+    "stable-diffusion",
+    "minimax",
+)
+
+
+def _error_json(message: str, status: int, code: str = "minimax_error") -> JSONResponse:
+    error_type = {
+        400: "invalid_request_error",
+        501: "not_implemented",
+        503: "not_implemented",
+    }.get(status, "api_error")
+    return error_json(message, status, error_type, code)
+
+
+def _find_minimax_provider(config: GatewayConfig) -> ProviderConfig | None:
+    candidates = [p for p in config.providers.values() if "minimax" in p.base_url]
+    for provider in candidates:
+        if provider.name == "minimax":
+            return provider
+    return candidates[0] if candidates else None
+
+
+def _image_api_root(base_url: str) -> str:
+    parts = urlsplit(base_url)
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def _clamp_edge(value: int) -> int:
+    return max(MINIMAX_MIN_EDGE, min(MINIMAX_MAX_EDGE, value))
+
+
+def _round8(value: float) -> int:
+    return max(8, int(round(value / 8)) * 8)
+
+
+def _map_size(size: object) -> dict[str, int]:
+    if not isinstance(size, str):
+        return {}
+    match = re.fullmatch(r"(\d+)x(\d+)", size)
+    if not match:
+        return {}
+    w, h = int(match.group(1)), int(match.group(2))
+    if w <= 0 or h <= 0:
+        return {}
+    scale = min(1.0, MINIMAX_MAX_EDGE / max(w, h))
+    w, h = w * scale, h * scale
+    if min(w, h) < MINIMAX_MIN_EDGE:
+        boost = MINIMAX_MIN_EDGE / min(w, h)
+        w, h = w * boost, h * boost
+        if max(w, h) > MINIMAX_MAX_EDGE:
+            shrink = MINIMAX_MAX_EDGE / max(w, h)
+            w, h = w * shrink, h * shrink
+    return {"width": _clamp_edge(_round8(w)), "height": _clamp_edge(_round8(h))}
+
+
+async def images_generate(request: Request) -> JSONResponse:
+    t0 = time.monotonic()
+    config: GatewayConfig = request.app.state.config
+    client: httpx.AsyncClient = request.app.state.client
+
+    try:
+        body = json.loads(await request.body())
+    except json.JSONDecodeError:
+        return _error_json("Invalid JSON in request body", 400, "bad_request")
+
+    provider = _find_minimax_provider(config)
+    if provider is None:
+        return _error_json(
+            "No MiniMax provider configured (need a provider whose base_url points at MiniMax)",
+            503,
+            "provider_not_found",
+        )
+
+    prompt = body.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip():
+        return _error_json("Missing required field: prompt", 400, "bad_request")
+
+    requested_model = str(body.get("model") or "")
+    if requested_model and not any(h in requested_model.lower() for h in _IMAGE_MODEL_HINTS):
+        return _error_json(
+            f"Model '{requested_model}' is not a supported image model. flexgate maps image "
+            f"generation to MiniMax {MINIMAX_MODEL} (text-to-image only); request a gpt-image-* "
+            f"alias or '{MINIMAX_MODEL}'.",
+            501,
+            "model_not_supported",
+        )
+    logger.info(
+        "images/generations model=%s -> %s via %s",
+        requested_model or "(default)", MINIMAX_MODEL, provider.name,
+    )
+
+    n = body.get("n", 1)
+    payload: dict = {
+        "model": MINIMAX_MODEL,
+        "prompt": prompt[:MINIMAX_MAX_PROMPT_CHARS],
+        "response_format": "base64",
+        "n": max(1, min(9, int(n))) if isinstance(n, (int, float)) else 1,
+    }
+    payload.update(_map_size(body.get("size")))
+
+    url = f"{_image_api_root(provider.base_url)}/v1/image_generation"
+    headers = {
+        "Authorization": f"Bearer {provider.api_key}",
+        "Content-Type": "application/json",
+    }
+
+    try:
+        resp = await client.post(url, headers=headers, json=payload)
+    except httpx.ConnectError as exc:
+        logger.error("Provider %s unreachable: %s", provider.name, exc)
+        return _error_json(f"Provider unreachable: {provider.name}", 502)
+
+    try:
+        data = resp.json()
+    except Exception:
+        return _error_json(resp.text[:500], 502)
+
+    base_resp = data.get("base_resp") or {}
+    status_code = base_resp.get("status_code", 0)
+    if resp.status_code != 200 or status_code != 0:
+        message = base_resp.get("status_msg") or f"HTTP {resp.status_code}"
+        logger.error("MiniMax image generation failed: %s", message)
+        return _error_json(f"MiniMax upstream: {message}", 502)
+
+    images = (data.get("data") or {}).get("image_base64") or []
+    if not images:
+        return _error_json("MiniMax returned no image_base64 payload", 502)
+
+    elapsed_ms = int((time.monotonic() - t0) * 1000)
+    logger.info("images/generations <- %s | %d image(s) | %dms", provider.name, len(images), elapsed_ms)
+    return JSONResponse({
+        "created": int(time.time()),
+        "data": [{"b64_json": img, "revised_prompt": None} for img in images],
+    })
+
+
+async def images_edits(request: Request) -> JSONResponse:
+    return _error_json(
+        "MiniMax image-01 does not support image editing/inpainting; "
+        "only /v1/images/generations (text-to-image) is available through this gateway.",
+        501,
+        "edits_not_supported",
+    )

{flexgate-0.6.0 → flexgate-0.8.0}/flexgate/server.py

@@ -13,6 +13,8 @@ from starlette.responses import JSONResponse
 from starlette.routing import Route
 
 from flexgate.config import GatewayConfig, load_config
+from flexgate.fallback import fallback
+from flexgate.images import images_edits, images_generate
 from flexgate.proxy import handle_request
 from flexgate.router import NoRouteMatchError, resolve
 
@@ -65,7 +67,17 @@ def create_app(config: GatewayConfig, config_path: str | None = None) -> Starlet
         timeout=httpx.Timeout(connect=10, read=3600, write=10, pool=10),
     )
 
-    routes = [Route("/v1/messages", messages, methods=["POST"])]
+    routes = [
+        Route("/v1/messages", messages, methods=["POST"]),
+        Route("/v1/images/generations", images_generate, methods=["POST"]),
+        Route("/v1/images/edits", images_edits, methods=["POST"]),
+        # Catch-all last: structured, reasoned errors for anything unsupported.
+        Route(
+            "/{path:path}",
+            fallback,
+            methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+        ),
+    ]
 
     async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
         app.state.config = config

{flexgate-0.6.0 → flexgate-0.8.0}/flexgate/usage.py

@@ -23,7 +23,10 @@ known adapter and queries it with the provider's own API key:
 from __future__ import annotations
 
 import asyncio
+import hashlib
+import json
 import logging
+import os
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -31,7 +34,13 @@ from urllib.parse import urlparse
 
 import httpx
 
-from flexgate.config import ApiKey, GatewayConfig, ProviderConfig, is_placeholder_key
+from flexgate.config import (
+    FLEXGATE_HOME,
+    ApiKey,
+    GatewayConfig,
+    ProviderConfig,
+    is_placeholder_key,
+)
 
 logger = logging.getLogger("flexgate.usage")
 
@@ -39,6 +48,11 @@ logger = logging.getLogger("flexgate.usage")
 _PROBE_INPUT = "hi"
 _PROBE_MAX_TOKENS = 128
 
+# Keys whose usage check hard-failed are cached here and skipped by default
+# until 'flexgate usage --force' rechecks them.
+USAGE_CACHE_FILE = os.path.join(FLEXGATE_HOME, "usage-cache.json")
+FORCE_HINT = "recheck with: flexgate usage --force"
+
 
 @dataclass
 class UsageResult:
@@ -47,6 +61,8 @@ class UsageResult:
     method: str  # how the information was obtained
     ok: bool
     lines: list[str] = field(default_factory=list)
+    skipped: bool = False  # served from the failure cache, not queried now
+    adapter_error: str | None = None  # adapter failed but the probe recovered
 
 
 def _mask_key(key: str) -> str:
@@ -55,6 +71,49 @@ def _mask_key(key: str) -> str:
     return key[:4] + "***" + key[-4:]
 
 
+# ── failure cache ────────────────────────────────────────────────────
+
+
+def _fingerprint(key: str) -> str:
+    """Stable identity for a key — the cache never stores key material."""
+    return hashlib.sha256(key.encode()).hexdigest()[:16]
+
+
+def _load_fail_cache() -> dict[str, dict]:
+    try:
+        with open(USAGE_CACHE_FILE) as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    entries = data.get("entries") if isinstance(data, dict) else None
+    return dict(entries) if isinstance(entries, dict) else {}
+
+
+def _save_fail_cache(entries: dict[str, dict]) -> None:
+    tmp = USAGE_CACHE_FILE + ".tmp"
+    try:
+        with open(tmp, "w") as f:
+            json.dump({"entries": entries}, f, ensure_ascii=False, indent=2)
+        os.replace(tmp, USAGE_CACHE_FILE)
+    except OSError:
+        logger.debug("could not write usage cache", exc_info=True)
+
+
+def _fmt_age(iso: str) -> str:
+    try:
+        then = datetime.fromisoformat(iso)
+    except (ValueError, TypeError):
+        return "?"
+    secs = max(0, (datetime.now() - then).total_seconds())
+    if secs < 60:
+        return f"{secs:.0f}s"
+    if secs < 3600:
+        return f"{secs / 60:.0f}m"
+    if secs < 86400:
+        return f"{secs / 3600:.0f}h"
+    return f"{secs / 86400:.0f}d"
+
+
 def _origin(base_url: str) -> str:
     parts = urlparse(base_url)
     return f"{parts.scheme}://{parts.netloc}"
@@ -342,7 +401,10 @@ async def check_key_usage(
         probe_lines, probe_err = await _probe_chat(client, provider, key, timeout)
         note = f"{method} failed ({err}); probe: "
         if probe_err is None:
-            return UsageResult(provider.name, label, method, True, [note + probe_lines[0]])
+            return UsageResult(
+                provider.name, label, method, True, [note + probe_lines[0]],
+                adapter_error=err,
+            )
         return UsageResult(provider.name, label, method, False, [note + probe_err])
 
     lines, err = await _probe_chat(client, provider, key, timeout)
@@ -352,24 +414,82 @@ async def check_key_usage(
     return UsageResult(provider.name, label, method, False, [err])
 
 
+async def _check_key_cached(
+    client: httpx.AsyncClient,
+    provider: ProviderConfig,
+    entry: ApiKey,
+    index: int,
+    timeout: float,
+    view: dict[str, dict],
+    cache: dict[str, dict],
+) -> tuple[UsageResult, bool]:
+    """check_key_usage plus failure-cache bookkeeping.
+
+    `view` holds the failed checks to skip on this run (empty when forced);
+    `cache` is the live copy that gets written back. Any result carrying an
+    error (hard failure, or adapter error recovered by the probe) is cached
+    and skipped next time. Returns (result, cache_changed).
+    """
+    key = entry.key
+    fp = _fingerprint(key)
+    hit = view.get(fp)
+    if hit is not None:
+        label = f"key #{index + 1} ({_mask_key(key)})"
+        if entry.note:
+            label += f" [{entry.note}]"
+        ok = bool(hit.get("ok"))
+        lines = list(hit.get("lines") or [hit.get("error") or "unknown error"])
+        age = _fmt_age(hit.get("failed_at", ""))
+        method = f"cached ({age} ago)" if ok else f"cached failure ({age} ago)"
+        return UsageResult(provider.name, label, method, ok, lines + [FORCE_HINT], skipped=True), False
+    result = await check_key_usage(client, provider, entry, index, timeout)
+    if is_placeholder_key(key):
+        return result, False  # local config state, not a remote failure
+    if result.ok and result.adapter_error is None:
+        if fp in cache:
+            del cache[fp]
+            return result, True
+        return result, False
+    cache[fp] = {
+        "provider": provider.name,
+        "ok": result.ok,
+        "lines": [line[:400] for line in result.lines][:4],
+        "method": result.method,
+        "failed_at": datetime.now().isoformat(timespec="seconds"),
+    }
+    return result, True
+
+
 async def check_all_usage(
-    config: GatewayConfig, timeout: float = 15.0
+    config: GatewayConfig, timeout: float = 15.0, force: bool = False
 ) -> dict[str, list[UsageResult]]:
-    """Query usage for every key of every provider, concurrently."""
+    """Query usage for every key of every provider, concurrently.
+
+    Keys whose previous check hard-failed are served from the failure cache
+    (marked `skipped`) unless `force` is set; the cache is updated afterwards.
+    """
     results: dict[str, list[UsageResult]] = {}
+    cache = _load_fail_cache()
+    view: dict[str, dict] = {} if force else cache
     async with httpx.AsyncClient() as client:
         tasks = []
         refs: list[tuple[str, int]] = []
         for name, provider in config.providers.items():
             results[name] = [None] * len(provider.api_keys)  # type: ignore[list-item]
             for index, entry in enumerate(provider.api_keys):
-                tasks.append(check_key_usage(client, provider, entry, index, timeout))
+                tasks.append(_check_key_cached(client, provider, entry, index, timeout, view, cache))
                 refs.append((name, index))
         done = await asyncio.gather(*tasks)
-    for (name, index), result in zip(refs, done):
+    changed = False
+    for (name, index), (result, touched) in zip(refs, done):
         results[name][index] = result
+        changed = changed or touched
+    if changed:
+        _save_fail_cache(cache)
     return results
 
 
-def run_usage_check(config: GatewayConfig, timeout: float = 15.0) -> dict[str, list[UsageResult]]:
-    return asyncio.run(check_all_usage(config, timeout))
+def run_usage_check(
+    config: GatewayConfig, timeout: float = 15.0, force: bool = False
+) -> dict[str, list[UsageResult]]:
+    return asyncio.run(check_all_usage(config, timeout, force=force))