How to get started

Our API proxy service helps you reduce costs and improve response times for your AI API calls by implementing intelligent caching. When you make identical requests, our service returns cached responses instead of making new API calls, saving you money and time.

Features

Request caching for identical prompts
Support for multiple AI providers (OpenAI and Anthropic)
Automatic token counting and cost estimation
Usage logging and statistics
Transparent cache hit reporting

Authentication

To use the proxy service, you'll need:

An API key from our service
Your provider API key (OpenAI or Anthropic)

Making Requests

Endpoint

HTTP

POST /api/proxy

Request Format

JSON

{
  "apiKey": "your-shousai-api-key",
  "providerKey": "your-provider-api-key",
  "noCache": "true | false (optional, default: false)",
  "model": "model-name",
  "messages": [
    {
      "role": "user | assistant",
      "content": "Your message here"
    }
  ]
}

The noCache parameter is optional and defaults to false. If set to true, the response will not be cached. Please use this flag if you are experiencing issues with caching or if you want to bypass the cache. This could be the case if your prompt includes phrases like: "What happened yesterday?" where the question is the same but the response will obviously differ from day to day. We do not take responsibility for any misuse of this feature.

Supported Models

Model	model-name
GPT-4o	gpt-4o
GPT-4o Mini	gpt-4o-mini
GPT-4 (Turbo)	gpt-4-turbo
GPT-4	gpt-4
GPT-4 32K	gpt-4-32k
GPT-3.5 Turbo	gpt-3.5-turbo
GPT-3.5 Turbo Instruct	gpt-3.5-turbo-instruct
Claude 3 Opus	claude-3-opus-20240229
Claude 3.5 Sonnet	claude-3-5-sonnet-20241022

Code Examples

JavaScript Examples

Using fetch

JavaScript

const response = await fetch('https://shousai.co.uk/api/v1/proxy', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        apiKey: 'your-shousai-api-key",',
        providerKey: 'your-provider-api-key',
        model: 'gpt-4',
        messages: [
            {
                role: 'user',
                content: 'Hello, how are you?'
            }
        ]
    })
});

const data = await response.json();

Using Axios

JavaScript

const response = await axios.post('https://shousai.co.uk/api/v1/proxy', {
    apiKey: 'your-shousai-api-key",',
    providerKey: 'your-provider-api-key',
    model: 'gpt-4',
    messages: [
        {
            role: 'user',
            content: 'Hello, how are you?'
        }
    ]
});

Python Examples

Using requests

Python

import requests

def make_ai_request(prompt: str):
    url = "https://shousai.co.uk/api/v1/proxy"
    
    payload = {
        "apiKey": "your-shousai-api-key",
        "providerKey": "your-provider-api-key",
        "model": "gpt-4",
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    }
    
    response = requests.post(url, json=payload)
    response.raise_for_status()  # Raises exception for 4XX/5XX status codes
    
    return response.json()

# Example usage
try:
    result = make_ai_request("What is the capital of France?")
    print(f"Response: {result['choices'][0]['message']['content']}")
    print(f"Cost: ${result["usage"]["estimated_cost"]}")
    print(f"Cached: {result['usage']['cached']}")
except requests.exceptions.RequestException as e:
    print(f"Error making request: {e}")

Using aiohttp (Async)

Python

import aiohttp
import asyncio

async def make_async_ai_request(prompt: str):
    url = "https://shousai.co.uk/api/v1/proxy"
    
    payload = {
        "apiKey": "your-shousai-api-key",
        "providerKey": "your-provider-api-key",
        "model": "claude-3-opus-20240229",
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json=payload) as response:
            if response.status >= 400:
                error_data = await response.json()
                raise Exception(f"API error: {error_data}")
            
            return await response.json()

# Example usage
async def main():
    try:
        result = await make_async_ai_request("What is the capital of France?")
        print(f"Response: {result['choices'][0]['message']['content']}")
        print(f"Cost: ${result["usage"]["estimated_cost"]}")
        print(f"Cached: {result['usage']['cached']}")
    except Exception as e:
        print(f"Error: {e}")

asyncio.run(main())

Error Handling Example

Python

import requests
from typing import Dict, Any

class AIProxyError(Exception):
    """Custom exception for AI Proxy errors"""
    pass

def make_ai_request_with_retry(prompt: str, max_retries: int = 3) -> Dict[str, Any]:
    """
    Make an AI request with retry logic and proper error handling
    """
    url = "https://shousai.co.uk/api/v1/proxy"
    
    payload = {
        "apiKey": "your-shousai-api-key",
        "providerKey": "your-provider-api-key",
        "model": "gpt-4",
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    }
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=10)
            
            if response.status_code == 401:
                raise AIProxyError("Invalid API key")
            elif response.status_code == 400:
                error_data = response.json()
                raise AIProxyError(f"Invalid request: {error_data['details']}")
            elif response.status_code >= 500:
                if attempt == max_retries - 1:
                    raise AIProxyError("Server error after max retries")
                continue  # Try again
                
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise AIProxyError("Request timed out after max retries")
        except requests.exceptions.RequestException as e:
            raise AIProxyError(f"Network error: {str(e)}")
            
    raise AIProxyError("Max retries exceeded")

# Example usage with error handling
try:
    result = make_ai_request_with_retry("What is the capital of France?")
    print(f"Response: {result['choices'][0]['message']['content']}")
    print(f"Cost: ${result["usage"]["estimated_cost"]}")
except AIProxyError as e:
    print(f"AI Proxy error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Error Handling

The service returns standard HTTP status codes:

200: Successful request
400: Invalid request data
401: Invalid API key or user not found
500: Internal server error

Caching Behavior

Responses are cached based on the exact match of messages, model, and provider
Cache hits are indicated by cached: true in the response
Cached responses have zero cost (estimated_cost: "0.0000 (cached)")
Cache timeouts are set to 2000ms for reads and writes

Best Practices

Consistent Message Format: Keep message format consistent to maximize cache hits
Error Handling: Implement proper error handling in your application
Timeout Handling: Account for potential cache timeouts in your implementation
Cost Monitoring: Track usage costs through the provided metrics
API Key Security: Store your API keys securely and never expose them in client-side code

Support

For additional support or questions, please contact our support team or visit our documentation portal.