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。
  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

配置示例

{
  "host": "127.0.0.1",
  "port": 8000,
  "default_base_url": "https://api.openai.com",
  "upstream_routes": {
    "https://example.com/tokenplan": {
      "anthropic": "anthropic/"
    }
  },
  "request_timeout": 60,
  "max_retries": 2,
  "key_failure_threshold": 2,
  "key_cooldown_seconds": 60,
  "local_api_key": "amkr_your-local-api-key",
  "unified_model": {
    "model": "gpt-4o-mini",
    "key": null
  },
  "models": [
    {
      "id": "gpt-4o-mini",
      "aliases": ["fast-mini"],
      "routing_mode": "round_robin",
      "keys": [
        {"name": "openai-main", "api_key": "sk-your-first-upstream-key"},
        {"name": "openai-backup", "api_key": "sk-your-second-upstream-key"},
        {
          "name": "mimo-tokenplan",
          "api_key": "sk-your-third-upstream-key",
          "base_url": "https://example.com/tokenplan"
        }
      ]
    }
  ]
}

local_api_key 是客户端访问本地 AMKR 的 Key；keys[].api_key 是 AMKR 转发到上游模型服务时使用的真实供应商 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 Jun 28, 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 Jun 28, 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-2.2.5.tar.gz (144.6 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-2.2.5-py3-none-any.whl (120.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: auto_model_key_router-2.2.5.tar.gz
  • Upload date:
  • Size: 144.6 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-2.2.5.tar.gz
Algorithm Hash digest
SHA256 c712075df658c0f118511d84394e5bc4e60c0987879ddb57afd3a394f61e9b41
MD5 4c0f68ccf5b49450d6e742b32495f736
BLAKE2b-256 4268f8b8d2a5e65d123fc8c337ddae2f480c8c5abf8c1be0cdb922a11cac605f

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-2.2.5.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-2.2.5-py3-none-any.whl.

File metadata

File hashes

Hashes for auto_model_key_router-2.2.5-py3-none-any.whl
Algorithm Hash digest
SHA256 15fbf539031d5264010fdd48f7e87720009f94c455be8ff2ca018eb65c80c0fd
MD5 3d73a4fdc3c0ce7adb9e268cba2658fe
BLAKE2b-256 4e7aea299daa48357923a3a25606372983b6d7a4d6011bc15aeccc26269167fe

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-2.2.5-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

3.0.4

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

This release

2.2.5 This release

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