# ProxyAPI

**Repository Path**: uchenily/proxy-api

## Basic Information

- **Project Name**: ProxyAPI
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ProxyAPI

轻量级 API 代理服务，将 OpenAI、Anthropic Claude、OpenAI Responses 三种请求格式统一转换为 OpenAI 兼容上游接口调用。Codex CLI 和 Claude Code 可直接通过此代理访问任意 OpenAI 兼容后端。

## 支持的请求格式

| 客户端格式 | 端点 | 方向 |
|---|---|---|
| OpenAI Chat Completions | `POST /v1/chat/completions` | 透传，仅重写 model 字段 |
| Anthropic Claude Messages | `POST /v1/messages` | 请求/响应双向转换 |
| OpenAI Responses | `POST /v1/responses` | 请求/响应双向转换 |
| Codex CLI | `POST /backend-api/codex/responses` | 同 Responses 格式 |

三种格式均支持流式（SSE）和非流式响应。

## 架构

```
cmd/server/main.go          入口：gin 服务器、CORS、优雅关闭
internal/cfg/cfg.go         配置：host/port + upstreams（base-url, api-key, models）
internal/proxy/proxy.go     核心代理：HTTP 转发 + 格式转换（Claude↔OpenAI, Responses↔OpenAI）
internal/api/api.go         路由处理 + SSE 流式状态机
```

请求流程：

```
客户端 (OpenAI/Claude/Responses 格式)
  → ProxyAPI 格式检测 & 转换
  → OpenAI 兼容上游
  → ProxyAPI 反向转换
  → 客户端
```

## 端点一览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/` | 服务信息 |
| GET | `/healthz` | 健康检查 |
| GET | `/v1/models` | 模型列表 |
| POST | `/v1/chat/completions` | OpenAI Chat Completions |
| POST | `/v1/messages` | Claude Messages |
| POST | `/v1/messages/count_tokens` | Claude token 计数（返回占位值） |
| POST | `/v1/responses` | OpenAI Responses（流式） |
| POST | `/v1/responses/compact` | OpenAI Responses（非流式） |
| POST | `/backend-api/codex/responses` | Codex CLI 别名 |
| POST | `/backend-api/codex/responses/compact` | Codex CLI 别名（非流式） |

## 格式转换细节

### Claude → OpenAI

请求转换：
- `system`（字符串或内容块数组）→ `system` role message
- `content` 内容块数组 → OpenAI 多模态格式（text / image_url / tool_result）
- `tools` → OpenAI function tools（`input_schema` → `parameters`）
- `stop_sequences` → `stop`
- `max_tokens` / `temperature` / `top_p` 直接映射

响应转换（非流式）：
- `choices[0].message` → Claude `content` blocks（text + tool_use）
- `finish_reason: stop` → `stop_reason: end_turn`
- `finish_reason: tool_calls` → `stop_reason: tool_use`
- `usage` → `input_tokens` / `output_tokens`

流式转换（SSE 事件映射）：
- `delta.role` → `message_start` + `content_block_start`
- `delta.content` → `content_block_delta`（text_delta）
- `delta.tool_calls` → `content_block_start`（tool_use）+ `content_block_delta`（input_json_delta）
- `finish_reason` → `content_block_stop` + `message_delta` + `message_stop`

### Responses → OpenAI

请求转换：
- `instructions` → `system` role message
- `input`（字符串或消息数组）→ `messages`
- `tools`（function 类型）→ OpenAI function tools
- `max_output_tokens` → `max_tokens`

响应转换（非流式）：
- `choices[0].message.content` → `output` 中的 `message` + `output_text`
- `tool_calls` → `function_call` 输出项
- `usage` 直接映射

流式转换（SSE 事件映射）：
- `delta.role` → `response.created` + `output_item.added` + `content_part.added`
- `delta.content` → `output_text.delta`
- `delta.tool_calls` → `output_item.added` + `function_call_arguments.delta`
- `finish_reason` → `content_part.done` + `output_item.done` + `response.completed`

## 配置

配置文件为 YAML 格式，仅需提供上游地址、API Key 和模型列表：

```yaml
host: "0.0.0.0"
port: 8080

# 可选：为代理设置访问密钥
# api-keys:
#   - "sk-your-proxy-key"

upstreams:
  - base-url: "https://api.openai.com"
    api-key: "sk-xxxxxxxxxxxxxxxx"
    models:
      - "gpt-4o"
      - "gpt-4o-mini"

  - base-url: "https://your-provider.example.com/v1"
    api-key: "sk-xxxxxx"
    models:
      - "gpt-5.5"
```

### 配置项说明

| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `host` | 否 | `0.0.0.0` | 监听地址 |
| `port` | 否 | `8080` | 监听端口 |
| `api-keys` | 否 | 无 | 代理访问密钥列表，为空则不鉴权 |
| `upstreams` | 是 | — | 上游服务列表 |
| `upstreams[].base-url` | 是 | — | 上游 OpenAI 兼容接口地址 |
| `upstreams[].api-key` | 否 | — | 上游 API Key |
| `upstreams[].models` | 是 | — | 该上游支持的模型名列表 |

模型名会同时用于路由（决定请求发往哪个上游）和请求体中的 `model` 字段。如果上游返回的 `model` 字段与请求不一致，代理会自动重写。

## 快速开始

```bash
# 构建
go build -o proxyapi ./cmd/server/

# 复制并编辑配置
cp config.example.yaml config.yaml
# 编辑 config.yaml，填入真实的 base-url、api-key、models

# 启动
./proxyapi -config config.yaml

# 测试
curl --noproxy '*' http://localhost:8080/healthz
```

## 许可证

MIT