Auto Model Key Router

一个本地 OpenAI-compatible API 路由器：把多个模型和多个上游 API Key 统一收口到本地服务，自动分流、失败切换、统计调用，并可一键接入 Claude Code / Codex。

主要能力

  • 多 Key 路由：同一模型可配置多个 Key，支持 round_robin、priority、only_first。
  • 失败切换与冷却：遇到 401/403/429/5xx 等可重试错误时自动重试或切换 Key，并持久化冷却状态。
  • 统一模型名：客户端固定请求 unified-model，真实模型和固定 Key 可在路由器侧随时切换。
  • OpenAI-compatible 代理：支持 /v1/chat/completions、/v1/models，并兼容 Claude Code 的 /v1/messages 与 Codex 的 /v1/responses；可为不同协议模式配置上游额外路径。
  • Terminal UI 管理：在 TUI 中配置模型、Key、统一模型、服务注册和客户端接入。
  • 访客 Key：安装 visitor extra 后，可用固定访客 Key 暴露受限公共模型。
  • 统计与日志：记录本地/访客调用、模型、Key、状态码、token、重试、延迟等指标。

安装

需要 Python >=3.12。

pipx install auto-model-key-router
# 或
uv tool install auto-model-key-router

启用访客 Key 功能：

pipx install "auto-model-key-router[visitor]"
# 或
uv tool install "auto-model-key-router[visitor]"

安装后可使用两个等价命令：

amkr --version
auto-model-key-router --version

快速开始

1. 启动 Terminal UI

amkr

首次启动会在系统缓存目录自动创建配置文件和本地鉴权 Key。你也可以复制示例配置到当前目录：

cp router-config.example.json router-config.json
amkr --config router-config.json

Windows PowerShell 可使用：

copy router-config.example.json router-config.json
amkr --config router-config.json

2. 配置模型与 Key

在 TUI 中进入：

  1. 模型 Key：添加真实模型和上游 API Key，并可在管理 Key 中对当前 Key 或所有 Key 探测 /v1/chat/completions、/v1/messages、/v1/responses 可用性。
  2. 统一模型：把 unified-model 指向一个真实模型，必要时固定到某个 Key。
  3. 一键配置 → 路由服务：启动或注册本地代理服务。
  4. 一键配置 → Claude Code / Codex：按需自动写入客户端配置。

3. 调用本地代理

默认服务地址是：

http://127.0.0.1:8000

请求示例：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer amkr_your-local-api-key" \
  -d '{
    "model": "unified-model",
    "messages": [{"role": "user", "content": "hello"}]
  }'

也可以把 model 写成真实模型 ID、模型 alias，或 模型ID[key name] 来显式指定某个 Key。

常用命令

# 打开 TUI
amkr

# 使用指定配置文件打开 TUI
amkr --config router-config.json

# 后台启动 / 查看状态 / 停止
auto-model-key-router --config router-config.json --serve
auto-model-key-router --config router-config.json --status
auto-model-key-router --config router-config.json --stop

# 注册、管理系统服务
auto-model-key-router --config router-config.json --install-service
auto-model-key-router --config router-config.json --service status
auto-model-key-router --config router-config.json --service restart

# 查看配置摘要、日志与统计
auto-model-key-router --config router-config.json --show-config
auto-model-key-router --config router-config.json --show-logs 50

# 管理 unified-model
auto-model-key-router --config router-config.json --show-unified-model
auto-model-key-router --config router-config.json --switch-model gpt-4o-mini
auto-model-key-router --config router-config.json --switch-key auto

配置示例

{
  "config_version": 3,
  "host": "127.0.0.1",
  "port": 8000,
  "request_timeout": 60,
  "max_retries": 2,
  "key_failure_threshold": 2,
  "key_cooldown_seconds": 60,
  "local_api_key": "amkr_your-local-api-key",
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com",
      "routes": {
        "openai": "v1/chat/completions",
        "responses": "v1/responses"
      },
      "keys": {
        "main": {"api_key": "sk-your-first-upstream-key"},
        "backup": {"api_key": "sk-your-second-upstream-key"}
      },
      "pools": {
        "default": {
          "keys": ["main", "backup"],
          "available_models": ["gpt-4o-mini"],
          "models": ["gpt-4o-mini"]
        }
      }
    },
    "tokenplan": {
      "base_url": "https://example.com/tokenplan",
      "routes": {"anthropic": "anthropic/"},
      "keys": {
        "mimo": {"api_key": "sk-your-third-upstream-key"}
      },
      "pools": {
        "default": {"keys": ["mimo"]}
      }
    }
  },
  "unified_model": {
    "model": "gpt-4o-mini",
    "key": null
  },
  "models": {
    "gpt-4o-mini": {
      "aliases": ["fast-mini"],
      "routing_mode": "round_robin",
      "targets": [
        {"provider": "openai", "pool": "default", "upstream_model": "gpt-4o-mini"},
        {"provider": "tokenplan", "pool": "default", "upstream_model": "gpt-4o-mini"}
      ]
    }
  }
}

