Add comprehensive README
- Document features, configuration, and API endpoints - Include request/response examples for streaming and non-streaming - Explain field mapping between OpenAI and Anthropic formats - Document security headers and claude-code mimicry - Add project structure overview and build instructions
This commit is contained in:
Franz Kafka
parent
73efb02461
commit
9bc49a25e1
1 changed files with 191 additions and 0 deletions
191
README.md
Normal file
191
README.md
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
# proxx
|
||||
|
||||
OpenAI-to-Anthropic API proxy that converts OpenAI-compatible requests to Anthropic format and forwards them to a configurable upstream endpoint.
|
||||
|
||||
## Features
|
||||
|
||||
- **OpenAI API compatibility** — Exposes `/v1/chat/completions` and `/v1/models` endpoints
|
||||
- **Automatic format conversion** — Translates OpenAI request/response to/from Anthropic format
|
||||
- **Streaming support** — Converts non-streaming upstream responses to OpenAI SSE format for clients
|
||||
- **Security headers** — Blocks sensitive headers (Referer, Cookie, X-Forwarded-*) from reaching upstream
|
||||
- **Claude-code mimicry** — Sets headers to mimic the claude-code CLI tool
|
||||
- **Single binary** — No runtime dependencies, just one executable
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Use OpenAI-compatible tools with Anthropic/ZAI API
|
||||
- Replace Claude API endpoint without modifying client code
|
||||
- Proxy requests to different Anthropic-compatible providers
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `config.yaml` file in the working directory:
|
||||
|
||||
```yaml
|
||||
port: 8080
|
||||
upstream_url: "https://api.z.ai/api/anthropic"
|
||||
```
|
||||
|
||||
- `port`: Port to listen on (default: 8080)
|
||||
- `upstream_url`: Base URL for the Anthropic-compatible upstream API
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
go build -o proxx
|
||||
```
|
||||
|
||||
Requires Go 1.21+ with only `gopkg.in/yaml.v3` as an external dependency.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
./proxx
|
||||
```
|
||||
|
||||
The server will start and log:
|
||||
```
|
||||
Starting proxx on :8080, upstream: https://api.z.ai/api/anthropic
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### GET /v1/models
|
||||
|
||||
Returns a list of available models in OpenAI format.
|
||||
|
||||
Example response:
|
||||
```json
|
||||
{
|
||||
"object": "list",
|
||||
"data": [
|
||||
{"id": "glm-4.7", "object": "model", "created": 1234567890, "owned_by": "zhipu"},
|
||||
{"id": "glm-4.6", "object": "model", "created": 1234567890, "owned_by": "zhipu"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /v1/chat/completions
|
||||
|
||||
Accepts OpenAI chat completion format and converts to Anthropic format.
|
||||
|
||||
**Request headers:**
|
||||
- `Authorization: Bearer <api-key>` — Required. Extracted and forwarded as `x-api-key`
|
||||
- `Content-Type: application/json` — Required
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{
|
||||
"model": "glm-4.7",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello!"}
|
||||
],
|
||||
"stream": false
|
||||
}
|
||||
```
|
||||
|
||||
**Non-streaming response:**
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-abc123",
|
||||
"object": "chat.completion",
|
||||
"created": 1234567890,
|
||||
"model": "glm-4.7",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Hello! How can I help you today?"
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 15,
|
||||
"total_tokens": 25
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Streaming response:**
|
||||
Returns Server-Sent Events (SSE) in OpenAI format:
|
||||
```
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"glm-4.7","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"glm-4.7","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
## Field Mapping
|
||||
|
||||
### OpenAI → Anthropic
|
||||
|
||||
| OpenAI Field | Anthropic Field | Notes |
|
||||
|--------------|-----------------|-------|
|
||||
| `model` | `model` | Direct mapping |
|
||||
| `messages[]` | `messages[]` | Converted to Anthropic format |
|
||||
| `system` message | `system` (top-level) | Extracted from messages |
|
||||
| `temperature` | `temperature` | Direct mapping |
|
||||
| `max_tokens` | `max_tokens` | Defaults to 32000 if omitted |
|
||||
| `top_p` | `top_p` | Direct mapping |
|
||||
| `stop` | `stop_sequences` | Array mapping |
|
||||
| `tools[]` | `tools[]` | Function tools converted |
|
||||
| `tool_choice` | `tool_choice` | Enum mapping |
|
||||
|
||||
### Anthropic → OpenAI
|
||||
|
||||
| Anthropic Field | OpenAI Field | Notes |
|
||||
|-----------------|--------------|-------|
|
||||
| `content[0].text` | `choices[0].message.content` | Text content |
|
||||
| `content[].tool_use` | `choices[0].message.tool_calls[]` | Tool calls |
|
||||
| `usage.input_tokens` | `usage.prompt_tokens` | Input tokens |
|
||||
| `usage.output_tokens` | `usage.completion_tokens` | Output tokens |
|
||||
| `stop_reason` | `finish_reason` | `end_turn` → `stop`, `tool_use` → `tool_calls`, `max_tokens` → `length` |
|
||||
|
||||
## Claude-Code Mimicry
|
||||
|
||||
The proxy sets these headers on all upstream requests to mimic the claude-code CLI:
|
||||
|
||||
| Header | Value |
|
||||
|--------|-------|
|
||||
| `User-Agent` | `claude-cli/1.0.18 (pro, cli)` |
|
||||
| `x-api-key` | From incoming `Authorization: Bearer` |
|
||||
| `x-app` | `cli` |
|
||||
| `anthropic-version` | `2023-06-01` |
|
||||
| `anthropic-beta` | `interleaved-thinking-2025-05-14,prompt-caching-scope-2026-01-05,context-management-2025-06-27` |
|
||||
| `X-Claude-Code-Session-Id` | Random UUID generated at startup |
|
||||
| `content-type` | `application/json` |
|
||||
|
||||
## Security
|
||||
|
||||
### Blocked Headers
|
||||
|
||||
The proxy blocks these headers from being forwarded to upstream:
|
||||
|
||||
- `Referer` — Prevents leaking internal URLs
|
||||
- `Cookie` — Prevents leaking session cookies
|
||||
- `Authorization` — Already extracted and forwarded as `x-api-key`
|
||||
- `X-Forwarded-For` — Prevents leaking client IP
|
||||
- `X-Real-Ip` — Prevents leaking client IP
|
||||
- `X-Forwarded-Host` — Prevents leaking internal hostnames
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
proxx/
|
||||
├── README.md # This file
|
||||
├── main.go # Entry point, config loading, HTTP server setup
|
||||
├── handler.go # HTTP handlers for /v1/chat/completions and /v1/models
|
||||
├── converter.go # OpenAI <-> Anthropic format conversion logic
|
||||
├── types.go # Request/response struct types
|
||||
├── config.yaml # Default configuration file
|
||||
├── go.mod
|
||||
└── go.sum
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
See LICENSE file for details.
|
||||
Loading…
Add table
Add a link
Reference in a new issue