119 lines
3.8 KiB
Markdown
119 lines
3.8 KiB
Markdown
---
|
|
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]]
|