rotor-gateway 0.2.0

No project description provided

Rotor

Rotor is an API-only LLM gateway. It exposes OpenAI-compatible, Anthropic-compatible, and OpenAI Responses-compatible endpoints over the models and provider keys configured as channels.

Rotor includes a minimal browser admin page at /. Management can also be done directly through HTTP admin APIs.

Run

cd /Users/whoami/research/apirouter/rotor
pip install -e .
rotor serve --host 0.0.0.0 --port 8000

Open the admin page:

http://localhost:8000

By default, Rotor stores runtime files in ~/.cache/rotor:

~/.cache/rotor/
  rotor.db
  conversations/

Important Environment

# Optional. Defaults to sqlite+aiosqlite:///~/.cache/rotor/rotor.db
DATABASE_URL=
# Optional. Defaults to ~/.cache/rotor/conversations
CONVERSATION_STORE_DIR=

Configure Channels

Each channel stores one provider base URL, provider API key, supported models, priority, and weight.

curl -X POST http://localhost:8000/api/admin/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "zhipu-main",
    "type": "zhipu",
    "key": "provider-api-key",
    "base_url": "https://open.bigmodel.cn/api/paas/v4",
    "models": ["glm-4.7"],
    "model_mapping": {},
    "priority": 10,
    "weight": 1,
    "enabled": true,
    "protocol": "openai"
  }'

base_url is the upstream provider API root. key is that provider's API key. Different providers or different keys should be configured as separate channels. Channels serving the same model are distributed by priority and weight.

Set protocol to openai_responses for an upstream that exposes native POST /responses. Native Responses channels preserve hosted tools, multimodal items, background jobs, response state, resource lifecycle calls, input-token counting, compaction, and Responses SSE events. Rotor persistently binds each native response ID to its originating channel and API token, so retrieval, cancellation, deletion, input-item listing, and previous_response_id requests return to the correct upstream account. Function tools can also be converted across openai, openai_responses, and anthropic channels.

Channel connectivity tests use GET /models and do not consume model tokens. An administrator can explicitly run a generation capability probe (which may be billable):

curl -X POST \
  "http://localhost:8000/api/admin/channels/1/test?capability=function_call&test_model=your-model"

Generate User API Key

curl -X POST "http://localhost:8000/api/admin/tokens/generate?name=demo&quota=1000000" \

Use the returned key against Rotor:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $ROTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Conversation-Id: conv_demo" \
  -d '{
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "hello"}]
  }'

Codex CLI、Claude Code 和 OpenCode 的配置模板与冒烟命令见 客户端接入指南。

Endpoints

• GET /
• GET /api
• POST /v1/chat/completions
• POST /v1/responses
• GET/DELETE /v1/responses/{response_id}
• POST /v1/responses/{response_id}/cancel
• GET /v1/responses/{response_id}/input_items
• POST /v1/responses/input_tokens
• POST /v1/responses/compact
• POST /anthropic/v1/messages
• POST /anthropic/v1/messages/count_tokens
• GET /v1/models
• GET/POST/PUT/DELETE /api/admin/channels
• GET/POST/PUT/DELETE /api/admin/tokens
• GET /api/admin/logs