# API Reference

<div align="center">

**🌍 Language / 语言**

[🇺🇸 English](./API-Reference.en.md) | [🇨🇳 中文](./API-Reference.md)

</div>

AI Proxy Worker provides a simple yet powerful RESTful API that is fully compatible with OpenAI's Chat Completions API format, allowing you to easily integrate it into existing projects.

> **Current Support**: DeepSeek API (v1.0)  
> **Future Plans**: Multi-AI service provider support including OpenAI, Claude, Gemini (v2.0)

## 🌐 Basic Information

### Base URL
```
https://your-worker.workers.dev
```

### Authentication
```http
Authorization: Bearer YOUR_PROXY_KEY
```

### Content-Type
```http
Content-Type: application/json
```

## 📚 API Endpoints

### 1. Health Check

Check service status and connectivity.

**Request:**
```http
GET /
```

**Response:**
```json
{
  "status": "ok",
  "service": "AI Proxy Worker",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
```

**Example:**
```bash
curl https://your-worker.workers.dev/
```

### 2. Chat Completions

Interact with AI models, supports both streaming and non-streaming responses.

**Request:**
```http
POST /chat
```

**Headers:**
```http
Authorization: Bearer YOUR_PROXY_KEY
Content-Type: application/json
Accept: application/json  # Non-streaming
Accept: text/event-stream # Streaming
```

**Request Body:**
```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful AI assistant."
    },
    {
      "role": "user", 
      "content": "Hello!"
    }
  ],
  "stream": false,
  "max_tokens": 2048
}
```

## 🤖 Supported Models

### deepseek-chat
- **Use Case**: General conversation and text generation
- **Architecture**: Based on DeepSeek-V3 architecture
- **Features**: Suitable for daily conversations, content creation, text understanding
- **Context Length**: 64K tokens
- **Recommended Scenarios**: General text generation, conversational applications

### deepseek-reasoner  
- **Use Case**: Complex reasoning and logical thinking
- **Architecture**: Based on DeepSeek-R1 architecture
- **Features**: Math problems, logical reasoning, code analysis, complex reasoning
- **Context Length**: 64K tokens
- **Recommended Scenarios**: Tasks requiring deep thinking

> **Note**: Model specifications and capabilities may change with DeepSeek updates. Check [DeepSeek Official Documentation](https://platform.deepseek.com/) for latest information.

## 📝 Request Parameters

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | string | Model name to use |
| `messages` | array | Array of conversation messages |

### Optional Parameters

| Parameter | Type | Default | Description | Support Status |
|-----------|------|---------|-------------|----------------|
| `stream` | boolean | false | Enable streaming response | ✅ Fully supported |
| `max_tokens` | number | - | Maximum tokens to generate | ✅ Fully supported |
| `temperature` | number | 1.0 | Control randomness (0-2) | ⚠️ May not work |
| `top_p` | number | 1.0 | Nucleus sampling parameter (0-1) | ⚠️ May not work |
| `frequency_penalty` | number | 0 | Frequency penalty (-2 to 2) | ⚠️ May not work |
| `presence_penalty` | number | 0 | Presence penalty (-2 to 2) | ⚠️ May not work |
| `stop` | array/string | null | Stop sequences | ✅ Supported |
| `seed` | number | null | Random seed for consistent output | ✅ Supported |

> **Note**: Parameters marked "⚠️ May not work" may not have the expected effect due to DeepSeek API limitations. We recommend primarily using `stream`, `max_tokens`, `stop`, and `seed` parameters.

### Messages Format

Each message object contains:

```json
{
  "role": "user|assistant|system",
  "content": "Message content"
}
```

**Role Descriptions:**
- `system`: System prompt, defines AI behavior
- `user`: User input
- `assistant`: AI response

## 📤 Response Format

### Non-streaming Response

**Success Response:**
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm DeepSeek, happy to help you."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 15,
    "total_tokens": 35
  }
}
```

### Streaming Response

When `stream: true` is enabled, response is in Server-Sent Events (SSE) format:

```
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"deepseek-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

## ⚠️ **Important: Parameter Compatibility**

According to DeepSeek official documentation, the following parameters may not work as expected:

