---
title: 'AI Agents Overview'
description: 'Overview of WinkSocial AI Agents API with Multi-Language Support'
---

# AI Agents API

The WinkSocial AI Agents API provides intelligent features from the production backend, backed by self-hosted open-model routing and shared user-context services. Ollama handles local text and embedding work, while ThunderCompute provides GPU capacity for larger open models, image, and video workflows. These endpoints cover bio optimization, match prediction, chat suggestions, experience pricing, support chat, and support-video requests.

## 🚀 Quick Start

### Base URL
```
https://agents.joinwink.app/api/v1/ai-agents
```

`https://api.joinwink.app/api/v1/ai-agents` serves the same controller set. The separate `apps/platform-agent` service is exposed to browsers through the web proxy at `/api/agent`, not under `/api/v1/ai-agents`.

### Authentication
AI Agents API uses the same authentication as the main API:

```bash
Authorization: Bearer YOUR_API_KEY
```

## 🌍 Multi-Language Support

All AI agents now support **35+ languages** based on user profile preferences:

- **English (en)** - Default language
- **Spanish (es)** - Español
- **French (fr)** - Français  
- **Swahili (sw)** - Kiswahili
- **Arabic (ar)** - العربية
- **Chinese (zh)** - 中文
- **Hindi (hi)** - हिन्दी
- **Portuguese (pt)** - Português
- **Russian (ru)** - Русский
- **Japanese (ja)** - 日本語
- **Korean (ko)** - 한국어
- **German (de)** - Deutsch
- **Italian (it)** - Italiano
- And 20+ more languages...

### Language-Aware Responses
- Agents automatically detect user's preferred language
- All text responses (bios, chat suggestions, explanations) are in the user's language
- JSON structure remains consistent across all languages
- Fallback to English if language preference is not specified

## 🤖 Available Agents

### 1. Bio Optimization Agent
- **Endpoint**: `/bio/rewrite` and `/bio/optimize`
- **Purpose**: Improve user profile descriptions with language-specific optimization
- **Input**: Current bio text, user interests, target audience, tone, max length, **language**
- **Output**: Optimized bio, headline, conversation prompts, improvement suggestions

### 2. Match Prediction Agent
- **Endpoint**: `/match/predict`
- **Purpose**: Predict compatibility between users with localized reasoning
- **Input**: User profiles, interests, location, **language**
- **Output**: Match score, compatibility reasoning, common interests, confidence

### 3. Chat Response Agent
- **Endpoint**: `/chat/response`
- **Purpose**: Generate engaging, language-appropriate chat responses
- **Input**: User message, context, tone, **language**
- **Output**: Response text, suggestions, tone analysis, next steps

### 4. Experience Pricing Agent
- **Endpoint**: `/experiences/pricing`
- **Purpose**: Optimize pricing for premium experiences with localized explanations
- **Input**: Experience details, amenities, target audience, **language**
- **Output**: Base price, final price, pricing reasoning, confidence

### 5. Support Chat Agent ⭐ NEW
- **Endpoint**: `/support/chat`
- **Purpose**: Comprehensive AI-powered support for users and admins
- **Input**: User query, context, user type, platform, **language**
- **Output**: Detailed guidance, next steps, related features, suggested actions

### 6. Support Video Agent ⭐ NEW
- **Endpoint**: `/support-video/request`
- **Purpose**: AI-powered video support request management
- **Input**: User ID, reason, priority, platform, language, callback times, timezone
- **Output**: Request ID, queue position, estimated wait time, status message

## 📊 Response Format

The examples below show the high-level contract shape used by the public docs. Treat the per-endpoint reference pages as the source of truth when integrating.

### Standard Response Structure
```json
{
  "success": true,
  "data": {
    "result": "AI-generated content in user's preferred language",
    "confidence": 0.85,
    "metadata": {
      "model_version": "3.0.0",
      "processing_time": "0.5s",
      "tokens_used": 150,
      "language": "es"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### Structured Response Examples

#### Bio Optimization Response
```json
{
  "headline": "Un título atractivo y llamativo",
  "bio": "Una bio reescrita y atractiva que muestra personalidad",
  "prompts": ["Conversación iniciador 1", "Conversación iniciador 2"],
  "improvements": ["Sugerencia 1", "Sugerencia 2"],
  "confidence": 0.8
}
```

#### Chat Response
```json
{
  "response": "¡Hola! Me encantaría conocer más sobre ti",
  "suggestions": ["Pregunta sobre su día", "Comparte algo interesante"],
  "tone": "amigable",
  "nextSteps": ["Mantén la conversación fluyendo", "Muestra interés genuino"]
}
```

## 🔧 Error Handling

### Common Error Codes

| Code | Error | Description |
|------|-------|-------------|
| 400 | `invalid_input` | Malformed or invalid request data |
| 401 | `unauthorized` | Missing or invalid API key |
| 429 | `rate_limit_exceeded` | Too many requests |
| 500 | `internal_error` | AI service error |
| 503 | `service_unavailable` | AI service temporarily unavailable |

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "invalid_input",
    "message": "Invalid bio text provided",
    "details": "Bio must be between 10 and 500 characters",
    "language": "en"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

## 📈 Rate Limits

### AI Agents Specific Limits

| Plan | Requests/Hour | Concurrent Requests |
|------|---------------|-------------------|
| Standard | 100 | 5 |
| Premium | 500 | 20 |
| Enterprise | 2000 | 100 |

### Rate Limit Headers

```http
X-AI-RateLimit-Limit: 100
X-AI-RateLimit-Remaining: 99
X-AI-RateLimit-Reset: 1640995200
```

## 🧪 Testing

### Health Check Endpoint

```bash
curl -X GET "https://agents.joinwink.app/api/v1/ai-agents/health" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Multi-Language Test Examples

