Content
# Cursor2API
[English](README_EN.md) | English
A Go service that converts Cursor Web into an OpenAI `chat/completions` compatible API.
[](https://golang.org)
[](https://polyformproject.org/licenses/noncommercial/1.0.0/)
## ✨ Features
- 🔄 **API Compatibility**: Compatible with OpenAI `chat/completions` interface
- ⚡ **High Performance**: Low latency response
- 🔐 **Secure Authentication**: Supports API Key authentication
- 🌐 **Model Derivation**: Automatically exposes `*-thinking` models
- 🧰 **Tool Calls**: Supports `tools` / `tool_choice` / `tool_calls`
- 🛡️ **Error Handling**: Comprehensive error handling mechanism
- 📊 **Health Check**: Built-in health check interface
## 🖼️ Screenshots
## 🤖 Supported Models
- **Google Gemini**: `gemini-3-flash`
- **Auto-derived thinking models**: `gemini-3-flash-thinking`
## 🚀 Quick Start
### Requirements
- Go 1.24+
- Node.js 18+ (for JavaScript execution)
### Local Running
#### Method 1: Direct Run (Recommended for development)
**Linux/macOS**:
```bash
git clone https://github.com/libaxuan/cursor2api-go.git
cd cursor2api-go
chmod +x start.sh
./start.sh
```
**Windows**:
```batch
# Double-click to run or execute in cmd
start-go.bat
# Or in Git Bash / Windows Terminal
./start-go-utf8.bat
```
#### Method 2: Manual Compilation and Run
```bash
# Clone the project
git clone https://github.com/libaxuan/cursor2api-go.git
cd cursor2api-go
# Download dependencies
go mod tidy
# Compile
go build -o cursor2api-go
# Run
./cursor2api-go
```
#### Method 3: Using go run
```bash
git clone https://github.com/libaxuan/cursor2api-go.git
cd cursor2api-go
go run main.go
```
The service will start at `http://localhost:8002`
## 🚀 Server Deployment
### Docker Deployment
1. **Build Image**:
```bash
# Build image
docker build -t cursor2api-go .
```
2. **Run Container**:
```bash
# Run container (recommended)
docker run -d \
--name cursor2api-go \
--restart unless-stopped \
-p 8002:8002 \
-e API_KEY=your-secret-key \
-e DEBUG=false \
cursor2api-go
# Or run with default configuration
docker run -d --name cursor2api-go --restart unless-stopped -p 8002:8002 cursor2api-go
```
### Docker Compose Deployment (Recommended for production)
1. **Using docker-compose.yml**:
```bash
# Start service
docker-compose up -d
# Stop service
docker-compose down
# View logs
docker-compose logs -f
```
2. **Custom Configuration**:
Modify environment variables in `docker-compose.yml` to meet your needs:
- Modify `API_KEY` to a secure key
- Adjust `MODELS`, `TIMEOUT`, etc. as needed
- Change exposed port
### System Service Deployment (Linux)
1. **Compile and move binary file**:
```bash
go build -o cursor2api-go
sudo mv cursor2api-go /usr/local/bin/
sudo chmod +x /usr/local/bin/cursor2api-go
```
2. **Create system service file** `/etc/systemd/system/cursor2api-go.service`:
```ini
[Unit]
Description=Cursor2API Service
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user/cursor2api-go
ExecStart=/usr/local/bin/cursor2api-go
Restart=always
Environment=API_KEY=your-secret-key
Environment=PORT=8002
[Install]
WantedBy=multi-user.target
```
3. **Start Service**:
```bash
# Reload systemd configuration
sudo systemctl daemon-reload
# Enable boot auto-start
sudo systemctl enable cursor2api-go
# Start service
sudo systemctl start cursor2api-go
# View status
sudo systemctl status cursor2api-go
```
## 📡 API Usage
### Get Model List
```bash
curl -H "Authorization: Bearer 0000" http://localhost:8002/v1/models
```
### Non-streaming Chat
```bash
curl -X POST http://localhost:8002/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0000" \
-d '{
"model": "gemini-3-flash",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": false
}'
```
### Streaming Chat
```bash
curl -X POST http://localhost:8002/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0000" \
-d '{
"model": "gemini-3-flash",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'
```
### Request with Tools
```bash
curl -X POST http://localhost:8002/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0000" \
-d '{
"model": "gemini-3-flash",
"messages": [{"role": "user", "content": "Help me check Beijing weather"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get real-time weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
}
]
}'
```
### `-thinking` Model
```bash
curl -X POST http://localhost:8002/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0000" \
-d '{
"model": "gemini-3-flash-thinking",
"messages": [{"role": "user", "content": "Think before deciding whether to use tools"}],
"tools": [
{
"type": "function",
"function": {
"name": "lookup",
"parameters": {
"type": "object",
"properties": {
"q": {"type": "string"}
},
"required": ["q"]
}
}
}
],
"stream": true
}'
```
### Using in Third-party Applications
In any application that supports custom OpenAI API (e.g., ChatGPT Next Web, Lobe Chat, etc.):
1. **API Address**: `http://localhost:8002`
2. **API Key**: `0000` (or custom)
3. **Model**: Select one of the supported models; base models will automatically have corresponding `-thinking` versions
## ⚙️ Configuration
### Environment Variables
| Variable | Default Value | Description |
| --- | --- | --- |
| `PORT` | `8002` | Server port |
| `DEBUG` | `false` | Debug mode (enables detailed logs and route information) |
| `API_KEY` | `0000` | API authentication key |
| `MODELS` | `gemini-3-flash` | Base model list (comma-separated), service will automatically append corresponding `-thinking` public models |
| `TIMEOUT` | `60` | Request timeout (seconds) |
| `KILO_TOOL_STRICT` | `false` | Kilo Code compatibility switch: when request provides `tools` and `tool_choice=auto`, it will be promoted to "must call at least once" |
### Debug Mode
By default, the service runs in concise mode. To enable detailed logs:
**Method 1**: Modify `.env` file
```bash
DEBUG=true
```
**Method 2**: Use environment variable
```bash
DEBUG=true ./cursor2api-go
```
Debug mode will display:
- Detailed GIN route information
- Detailed logs for each request
- x-is-human token information
- Browser fingerprint configuration
### Troubleshooting
Encounter issues? Check the **[Troubleshooting Guide](TROUBLESHOOTING.md)** for solutions to common problems, including:
- 403 Access Denied error
- Token acquisition failure
- Connection timeout
- Cloudflare interception
## 🧩 Compatibility with Kilo Code / Agent Orchestrator
Some orchestrators will enforce models to produce tool calls when "tools" are provided, otherwise reporting errors like `MODEL_NO_TOOLS_USED`. To improve compatibility:
- **Recommendation**: Enable `KILO_TOOL_STRICT=true` in `.env`
- **Non-streaming remedy**: When request provides `tools` and is judged as "must use tools" (`tool_choice=required/specify function`, or enable `KILO_TOOL_STRICT`), if no `tool_calls` are produced in this round, the service will automatically **retry once** (only non-streaming; streaming does not retry)
### Windows Startup Script
The project provides two Windows startup scripts:
- **`start-go.bat`** (Recommended): GBK encoding, perfectly compatible with Windows cmd.exe
- **`start-go-utf8.bat`**: UTF-8 encoding, suitable for Git Bash, PowerShell, Windows Terminal
Both scripts have the same functionality, only different display styles. If encountering garbled characters, use `start-go.bat`.
## 🧪 Development
### Run Tests
```bash
# Run existing tests
go test ./...
```
### Build Project
```bash
# Build executable file
go build -o cursor2api-go
# Cross-compile (e.g., Linux)
GOOS=linux GOARCH=amd64 go build -o cursor2api-go-linux
```
## 📁 Project Structure
```
cursor2api-go/
├── main.go # Main program entry (Go version)
├── config/ # Configuration management (Go version)
├── handlers/ # HTTP handlers (Go version)
├── services/ # Business service layer (Go version)
├── models/ # Data models (Go version)
├── utils/ # Utility functions (Go version)
├── middleware/ # Middleware (Go version)
├── jscode/ # JavaScript code (Go version)
├── static/ # Static files (Go version)
├── start.sh # Linux/macOS startup script
├── start-go.bat # Windows startup script (GBK)
├── start-go-utf8.bat # Windows startup script (UTF-8)
└── README.md # Project documentation
```
## 🤝 Contribution Guide
Welcome to contribute code! Please follow these steps:
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'feat: Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Code Style
- Follow [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- Use `gofmt` to format code
- Use `go vet` to check code
- Commit messages follow [Conventional Commits](https://conventionalcommits.org/) specification
## 📄 License
This project uses the [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) license.
No commercial use. See [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
Please comply with the usage terms of related services when using this project.
⭐ If this project helps you, give us a Star!
