AI API

Endpoints live under /api/ai/*. The router is backend/src/services/ai/aiRoutes.ts and delegates to aiController, which wraps the OpenAI SDK.

The AI service is intentionally generic — there are no resource-specific endpoints (no "generate product description" route). Instead, four general-purpose endpoints (generate, analyze, translate, assist) accept a purpose field that the controller maps to a system prompt template. The frontend uses these for:

Product description generation (purpose: description)
Content moderation (purpose: moderation on /analyze)
Product recommendations (purpose: recommend on /generate)
In-app helper (/assist)

Note: the router currently exposes these endpoints without authenticateToken. Front-end usage assumes the user is logged in. If you need to add auth, do it in the router. OpenAI cost-protection and rate-limiting are handled inside aiController via the Redis-backed rateLimitService.

Endpoints

POST /api/ai/generate

Description: Generate free-form text. Used for product descriptions, marketing copy, recommendation rationales. Auth required: No (intended for authenticated frontends) Request body:

{
  prompt: string;
  purpose?: "description" | "recommend" | "summary" | "generic";   // default "generic"
  context?: Record<string, unknown>;       // injected into the system prompt
  maxTokens?: number;                      // default 512, capped server-side
  temperature?: number;                    // 0..2, default 0.7
  language?: "en" | "fa" | "ar";           // default "en"
}

Response 200:

{
  "success": true,
  "data": {
    "text": "...",
    "model": "gpt-4o-mini",
    "tokensUsed": { "prompt": 120, "completion": 340, "total": 460 }
  }
}

Errors: 400 invalid params, 429 quota exceeded, 502 upstream OpenAI error.

POST /api/ai/analyze

Description: Analyze a piece of text. Used for moderation (flag offensive content), sentiment, keyword extraction. Auth required: No Request body:

{
  text: string;
  purpose?: "moderation" | "sentiment" | "keywords" | "summary";   // default "moderation"
  language?: "en" | "fa" | "ar";
}

Response 200 (moderation example):

{
  "success": true,
  "data": {
    "purpose": "moderation",
    "flagged": false,
    "categories": { "hate": 0.001, "harassment": 0.0 },
    "suggestion": null
  }
}

Response 200 (sentiment example):

{ "success": true, "data": { "purpose": "sentiment", "score": 0.62, "label": "positive" } }

POST /api/ai/translate

Description: Translate text between languages. Auth required: No Request body:

{
  text: string;
  from?: "en" | "fa" | "ar" | "auto";    // default "auto"
  to: "en" | "fa" | "ar";
}

Response 200: { success, data: { translated: "...", detectedFrom: "en" } }

POST /api/ai/assist

Description: In-app conversational assistant. Maintains short-term context per call (the client passes prior turns explicitly). Auth required: No Request body:

{
  messages: Array<{ role: "user" | "assistant" | "system"; content: string }>;
  purpose?: "help" | "search" | "navigate";    // tunes the system prompt
  context?: { userId?: string; route?: string; locale?: string };
}

Response 200: { success, data: { reply: { role: "assistant", content: "..." }, tokensUsed } }

Configuration

The OpenAI client is configured via env:

OPENAI_API_KEY (required)
OPENAI_MODEL (default gpt-4o-mini)
OPENAI_BASE_URL (override for self-hosted proxies)

3.8 KiB Raw Blame History