- `temperature` - May be ignored, DeepSeek API may use fixed temperature values
- `top_p` - May not work
- `frequency_penalty` - May not work  
- `presence_penalty` - May not work

**Recommended Approach:**
- Primarily use `model`, `messages`, `max_tokens`, `stream`, and `stop` parameters
- To control generation behavior, use `system` messages to guide the model
- You can try these parameters during testing, but don't rely on their effects

**Example - Recommended Request Format:**
```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system", 
      "content": "Please answer concisely, don't be overly detailed."
    },
    {
      "role": "user",
      "content": "What is artificial intelligence?"
    }
  ],
  "max_tokens": 500,
  "stream": false
}
```

## 🔧 Complete Examples

### cURL Examples

**Non-streaming Request:**
```bash
curl -X POST https://your-worker.workers.dev/chat \
  -H "Authorization: Bearer YOUR_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {
        "role": "system",
        "content": "You are a professional programming assistant."
      },
      {
        "role": "user",
        "content": "Please write a Python quicksort function for me."
      }
    ],
    "max_tokens": 1000
  }'
```

**Streaming Request:**
```bash
curl -X POST https://your-worker.workers.dev/chat \
  -H "Authorization: Bearer YOUR_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "user", "content": "Write a poem about programming"}
    ],
    "stream": true
  }'
```

### JavaScript Examples

**Basic Call:**
```javascript
async function callAI(message) {
  const response = await fetch('https://your-worker.workers.dev/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_PROXY_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'deepseek-chat',
      messages: [
        { role: 'user', content: message }
      ],
      max_tokens: 1000
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  return data.choices[0].message.content;
}

// Usage example
callAI('Hello, please introduce yourself')
  .then(result => console.log(result))
  .catch(error => console.error('Error:', error));
```

**Streaming Call:**
```javascript
async function streamAI(message, onChunk) {
  const response = await fetch('https://your-worker.workers.dev/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_PROXY_KEY',
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
    },
    body: JSON.stringify({
      model: 'deepseek-chat',
      messages: [{ role: 'user', content: message }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n');

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') return;

          try {
            const parsed = JSON.parse(data);
            const content = parsed.choices[0]?.delta?.content;
            if (content) {
              onChunk(content);
            }
          } catch (e) {
            // Ignore parsing errors
          }
        }
      }
    }
  } finally {
    reader.releaseLock();
  }
}

// Usage example
streamAI('Write a story about AI', (chunk) => {
  process.stdout.write(chunk); // Real-time output
});
```

### Python Examples

**Basic Call:**
```python
import requests
import json

def call_ai(message, model="deepseek-chat"):
    url = "https://your-worker.workers.dev/chat"
    headers = {
        "Authorization": "Bearer YOUR_PROXY_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": model,
        "messages": [
            {"role": "user", "content": message}
        ],
        "max_tokens": 1000
    }
    
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    
    data = response.json()
    return data["choices"][0]["message"]["content"]

# Usage example
result = call_ai("Please explain what machine learning is")
print(result)
```

**Streaming Call:**
```python
import requests
import json

def stream_ai(message, model="deepseek-chat"):
    url = "https://your-worker.workers.dev/chat"
    headers = {
        "Authorization": "Bearer YOUR_PROXY_KEY",
        "Content-Type": "application/json",
        "Accept": "text/event-stream"
    }
    
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": message}],
        "stream": True
    }
    
    response = requests.post(url, headers=headers, json=payload, stream=True)
    response.raise_for_status()
    
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = line[6:]
                if data == '[DONE]':
                    break
                
                try:
                    parsed = json.loads(data)
                    content = parsed["choices"][0]["delta"].get("content")
                    if content:
                        print(content, end='', flush=True)
                except json.JSONDecodeError:
                    continue

# Usage example
stream_ai("Write a poem about spring")
```

### iOS Swift Examples

