---
title: AI API
tags: [api, ai, reference]
---

# AI API

Endpoints live under `/api/ai/*`. The router is [`backend/src/services/ai/aiRoutes.ts`](../../backend/src/services/ai/aiRoutes.ts) and delegates to [`aiController`](../../backend/src/services/ai/aiController.ts), 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:**
```ts
{
  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:**
```json
{
  "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:**
```ts
{
  text: string;
  purpose?: "moderation" | "sentiment" | "keywords" | "summary";   // default "moderation"
  language?: "en" | "fa" | "ar";
}
```
**Response 200 (moderation example):**
```json
{
  "success": true,
  "data": {
    "purpose": "moderation",
    "flagged": false,
    "categories": { "hate": 0.001, "harassment": 0.0 },
    "suggestion": null
  }
}
```
**Response 200 (sentiment example):**
```json
{ "success": true, "data": { "purpose": "sentiment", "score": 0.62, "label": "positive" } }
```

### POST /api/ai/translate

**Description:** Translate `text` between languages.
**Auth required:** No
**Request body:**
```ts
{
  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:**
```ts
{
  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)

## Related

- [[AI Integration]]
- [[Moderation Pipeline]]
- [[Rate Limiting]]