HF_SPACES_DEPLOYMENT.md

HF Spaces Deployment - Claude Multi-API Key Feature

Overview

This version of CLIProxyAPI includes support for multiple Claude API keys with round-robin load balancing, accessible through both the Management UI and API endpoints.

What's New

1. Multiple Claude API Keys

• Add multiple API keys per Claude configuration
• Each key can have its own proxy URL
• Automatic round-robin load balancing across all keys
• Backward compatible with single-key configurations

2. Updated Management UI

The management UI (/management.html) now includes:

• AI Providers → Claude API Configuration section
• Add/remove multiple API keys with individual proxy settings
• Visual interface for managing key entries

3. API Endpoints

The following endpoints support the new api-key-entries field:

• GET /api/config/claude-api-key - Returns configurations with api-key-entries
• PUT /api/config/claude-api-key - Create/update with multiple keys
• PATCH /api/config/claude-api-key - Update specific fields including api-key-entries
• DELETE /api/config/claude-api-key - Delete by API key or index

Configuration Examples

Via Management UI

1. Access https://your-space.hf.space/management.html
2. Navigate to AI Providers → Claude API Configuration
3. Click Add Configuration
4. Add multiple API keys in the API Keys section
5. Save

Via Config File (config.yaml)

claude-api-key:
  - api-key-entries:
      - api-key: "sk-ant-api03-key1..."
        proxy-url: "http://proxy1:8080"
      - api-key: "sk-ant-api03-key2..."
        proxy-url: "http://proxy2:8080"
      - api-key: "sk-ant-api03-key3..."
    base-url: "https://api.anthropic.com"
    priority: 10
    prefix: "team-a/"
    models:
      - name: claude-3-5-sonnet-20241022
        alias: claude-sonnet
      - name: claude-3-opus-20240229
        alias: claude-opus

Via API

# Add Claude configuration with multiple keys
curl -X PUT https://your-space.hf.space/api/config/claude-api-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '[{
    "api-key-entries": [
      {"api-key": "sk-ant-api03-key1...", "proxy-url": "http://proxy1:8080"},
      {"api-key": "sk-ant-api03-key2...", "proxy-url": "http://proxy2:8080"}
    ],
    "base-url": "https://api.anthropic.com",
    "priority": 10,
    "models": [
      {"name": "claude-3-5-sonnet-20241022", "alias": "claude-sonnet"}
    ]
  }]'

How It Works

1. Load Balancing: Each API key becomes a separate Auth entry. The system uses round-robin selection to distribute requests across all available keys.

2. Per-Key Proxy: Each API key entry can specify its own proxy-url. If not specified, it falls back to the key-level proxy-url or no proxy.

3. Backward Compatibility: The old single api-key field still works. If api-key-entries is empty, the system uses the single api-key.

4. Failover: If one API key fails (e.g., rate limited), the system automatically tries the next key in the rotation.

Files Modified

Backend (Go)

• internal/config/config.go - Added ClaudeAPIKeyEntry type and updated ClaudeKey
• internal/watcher/synthesizer/config.go - Updated synthesizeClaudeKeys() for multi-key support
• internal/watcher/diff/config_diff.go - Added diff detection for api-key-entries
• internal/api/handlers/management/config_lists.go - Updated API handlers
• internal/managementasset/management.html - Updated React UI build

Frontend (React/TypeScript)

• management-center/src/types/provider.ts - Added apiKeyEntries to types
• management-center/src/components/providers/ClaudeSection/ClaudeModal.tsx - New multi-key UI
• management-center/src/components/providers/types.ts - Updated form state types
• management-center/src/i18n/locales/*.json - Added translation keys

Testing

All tests pass for the modified components:

go test ./internal/config/... ./internal/watcher/... ./internal/api/handlers/management/... -v

Deployment Notes

1. The management.html file is embedded in the binary at /home/internal/managementasset/management.html
2. The Dockerfile copies the entire project, so the management UI is included automatically
3. No additional environment variables are required for the multi-key feature
4. The feature works out of the box once deployed

Troubleshooting

Management UI Not Loading

• Ensure the management.html file exists in the Docker image
• Check that RemoteManagement.DisableControlPanel is not set to true in config

API Keys Not Rotating

• Verify that api-key-entries is properly formatted in the config
• Check logs for any synthesis errors
• Ensure at least one API key has a non-empty value

Per-Key Proxy Not Working

• Verify the proxy URL format (e.g., http://proxy.example.com:8080)
• Check that the proxy is accessible from the HF Spaces environment