#### Spanish Bio Optimization
```bash
curl -X POST "https://agents.joinwink.app/api/v1/ai-agents/bio/rewrite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentBio": "Me gusta viajar y conocer gente nueva",
    "interests": ["viajes", "música", "deportes"],
    "targetAudience": "personas aventureras",
    "tone": "amigable",
    "maxLength": 200,
    "language": "es"
  }'
```

#### French Chat Response
```bash
curl -X POST "https://agents.joinwink.app/api/v1/ai-agents/chat/response" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Salut! Comment allez-vous?",
    "userId": "user123",
    "context": ["dating", "first_message"],
    "tone": "friendly",
    "language": "fr"
  }'
```

## 🔗 Integration Examples

### JavaScript/TypeScript with Language Support

```typescript
class WinkSocialAIAgents {
  private baseURL = 'https://agents.joinwink.app/api/v1/ai-agents';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async optimizeBio(bio: string, interests: string[], language: string = 'en'): Promise<any> {
    const response = await fetch(`${this.baseURL}/bio/rewrite`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ 
        currentBio: bio, 
        interests, 
        targetAudience: 'dating',
        tone: 'friendly',
        maxLength: 200,
        language 
      })
    });

    return response.json();
  }

  async predictMatch(user1: any, user2: any, language: string = 'en'): Promise<any> {
    const response = await fetch(`${this.baseURL}/match/predict`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ 
        userProfile: user1.profile,
        potentialMatchProfile: user2.profile,
        userInterests: user1.interests,
        matchInterests: user2.interests,
        location: user1.location,
        language 
      })
    });

    return response.json();
  }

  async getSupportChat(query: string, context: string, language: string = 'en'): Promise<any> {
    const response = await fetch(`${this.baseURL}/support/chat`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ 
        userId: 'user123',
        query,
        context,
        userType: 'user',
        platform: 'web',
        language,
        tags: ['support', 'general']
      })
    });

    return response.json();
  }
}
```

### React Native with Language Support

```javascript
class WinkSocialAIAgents {
  constructor(apiKey) {
    this.baseURL = 'https://agents.joinwink.app/api/v1/ai-agents';
    this.apiKey = apiKey;
  }

  async getChatSuggestions(matchContext, language = 'en') {
    const response = await fetch(`${this.baseURL}/chat/response`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        message: matchContext.message,
        userId: matchContext.userId,
        context: matchContext.context,
        tone: matchContext.tone,
        language
      })
    });

    return response.json();
  }

  async getExperiencePricing(experienceData, language = 'en') {
    const response = await fetch(`${this.baseURL}/experiences/pricing`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        experienceType: experienceData.type,
        location: experienceData.location,
        duration: experienceData.duration,
        amenities: experienceData.amenities,
        targetAudience: experienceData.audience,
        language
      })
    });

    return response.json();
  }
}
```

## 📚 SDK Support

### Official SDKs

- **JavaScript SDK**: `@winksocial/js-sdk`
- **React Native SDK**: `@winksocial/react-native-sdk`
- **Admin Panel SDK**: `@winksocial/admin-sdk`

### Installation

```bash
# JavaScript/TypeScript
pnpm add @winksocial/js-sdk

# React Native
pnpm add @winksocial/react-native-sdk

# Admin Panel
pnpm add @winksocial/admin-sdk
```

## 🚀 Best Practices

### 1. Language Handling
- **Always Pass Language**: Include user's language preference in all requests
- **Fallback Strategy**: Handle cases where language is not specified
- **Consistent Experience**: Maintain language consistency across user sessions

### 2. Request Optimization
- **Batch Requests**: Combine multiple AI operations when possible
- **Cache Results**: Store AI responses for similar inputs and languages
- **Async Processing**: Use non-blocking calls for better UX

### 3. Error Handling
- **Retry Logic**: Implement exponential backoff for retries
- **Fallback Content**: Provide default content when AI fails
- **User Feedback**: Inform users when AI features are unavailable

### 4. Performance
- **Request Throttling**: Limit concurrent AI requests
- **Response Caching**: Cache AI responses for repeated queries
- **Background Processing**: Process AI requests in background

## 🔮 Current Features

### Implemented AI Capabilities
- **Multi-Language Support**: 35+ languages with localized responses
- **Structured JSON Responses**: Consistent data format across all agents
- **Self-hosted open-model inference**: internal model catalog selects Ollama or ThunderCompute-hosted open models
- **CAF-ready agent mesh policy**: routes by workflow, modality, health, latency, and model capability without commercial inference fallbacks
- **Real-time Processing**: Fast response times with streaming support
- **Comprehensive Support**: AI-powered help system for users and admins

### Advanced Features
- **Context-Aware Responses**: Agents understand user context and history
- **Personalized Suggestions**: Tailored recommendations based on user data
- **Quality Assurance**: Confidence scores and fallback mechanisms
- **Scalable Architecture**: Cloud-native deployment with auto-scaling

## 📞 Support

Need help with AI Agents?

- **Email**: hello@joinwink.app
- **Documentation**: This guide
- **API Status**: Check health endpoint
- **Community**: Developer forums
- **AI Support**: Use the Support Chat Agent directly

---

Next: Explore specific AI agent endpoints:
- [Bio Optimization](/api-reference/ai-agents/bio-optimization)
- [Match Prediction](/api-reference/ai-agents/match-prediction)
- [Chat Response](/api-reference/ai-agents/chat-response)
- [Experience Pricing](/api-reference/ai-agents/experience-pricing)
- [Support Chat](/api-reference/ai-agents/support-chat)
