211 lines
8 KiB
Markdown
211 lines
8 KiB
Markdown
# Anthropic API Proxy for Gemini & OpenAI Models 🔄
|
|
|
|
**Use Anthropic clients (like Claude Code) with Gemini, OpenAI, or direct Anthropic backends.** 🤝
|
|
|
|
A proxy server that lets you use Anthropic clients with Gemini, OpenAI, or Anthropic models themselves (a transparent proxy of sorts), all via LiteLLM. 🌉
|
|
|
|
|
|
|
|
|
|
## Quick Start ⚡
|
|
|
|
### Prerequisites
|
|
|
|
- OpenAI API key 🔑
|
|
- Google AI Studio (Gemini) API key (if using Google provider) 🔑
|
|
- Google Cloud Project with Vertex AI API enabled (if using Application Default Credentials for Gemini) ☁️
|
|
- [uv](https://github.com/astral-sh/uv) installed.
|
|
|
|
### Setup 🛠️
|
|
|
|
#### From source
|
|
|
|
1. **Clone this repository**:
|
|
```bash
|
|
git clone https://github.com/1rgs/claude-code-proxy.git
|
|
cd claude-code-proxy
|
|
```
|
|
|
|
2. **Install uv** (if you haven't already):
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
*(`uv` will handle dependencies based on `pyproject.toml` when you run the server)*
|
|
|
|
3. **Configure Environment Variables**:
|
|
Copy the example environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Edit `.env` and fill in your API keys and model configurations:
|
|
|
|
* `ANTHROPIC_API_KEY`: (Optional) Needed only if proxying *to* Anthropic models.
|
|
* `OPENAI_API_KEY`: Your OpenAI API key (Required if using the default OpenAI preference or as fallback).
|
|
* `GEMINI_API_KEY`: Your Google AI Studio (Gemini) API key (Required if `PREFERRED_PROVIDER=google` and `USE_VERTEX_AUTH=true`).
|
|
* `USE_VERTEX_AUTH` (Optional): Set to `true` to use Application Default Credentials (ADC) will be used (no static API key required). Note: when USE_VERTEX_AUTH=true, you must configure `VERTEX_PROJECT` and `VERTEX_LOCATION`.
|
|
* `VERTEX_PROJECT` (Optional): Your Google Cloud Project ID (Required if `PREFERRED_PROVIDER=google` and `USE_VERTEX_AUTH=true`).
|
|
* `VERTEX_LOCATION` (Optional): The Google Cloud region for Vertex AI (e.g., `us-central1`) (Required if `PREFERRED_PROVIDER=google` and `USE_VERTEX_AUTH=true`).
|
|
* `PREFERRED_PROVIDER` (Optional): Set to `openai` (default), `google`, or `anthropic`. This determines the primary backend for mapping `haiku`/`sonnet`.
|
|
* `BIG_MODEL` (Optional): The model to map `sonnet` requests to. Defaults to `gpt-4.1` (if `PREFERRED_PROVIDER=openai`) or `gemini-2.5-pro-preview-03-25`. Ignored when `PREFERRED_PROVIDER=anthropic`.
|
|
* `SMALL_MODEL` (Optional): The model to map `haiku` requests to. Defaults to `gpt-4.1-mini` (if `PREFERRED_PROVIDER=openai`) or `gemini-2.0-flash`. Ignored when `PREFERRED_PROVIDER=anthropic`.
|
|
|
|
**Mapping Logic:**
|
|
- If `PREFERRED_PROVIDER=openai` (default), `haiku`/`sonnet` map to `SMALL_MODEL`/`BIG_MODEL` prefixed with `openai/`.
|
|
- If `PREFERRED_PROVIDER=google`, `haiku`/`sonnet` map to `SMALL_MODEL`/`BIG_MODEL` prefixed with `gemini/` *if* those models are in the server's known `GEMINI_MODELS` list (otherwise falls back to OpenAI mapping).
|
|
- If `PREFERRED_PROVIDER=anthropic`, `haiku`/`sonnet` requests are passed directly to Anthropic with the `anthropic/` prefix without remapping to different models.
|
|
|
|
4. **Run the server**:
|
|
```bash
|
|
uv run uvicorn server:app --host 0.0.0.0 --port 8082 --reload
|
|
```
|
|
*(`--reload` is optional, for development)*
|
|
|
|
#### Docker
|
|
|
|
If using docker, download the example environment file to `.env` and edit it as described above.
|
|
```bash
|
|
curl -O .env https://raw.githubusercontent.com/1rgs/claude-code-proxy/refs/heads/main/.env.example
|
|
```
|
|
|
|
Then, you can either start the container with [docker compose](https://docs.docker.com/compose/) (preferred):
|
|
|
|
```yml
|
|
services:
|
|
proxy:
|
|
image: ghcr.io/1rgs/claude-code-proxy:latest
|
|
restart: unless-stopped
|
|
env_file: .env
|
|
ports:
|
|
- 8082:8082
|
|
```
|
|
|
|
Or with a command:
|
|
|
|
```bash
|
|
docker run -d --env-file .env -p 8082:8082 ghcr.io/1rgs/claude-code-proxy:latest
|
|
```
|
|
|
|
### Using with Claude Code 🎮
|
|
|
|
1. **Install Claude Code** (if you haven't already):
|
|
```bash
|
|
npm install -g @anthropic-ai/claude-code
|
|
```
|
|
|
|
2. **Connect to your proxy**:
|
|
```bash
|
|
ANTHROPIC_BASE_URL=http://localhost:8082 claude
|
|
```
|
|
|
|
3. **That's it!** Your Claude Code client will now use the configured backend models (defaulting to Gemini) through the proxy. 🎯
|
|
|
|
## Model Mapping 🗺️
|
|
|
|
The proxy automatically maps Claude models to either OpenAI or Gemini models based on the configured model:
|
|
|
|
| Claude Model | Default Mapping | When BIG_MODEL/SMALL_MODEL is a Gemini model |
|
|
|--------------|--------------|---------------------------|
|
|
| haiku | openai/gpt-4o-mini | gemini/[model-name] |
|
|
| sonnet | openai/gpt-4o | gemini/[model-name] |
|
|
|
|
### Supported Models
|
|
|
|
#### OpenAI Models
|
|
The following OpenAI models are supported with automatic `openai/` prefix handling:
|
|
- o3-mini
|
|
- o1
|
|
- o1-mini
|
|
- o1-pro
|
|
- gpt-4.5-preview
|
|
- gpt-4o
|
|
- gpt-4o-audio-preview
|
|
- chatgpt-4o-latest
|
|
- gpt-4o-mini
|
|
- gpt-4o-mini-audio-preview
|
|
- gpt-4.1
|
|
- gpt-4.1-mini
|
|
|
|
#### Gemini Models
|
|
The following Gemini models are supported with automatic `gemini/` prefix handling:
|
|
- gemini-2.5-pro
|
|
- gemini-2.5-flash
|
|
|
|
### Model Prefix Handling
|
|
The proxy automatically adds the appropriate prefix to model names:
|
|
- OpenAI models get the `openai/` prefix
|
|
- Gemini models get the `gemini/` prefix
|
|
- The BIG_MODEL and SMALL_MODEL will get the appropriate prefix based on whether they're in the OpenAI or Gemini model lists
|
|
|
|
For example:
|
|
- `gpt-4o` becomes `openai/gpt-4o`
|
|
- `gemini-2.5-pro-preview-03-25` becomes `gemini/gemini-2.5-pro-preview-03-25`
|
|
- When BIG_MODEL is set to a Gemini model, Claude Sonnet will map to `gemini/[model-name]`
|
|
|
|
### Customizing Model Mapping
|
|
|
|
Control the mapping using environment variables in your `.env` file or directly:
|
|
|
|
**Example 1: Default (Use OpenAI)**
|
|
No changes needed in `.env` beyond API keys, or ensure:
|
|
```dotenv
|
|
OPENAI_API_KEY="your-openai-key"
|
|
GEMINI_API_KEY="your-google-key" # Needed if PREFERRED_PROVIDER=google
|
|
# PREFERRED_PROVIDER="openai" # Optional, it's the default
|
|
# BIG_MODEL="gpt-4.1" # Optional, it's the default
|
|
# SMALL_MODEL="gpt-4.1-mini" # Optional, it's the default
|
|
```
|
|
|
|
**Example 2a: Prefer Google (using GEMINI_API_KEY)**
|
|
```dotenv
|
|
GEMINI_API_KEY="your-google-key"
|
|
OPENAI_API_KEY="your-openai-key" # Needed for fallback
|
|
PREFERRED_PROVIDER="google"
|
|
# BIG_MODEL="gemini-2.5-pro" # Optional, it's the default for Google pref
|
|
# SMALL_MODEL="gemini-2.5-flash" # Optional, it's the default for Google pref
|
|
```
|
|
|
|
**Example 2b: Prefer Google (using Vertex AI with Application Default Credentials)**
|
|
```dotenv
|
|
OPENAI_API_KEY="your-openai-key" # Needed for fallback
|
|
PREFERRED_PROVIDER="google"
|
|
VERTEX_PROJECT="your-gcp-project-id"
|
|
VERTEX_LOCATION="us-central1"
|
|
USE_VERTEX_AUTH=true
|
|
# BIG_MODEL="gemini-2.5-pro" # Optional, it's the default for Google pref
|
|
# SMALL_MODEL="gemini-2.5-flash" # Optional, it's the default for Google pref
|
|
```
|
|
|
|
**Example 3: Use Direct Anthropic ("Just an Anthropic Proxy" Mode)**
|
|
```dotenv
|
|
ANTHROPIC_API_KEY="sk-ant-..."
|
|
PREFERRED_PROVIDER="anthropic"
|
|
# BIG_MODEL and SMALL_MODEL are ignored in this mode
|
|
# haiku/sonnet requests are passed directly to Anthropic models
|
|
```
|
|
|
|
*Use case: This mode enables you to use the proxy infrastructure (for logging, middleware, request/response processing, etc.) while still using actual Anthropic models rather than being forced to remap to OpenAI or Gemini.*
|
|
|
|
**Example 4: Use Specific OpenAI Models**
|
|
```dotenv
|
|
OPENAI_API_KEY="your-openai-key"
|
|
GEMINI_API_KEY="your-google-key"
|
|
PREFERRED_PROVIDER="openai"
|
|
BIG_MODEL="gpt-4o" # Example specific model
|
|
SMALL_MODEL="gpt-4o-mini" # Example specific model
|
|
```
|
|
|
|
## How It Works 🧩
|
|
|
|
This proxy works by:
|
|
|
|
1. **Receiving requests** in Anthropic's API format 📥
|
|
2. **Translating** the requests to OpenAI format via LiteLLM 🔄
|
|
3. **Sending** the translated request to OpenAI 📤
|
|
4. **Converting** the response back to Anthropic format 🔄
|
|
5. **Returning** the formatted response to the client ✅
|
|
|
|
The proxy handles both streaming and non-streaming responses, maintaining compatibility with all Claude clients. 🌊
|
|
|
|
## Contributing 🤝
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request. 🎁
|