​
Quick Decision Matrix

FactorSDKREST API
LanguageJavaScript/TypeScriptAny language
EnvironmentBrowser applicationsAny environment
Setup Time< 30 seconds2-5 minutes
Code Required3-5 lines15-30 lines
AuthenticationAutomatic token handlingManual header management
StreamingAsyncIterable patternManual SSE parsing
Event HandlingBuilt-in eventsCustom implementation
Conversation HistoryAutomatic managementManual tracking
Learning CurveMinimalModerate

​
Choose the SDK When…

Building Browser Applications

Perfect for web apps, SPAs, and browser-based tools

Want Rapid Development

Get started in minutes with minimal boilerplate code

Need Event-Driven Architecture

Built-in events for messages, images, and streaming

Building Conversational Interfaces

Automatic conversation history and turn management

​
SDK Advantages

✅ Minimal Setup: One import, one configuration object
✅ Automatic Authentication: Secure token handling with refresh
✅ Built-in Events: React to messages, images, and errors
✅ Conversation Management: Automatic history and context
✅ Streaming Made Easy: AsyncIterable pattern for real-time responses
✅ Image Generation: Automatic detection and generation
✅ TypeScript Support: Full type safety and autocomplete
✅ Error Handling: Specific error types for different scenarios

​
SDK Example

// Complete chat setup in 3 lines
import { AnimusClient } from 'animus-client';
const client = new AnimusClient({ tokenProviderUrl: 'your-auth-server' });
client.on('messageComplete', (data) => console.log('Friend:', data.content));
client.chat.send('Hey, how has your day been?');

​
Choose the REST API When…

Using Non-JavaScript Languages

Python, Java, C#, Go, PHP, Ruby, or any other language

Building Backend Services

Server-side applications, APIs, and microservices

Need Maximum Control

Custom request handling and response processing

Batch Processing

Processing large datasets or automated workflows

​
REST API Advantages

✅ Universal Language Support: Works with any programming language
✅ Maximum Flexibility: Full control over requests and responses
✅ Server-Side Integration: Perfect for backend services
✅ Existing Infrastructure: Integrate with current HTTP clients
✅ Batch Operations: Process multiple requests efficiently
✅ Custom Authentication: Implement your own auth patterns

​
REST API Example

# Python example with requests
import requests

response = requests.post('https://api.animusai.co/v3/chat/completions', 
  headers={'Authorization': 'Bearer your-api-key'},
  json={
    'model': 'vivian-llama3.1-70b-1.0-fp8',
    'messages': [{'role': 'user', 'content': 'Hello!'}]
  })

​
Use Case Scenarios

​
Perfect for SDK

🤖 Chatbot Interfaces 
// Natural conversation with automatic history
client.on('messageComplete', (data) => updateChatUI(data.content));
client.chat.send(userInput);
📱 Real-time Applications 
// Streaming responses with events
const stream = await client.chat.completions({ stream: true });
for await (const chunk of stream) {
  updateUI(chunk.choices[0].delta.content);
}
🎨 Creative Tools 
// Automatic image generation
client.on('imageGenerationComplete', (data) => displayImage(data.imageUrl));
client.chat.send('I need some inspiration today, could you create something beautiful?');
🔄 Interactive Experiences 
// Conversational turns with natural delays
const client = new AnimusClient({
  chat: {
    systemMessage: 'You are a caring companion.',
    autoTurn: true // Natural conversation flow
  }
});

​
Perfect for REST API

🤝 Chat Co-pilot with Response Selection 
# Generate multiple response options for human selection
response = requests.post(api_url, json={
    'model': 'vivian-llama3.1-70b-1.0-fp8',
    'messages': [{'role': 'user', 'content': user_message}],
    'n': 3,  # Generate 3 response options
    'temperature': 0.8  # Add variety between responses
})

# Extract all response options
response_options = [choice['message']['content'] for choice in response.json()['choices']]
# Present options to human for selection
best_response = human_select_best(response_options)
👁️ Video Categorization with Vision 
# Batch video analysis and categorization
video_batch = ['frame1.jpg', 'frame2.jpg', 'frame3.jpg']
for frame in video_batch:
    response = requests.post(api_url, json={
        'model': 'xavier-vision-1.0',
        'messages': [{
            'role': 'user',
            'content': [
                {'type': 'text', 'text': 'Categorize this video frame and provide a description'},
                {'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{encode_image(frame)}'}}
            ]
        }]
    })
    video_analysis.append(response.json())
💬 Conversation Analysis & Profiling 
# Analyze conversation patterns and build speaker profiles
conversation_history = load_chat_history(user_id)
analysis = requests.post(api_url, json={
    'model': 'vivian-llama3.1-70b-1.0-fp8',
    'messages': [{
        'role': 'user', 
        'content': f'Analyze this conversation and create personality profiles for both speakers: {conversation_history}'
    }]
})
speaker_profiles = analysis.json()['choices'][0]['message']['content']

​
Feature Comparison

​
Authentication

SDK Approach: 
// Automatic token management
const client = new AnimusClient({
  tokenProviderUrl: 'http://localhost:3001/token' // Your secure backend
});
// SDK handles token refresh automatically
REST API Approach: 
# Manual token management
headers = {'Authorization': f'Bearer {api_key}'}
response = requests.post(url, headers=headers, json=data)

​
Streaming

SDK Approach: 
// Clean AsyncIterable pattern
const stream = await client.chat.completions({ stream: true });
for await (const chunk of stream) {
  console.log(chunk.choices[0].delta.content);
}
REST API Approach: 
# Manual SSE parsing
response = requests.post(url, stream=True)
for line in response.iter_lines():
    if line.startswith(b'data: '):
        chunk = json.loads(line[6:])
        print(chunk['choices'][0]['delta']['content'])

​
Error Handling

SDK Approach: 
// Specific error types
try {
  // Event-driven approach
  client.chat.send('Hello');
  
  // Or use completions() for direct API calls
  const response = await client.chat.completions({
    messages: [{ role: 'user', content: 'Hello' }]
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle auth issues
  } else if (error instanceof ApiError) {
    // Handle API errors
  }
}
REST API Approach: 
# HTTP status code handling
try:
    response = requests.post(url, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        # Handle auth error
    elif e.response.status_code == 429:
        # Handle rate limit

​
Migration Paths

​
From REST API to SDK

If you’re currently using the REST API and want to migrate to the SDK:
  1. Set up authentication server (see SDK Quickstart)
  2. Replace HTTP calls with SDK methods
  3. Add event listeners for reactive UI updates
  4. Enable automatic features like conversation history

​
From SDK to REST API

If you need to migrate from SDK to REST API:
  1. Implement authentication header management
  2. Add streaming parsing for real-time responses
  3. Build conversation history tracking
  4. Handle errors with HTTP status codes

​
Decision Framework

Ask yourself these questions:
  1. What’s your primary language?
    • JavaScript/TypeScript → SDK
    • Other languages → REST API
  2. What’s your environment?
    • Browser application → SDK
    • Server/backend → REST API
  3. How complex is your use case?
    • Simple chat/conversation → SDK
    • Complex integrations → REST API
  4. Do you need real-time features?
    • Yes, with minimal code → SDK
    • Yes, with full control → REST API
  5. How quickly do you need to ship?
    • ASAP → SDK
    • Have time for custom implementation → REST API

​
Get Started

Ready to choose your path?

Start with SDK

Perfect for JavaScript/TypeScript browser applications

Start with REST API

Ideal for any language or server-side applications
Still unsure? Start with the SDK if you’re building a browser application with JavaScript/TypeScript. You can always switch to the REST API later if you need more control or different language support.