```swift
import Foundation

class AIProxyClient {
    private let baseURL = "https://your-worker.workers.dev"
    private let apiKey = "YOUR_PROXY_KEY"
    
    func chatCompletion(
        model: String = "deepseek-chat",
        messages: [[String: String]],
        maxTokens: Int = 1000
    ) async throws -> String {
        
        guard let url = URL(string: "\(baseURL)/chat") else {
            throw APIError.invalidURL
        }
        
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        let requestBody: [String: Any] = [
            "model": model,
            "messages": messages,
            "max_tokens": maxTokens
        ]
        
        request.httpBody = try JSONSerialization.data(withJSONObject: requestBody)
        
        let (data, response) = try await URLSession.shared.data(for: request)
        
        guard let httpResponse = response as? HTTPURLResponse,
              httpResponse.statusCode == 200 else {
            throw APIError.requestFailed
        }
        
        let result = try JSONSerialization.jsonObject(with: data) as! [String: Any]
        let choices = result["choices"] as! [[String: Any]]
        let message = choices[0]["message"] as! [String: Any]
        
        return message["content"] as! String
    }
}

enum APIError: Error {
    case invalidURL
    case requestFailed
}

// Usage example
let client = AIProxyClient()

Task {
    do {
        let response = try await client.chatCompletion(
            messages: [
                ["role": "user", "content": "Hello, please introduce yourself"]
            ]
        )
        print(response)
    } catch {
        print("Error: \(error)")
    }
}
```

## ❌ Error Handling

### Error Response Format

All errors return a unified JSON format:

```json
{
  "error": "error_type",
  "details": "Detailed error message",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
```

### Common Error Codes

| HTTP Status | Error Type | Description |
|-------------|------------|-------------|
| 400 | `invalid_request` | Request format error |
| 401 | `unauthorized` | Authentication failed |
| 404 | `not_found` | Endpoint not found |
| 413 | `payload_too_large` | Request body too large |
| 500 | `internal_error` | Internal server error |
| 502 | `upstream_error` | Upstream API error |
| 504 | `timeout` | Request timeout |

### Error Handling Example

```javascript
async function handleAPICall(message) {
  try {
    const response = await fetch('https://your-worker.workers.dev/chat', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_PROXY_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'deepseek-chat',
        messages: [{ role: 'user', content: message }]
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error (${response.status}): ${errorData.error} - ${errorData.details}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API call failed:', error.message);
    
    // Handle different error types
    if (error.message.includes('401')) {
      console.log('Please check if API key is correct');
    } else if (error.message.includes('504')) {
      console.log('Request timeout, please try again later');
    } else if (error.message.includes('413')) {
      console.log('Request content too long, please reduce input');
    }
    
    throw error;
  }
}
```

## 🔒 Security Best Practices

### 1. API Key Management
- Never hardcode `PROXY_KEY` in client code
- Use environment variables or secure configuration management
- Rotate keys regularly

### 2. Request Validation
- Validate user input to prevent injection attacks
- Limit request frequency to prevent abuse
- Log and monitor abnormal requests

### 3. Content Filtering
```javascript
function sanitizeInput(content) {
  // Remove potentially malicious content
  return content
    .replace(/<script[^>]*>.*?<\/script>/gi, '')
    .replace(/<[^>]*>/g, '')
    .trim();
}

const sanitizedMessage = sanitizeInput(userInput);
```

## 📊 Usage Limits

### Cloudflare Workers Limits
- **Request Timeout**: 30 seconds (configurable)
- **Request Body Size**: 1MB (configurable)
- **Concurrent Requests**: 1000/minute (free tier)
- **CPU Time**: 10ms (free tier)

### DeepSeek API Limits
- **Rate Limits**: Based on your DeepSeek account plan
- **Context Length**: 64K tokens
- **Concurrent Connections**: Based on account type

## 🚀 Performance Optimization Tips

### 1. Caching Strategy
```javascript
// Simple memory cache example
const cache = new Map();

function getCachedResponse(key) {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < 300000) { // 5-minute cache
    return cached.data;
  }
  return null;
}
```

### 2. Request Optimization
- Set reasonable `max_tokens` to avoid unnecessarily long responses
- Use appropriate `temperature` values
- Use faster models for simple tasks

### 3. Streaming Response
- Use streaming response for long text generation to improve user experience
- Implement appropriate error retry mechanisms
- Consider implementing request cancellation

---

**Need More Help?** 👉 [View Usage Examples](./Examples.en) | [Troubleshooting](./Troubleshooting.en)