API_KEYS_FOR_COLLEAGUE.md

A/B Test Predictor API - Integration Guide for Backend

API Endpoint

https://nitish-spz-abtestpredictorv2.hf.space

Available Endpoints

1. Auto-Categorization Prediction

Endpoint: /call/predict_with_auto_categorization Method: POST Description: Automatically categorizes images and predicts A/B test winner

Request Format:

{
  "data": [
    {
      "path": "uploaded_control_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_control_image_path",
      "orig_name": "control.jpg",
      "size": 123456,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    {
      "path": "uploaded_variant_image_path", 
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_variant_image_path",
      "orig_name": "variant.jpg",
      "size": 789012,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    }
  ]
}

Response Format:

{
  "predictionResults": {
    "probability": "0.041",
    "modelConfidence": "75.5%",
    "trainingDataSamples": 477,
    "totalPredictions": 53,
    "correctPredictions": 40,
    "totalWinPrediction": 24,
    "totalLosePrediction": 29
  },
  "autoDetectedCategories": {
    "businessModel": "SaaS",
    "customerType": "B2B", 
    "conversionType": "High-Intent Lead Gen",
    "industry": "B2B Software & Tech",
    "pageType": "Conversion"
  },
  "detectedPattern": {
    "pattern": "Double Column Form",
    "description": "The variant implements a 'Double Column Form' modification"
  },
  "processingInfo": {
    "totalProcessingTime": "32.36s",
    "aiCategorization": "Perplexity Sonar Reasoning Pro",
    "patternDetection": "Gemini Pro Vision", 
    "confidenceSource": "B2B Software & Tech | Conversion",
    "totalPatternsAnalyzed": 359
  }
}

2. Manual Categorization Prediction

Endpoint: /call/predict_single Method: POST Description: Predicts A/B test winner with manually provided categories

Request Format:

{
  "data": [
    {
      "path": "uploaded_control_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_control_image_path",
      "orig_name": "control.jpg",
      "size": 123456,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    {
      "path": "uploaded_variant_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_variant_image_path", 
      "orig_name": "variant.jpg",
      "size": 789012,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    "E-Commerce",
    "B2C", 
    "Direct Purchase",
    "Retail & E-commerce",
    "Conversion"
  ]
}

Response Format:

{
  "probability": "0.987",
  "modelConfidence": "82.3%",
  "trainingDataSamples": 1205,
  "totalPredictions": 120,
  "correctPredictions": 98,
  "totalWinsPrediction": 67,
  "totalLosePrediction": 53
}

File Upload Process

Step 1: Upload Images

Endpoint: /upload Method: POST Content-Type: multipart/form-data

import requests

# Upload control image
with open('control.jpg', 'rb') as f:
    files = {'files': f}
    response = requests.post('https://nitish-spz-abtestpredictorv2.hf.space/upload', files=files)
    control_path = response.json()[0]

# Upload variant image  
with open('variant.jpg', 'rb') as f:
    files = {'files': f}
    response = requests.post('https://nitish-spz-abtestpredictorv2.hf.space/upload', files=files)
    variant_path = response.json()[0]

Step 2: Make Prediction Request

import requests

# Prepare FileData objects
control_file_data = {
    "path": control_path,
    "url": f"https://nitish-spz-abtestpredictorv2.hf.space/file={control_path}",
    "orig_name": "control.jpg",
    "size": 123456,
    "mime_type": "image/jpeg",
    "meta": { "_type": "gradio.FileData" }
}

variant_file_data = {
    "path": variant_path,
    "url": f"https://nitish-spz-abtestpredictorv2.hf.space/file={variant_path}",
    "orig_name": "variant.jpg", 
    "size": 789012,
    "mime_type": "image/jpeg",
    "meta": { "_type": "gradio.FileData" }
}

# Make prediction request
response = requests.post(
    'https://nitish-spz-abtestpredictorv2.hf.space/call/predict_with_auto_categorization',
    json={"data": [control_file_data, variant_file_data]}
)

result = response.json()

Response Field Descriptions

Prediction Results

• probability: Float between 0-1 (probability of variant winning). Values > 0.5 mean variant wins, < 0.5 mean control wins
• modelConfidence: Percentage confidence based on historical data
• trainingDataSamples: Number of training samples used for confidence calculation
• totalPredictions: Total number of historical predictions in this category
• correctPredictions: Number of correct predictions in historical data
• totalWinPrediction: Number of times variant won in historical data
• totalLosePrediction: Number of times control won in historical data

Auto-Detected Categories

• businessModel: "E-Commerce", "SaaS", "Lead Generation", "Other*"
• customerType: "B2B", "B2C", "Both", "Other*"
• conversionType: "Direct Purchase", "High-Intent Lead Gen", "Info/Content Lead Gen", "Location Search", "Non-Profit/Community", "Other Conversion"
• industry: 14 categories including "B2B Software & Tech", "Retail & E-commerce", etc.
• pageType: "Awareness & Discovery", "Consideration & Evaluation", "Conversion", "Internal & Navigation", "Post-Conversion & Other"

Detected Pattern

• pattern: A/B test pattern name (e.g., "Button", "Form Over UI", "Hero Changes")
• description: Human-readable description of the pattern

Processing Info

• totalProcessingTime: Time taken for prediction (typically 20-40 seconds)
• aiCategorization: AI service used for categorization
• patternDetection: AI service used for pattern detection
• confidenceSource: Data source for confidence scores
• totalPatternsAnalyzed: Number of patterns in the detection database

Error Handling

Common Error Responses

{
  "error": "Prediction failed: [error message]",
  "modelConfidence": "50.0%",
  "trainingDataSamples": 0,
  "totalPredictions": 0,
  "correctPredictions": 0,
  "totalWinPrediction": 0,
  "totalLosePrediction": 0
}

HTTP Status Codes

• 200: Success
• 400: Bad request (invalid parameters)
• 500: Internal server error
• 503: Service unavailable (GPU quota exceeded)

Rate Limits

• Free tier: Limited concurrent requests
• Processing time: 20-40 seconds per prediction
• GPU duration: 50-60 seconds maximum

Example Integration (Python)

import requests
import time

class ABTestPredictor:
    def __init__(self):
        self.base_url = "https://nitish-spz-abtestpredictorv2.hf.space"
    
    def predict(self, control_image_path, variant_image_path):
        # Step 1: Upload images
        control_path = self._upload_image(control_image_path)
        variant_path = self._upload_image(variant_image_path)
        
        # Step 2: Make prediction
        return self._make_prediction(control_path, variant_path)
    
    def _upload_image(self, image_path):
        with open(image_path, 'rb') as f:
            files = {'files': f}
            response = requests.post(f"{self.base_url}/upload", files=files)
            return response.json()[0]
    
    def _make_prediction(self, control_path, variant_path):
        control_data = self._create_file_data(control_path, "control.jpg")
        variant_data = self._create_file_data(variant_path, "variant.jpg")
        
        response = requests.post(
            f"{self.base_url}/call/predict_with_auto_categorization",
            json={"data": [control_data, variant_data]}
        )
        
        return response.json()
    
    def _create_file_data(self, path, orig_name):
        return {
            "path": path,
            "url": f"{self.base_url}/file={path}",
            "orig_name": orig_name,
            "size": 0,  # Optional
            "mime_type": "image/jpeg",
            "meta": { "_type": "gradio.FileData" }
        }

# Usage
predictor = ABTestPredictor()
result = predictor.predict("control.jpg", "variant.jpg")

# Get prediction results
prob = float(result['predictionResults']['probability'])
winner = "VARIANT WINS" if prob > 0.5 else "CONTROL WINS"

print(f"Winner: {winner}")
print(f"Probability: {prob}")
print(f"Confidence: {result['predictionResults']['modelConfidence']}")
print(f"Accuracy: {result['predictionResults']['correctPredictions']}/{result['predictionResults']['totalPredictions']}")

Notes

• Images are automatically deleted after processing
• Maximum image size: 10MB
• Supported formats: JPEG, PNG, WebP
• Processing time varies based on image complexity and server load