01

Overview

The AI Proxy Backend is a comprehensive API gateway built with Next.js, providing unified access to Google Gemini AI models.

Unified AI Interface

Single API endpoint for text, image, and vision tasks.

JWT Authentication

Clerk-based verification with secure user context.

Quota Enforcement

Tier-based limits and real-time usage tracking.

Gamified Systems

XP, levels, and achievements integrated via Convex.

02

Authentication

All protected endpoints require a valid Clerk JWT token in the Authorization header.

# Format
Authorization: Bearer <jwt_token>
# Optional Header
x-app-id: prompt-pal
03

Rate Limiting

To ensure system stability, we enforce sliding window rate limits based on IP address.

Default Limit
30 RPM
Burst Capacity
10 REQ
04

AI Proxy Endpoints

POST/api/ai/proxy

Unified endpoint for multiple AI task types.

Request Body
{
  "type": "text" | "image" | "compare",
  "input": {
    "prompt": "Your content here..."
  }
}
POST/api/analyzer/evaluate-images

Detailed scoring of generated vs target images.

Request Body
{
  "input": {
    "userImageUrl": "...",
    "expectedImageUrl": "..."
  }
}
05

User Data Endpoints

GET/api/user/usage

Retrieve current user quota and tier limits.

GET/api/user/game-state

Fetch level progression and gamification state.

GET/api/v1/user/sync

Full profile and progress synchronization.

06

Analytics & System

POST/api/analytics/event

Log custom user behavior and application events.

GET/api/health

Check infrastructure and sub-system status.