local_api_key 是客户端访问本地 AMKR 的 Key；providers.*.keys.*.api_key 是真实供应商 Key；providers.*.pools 表示同一模型能力池，TUI 创建或刷新模型池时会探测可用模型与路由并写入 available_models / routes 元信息，探测到的模型默认不启用；如果上游不支持 /v1/models，TUI 会允许手动填写可用模型并继续探测路由；providers.*.pools.*.models 是手动启用后可用于添加本地模型路由的模型清单。旧版 models[].keys[] 和 v2 的 target.key 会自动迁移为新版语义。

文档

访客 Key 简介

安装 auto-model-key-router[visitor] 后，可以用固定 Key amkr-visitor 暴露受限公共模型。只有设置了 allow_visitor: true 的上游 Key 才能被访客使用，访客看到的模型名格式为 amkr-{真实模型ID}。

详细限制和示例见 完整使用教程：使用访客 Key。

开发

git clone https://github.com/sparr68/auto-model-key-router.git
cd auto-model-key-router
pip install -e ".[test]"
pytest

安全提示

  • 不要把真实上游 API Key 提交到 Git。
  • local_api_key 为空会关闭本地鉴权；仅建议在可信本机环境使用。
  • 如果监听 0.0.0.0 或暴露到局域网/公网，请务必启用本地鉴权并配置防火墙。

License

MIT

Project links

Data verified by PyPI on Jul 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.2.9)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Sparrived from gravatar.com Sparrived

Credits

Author: Sparrived

GitHub Statistics

Data verified by PyPI on Jul 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

visitor test release dev

Tags

openai api-key router fastapi cli tui

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

auto_model_key_router-3.0.4.tar.gz (168.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

auto_model_key_router-3.0.4-py3-none-any.whl (137.0 kB view details)

Uploaded Python 3

File details

Details for the file auto_model_key_router-3.0.4.tar.gz.

File metadata

  • Download URL: auto_model_key_router-3.0.4.tar.gz
  • Upload date:
  • Size: 168.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for auto_model_key_router-3.0.4.tar.gz
Algorithm Hash digest
SHA256 c2500d910fa9bf0d6b167e57ba9cc2ac07f667d20b072a5a244486e4f60e81b8
MD5 29dd4e678f05ce46e0ab79c023067434
BLAKE2b-256 2ea56a14690a69ee68e4ab99dcbea428cd987dbf5db577222201e0b5d105410f

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-3.0.4.tar.gz:

Publisher: publish-pypi.yml on Sparrived/auto-model-key-router

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auto_model_key_router-3.0.4-py3-none-any.whl.

File metadata

File hashes

Hashes for auto_model_key_router-3.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 cadf6e8de7ab395a786ddecce9724cb2ecff0a9d8bf61b9b321a85027707e771
MD5 63a6269b89192e1a1a9eab9c8a791a1b
BLAKE2b-256 e2e260d25375d2258c21485fd234080bf0200749887907c6a3b6a2c1ce196490

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-3.0.4-py3-none-any.whl:

Publisher: publish-pypi.yml on Sparrived/auto-model-key-router

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.2.9

2 files

3.2.8

2 files

3.2.7

2 files

3.2.6

2 files

3.2.5

2 files

3.2.4

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.1

2 files

3.1.0

2 files

This release

3.0.4 This release

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.2.6

2 files

2.2.5.post1

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3.post1

2 files

2.2.3

2 files

2.2.2.post3

2 files

2.2.2.post2

2 files

2.2.2.post1

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.6

2 files

2.1.5.post1

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.2

2 files

2.0.0.post1

2 files

2.0.0

2 files

1.7.0

2 files

1.6.1.post2

2 files

1.6.1.post1

2 files

1.6.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

Pre-release

1.3.3a1

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.4

2 files

Pre-release

1.2.3rc3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page