A simple, focused OpenAI-compatible API gateway for Claude Code with streaming support. Leverage the Claude Code SDK use mode. Don't hack the token credentials.
Use the Makefile to install the project or pip/uv.
# Clone and setup git clone https://github.com/codingworkflow/claude-code-api cd claude-code-api # Install dependencies & module make install # Start the API server make start- There might be a limit on maximum input below normal "Sonnet 4" input as Claude Code usually doesn't ingest more than 25k tokens (despite the context being 100k).
- Claude Code auto-compacts context beyond 100k.
- Currently runs with bypass mode to avoid tool errors.
- Claude Code tools may need to be disabled to avoid overlap and background usage.
- Runs only on Linux/Mac as Claude Code doesn't run on Windows (you can use WSL).
- Note that Claude Code will default to accessing the current workspace environment/folder and is set to use bypass mode.
- Claude-Only Models: Supports exactly the 6 Claude models that Claude Code CLI offers
- OpenAI Compatible: Drop-in replacement for OpenAI API endpoints
- Streaming Support: Real-time streaming responses
- Context Preservation: Full conversation history support with system prompts
- Auto Key Rotation: Automatic API key rotation when quota is exceeded
- Shell Config Updates: Automatically updates shell configuration files (.bashrc, .bash_profile, .zshrc) when keys rotate
- Simple & Clean: No over-engineering, focused implementation
- Claude Code Integration: Leverages Claude Code CLI with streaming output
claude-opus-4-1-20250805- Claude Opus 4.1 (Latest, most powerful)claude-opus-4-20250514- Claude Opus 4claude-sonnet-4-20250514- Claude Sonnet 4claude-3-7-sonnet-20250219- Claude Sonnet 3.7claude-3-5-sonnet-20241022- Claude Sonnet 3.5 (Latest Sonnet)claude-3-5-haiku-20241022- Claude Haiku 3.5 (Fast & cost-effective)
The system automatically handles API key failures and rotates to backup keys when:
- Current key runs out of quota/credits
- Authentication errors occur
- Rate limits are exceeded
Configuration:
{ "claude_api_keys": [ { "name": "primary", "token": "sk-your-primary-key", "base_url": "https://anyrouter.top", "status": "active" }, { "name": "backup1", "token": "sk-your-backup-key", "base_url": "https://anyrouter.top", "status": "active" } ] }When a key fails:
- ✅ Automatically detects quota/auth errors
- ✅ Rotates to next available key
- ✅ Updates environment variables (
ANTHROPIC_AUTH_TOKEN) - ✅ Updates shell config files (.bashrc, .bash_profile, .zshrc)
- ✅ Continues serving requests without interruption
Unlike basic implementations, this gateway preserves complete conversation context:
- ✅ System prompts are properly handled
- ✅ Full conversation history is maintained
- ✅ Assistant responses are remembered across turns
- ✅ OpenAI-compatible message format support
Example with context:
{ "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "My name is Alice."}, {"role": "assistant", "content": "Nice to meet you, Alice!"}, {"role": "user", "content": "What's my name?"} ] }Response: "Your name is Alice." ✅ (Context preserved)
- Python 3.10+
- Claude Code CLI installed and accessible
- Valid Anthropic API key configured in Claude Code (ensure it works in current directory src/)
# Clone and setup git clone https://github.com/codingworkflow/claude-code-api cd claude-code-api # Copy environment example and configure cp .env.example .env # Edit .env to configure your settings (especially API keys for production) # Install dependencies make install # Run tests to verify setup make test # Start the API server (development with auto-reload) make start # Start the API server (production, foreground) make start-prod # Start the API server (production, background - survives SSH disconnect) make start-prod-bg # Stop background server make stop # Restart background server make restart # Check server status and recent logs make status # Follow server logs in real-time make logsThe API will be available at:
- API: http://localhost:8010
- Docs: http://localhost:8010/docs
- Health: http://localhost:8010/health
For production use, especially on remote servers:
# Start in background (survives SSH disconnect) make start-prod-bg # Check status make status # View logs make logs # Restart if needed make restart # Stop when needed make stop ## Makefile Commands ### 🔧 使用方式 1. **开发环境**：`make start` （自动重载，适合开发） 2. **生产前台**：`make start-prod` （稳定，但SSH断开会停止） 3. **生产后台**：`make start-prod-bg` （最稳定，SSH断开仍运行） ### Core Commands ```bash # Development make install # Install dependencies make start # Start server (development with auto-reload) # Production make start-prod # Start server (production, foreground) make start-prod-bg # Start server (production, background) # Process Management make stop # Stop background server make restart # Restart background server make status # Show status and recent logs make logs # Follow logs in real-time # Testing & Cleanup make test # Run tests make clean # Clean cache files make kill PORT=X # Kill process on specific portmake test # Run all tests make test-fast # Run tests (skip slow ones) make test-hello # Test hello world with Haiku make test-health # Test health check only make test-models # Test models API only make test-chat # Test chat completions only make quick-test # Quick validation of core functionalitymake dev-setup # Complete development setup make lint # Run linting checks make format # Format code with black/isort make type-check # Run type checking make clean # Clean up cache filesmake help # Show all available commands make models # Show supported Claude models make info # Show project information make check-claude # Check if Claude Code CLI is availableBy default, the API runs without authentication for development. For production use, enable API key authentication:
- Configure API Keys in
.env:
# Enable authentication REQUIRE_AUTH=true # Add your API keys (comma-separated) API_KEYS=your-secure-api-key-1,your-secure-api-key-2 # Generate secure keys using provided script: python3 scripts/generate_api_keys.py -n 2 --env # Or manually with openssl: # openssl rand -hex 32- Use API Key in Requests:
Option A: Authorization Header (Recommended)
curl -X POST http://localhost:8000/v1/chat/completions \ -H "Authorization: Bearer your-secure-api-key-1" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-sonnet-20241022", "messages": [{"role": "user", "content": "Hello!"}] }'Option B: X-API-Key Header
curl -X POST http://localhost:8000/v1/chat/completions \ -H "x-api-key: your-secure-api-key-1" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-sonnet-20241022", "messages": [{"role": "user", "content": "Hello!"}] }'- Rate Limiting:
- Default: 100 requests per minute per API key
- Configurable via
RATE_LIMIT_REQUESTS_PER_MINUTEin.env
curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-haiku-20241022", "messages": [ {"role": "user", "content": "Hello!"} ] }'curl http://localhost:8000/v1/modelscurl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-haiku-20241022", "messages": [ {"role": "user", "content": "Tell me a joke"} ], "stream": true }'claude-code-api/ ├── claude_code_api/ │ ├── main.py # FastAPI application │ ├── api/ # API endpoints │ │ ├── chat.py # Chat completions │ │ ├── models.py # Models API │ │ ├── projects.py # Project management │ │ └── sessions.py # Session management │ ├── core/ # Core functionality │ │ ├── auth.py # Authentication │ │ ├── claude_manager.py # Claude Code integration │ │ ├── session_manager.py # Session management │ │ ├── config.py # Configuration │ │ └── database.py # Database layer │ ├── models/ # Data models │ │ ├── claude.py # Claude-specific models │ │ └── openai.py # OpenAI-compatible models │ ├── utils/ # Utilities │ │ ├── streaming.py # Streaming support │ │ └── parser.py # Output parsing │ └── tests/ # Test suite ├── Makefile # Development commands ├── pyproject.toml # Project configuration ├── setup.py # Package setup └── README.md # This file The test suite validates:
- Health check endpoints
- Models API (Claude models only)
- Chat completions with Haiku model
- Hello world functionality
- OpenAI compatibility (structure)
- Error handling
Run specific test suites:
make test-hello # Test hello world with Haiku make test-models # Test models API make test-chat # Test chat completionsmake dev-setupmake format # Format code make lint # Check linting make type-check # Type checkingmake quick-test # Test core functionalitymake deploy-checkmake start-prod # Start with multiple workersUse http://127.0.0.1:8000/v1 as OpenAPI endpoint
Key settings in claude_code_api/core/config.py:
claude_binary_path: Path to Claude Code CLIproject_root: Root directory for projectsdatabase_url: Database connection stringrequire_auth: Enable/disable authentication
- Simple & Focused: No over-engineering
- Claude-Only: Pure Claude gateway, no OpenAI models
- Streaming First: Built for real-time streaming
- OpenAI Compatible: Drop-in API compatibility
- Test-Driven: Comprehensive test coverage
curl http://localhost:8000/healthResponse:
{ "status": "healthy", "version": "1.0.0", "claude_version": "1.x.x", "active_sessions": 0 }This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.