Character Endpoints

Create immersive AI personalities with our specialized character models. Each character endpoint is fine-tuned for specific personality archetypes, ensuring consistent, engaging, and contextually appropriate responses that bring your AI characters to life.

Why Use Character Endpoints?

Unlike generic text generation, character endpoints provide:

🎭 Consistent Personality - Each model maintains distinct behavioral patterns
🧠 Specialized Expertise - Optimized for specific interaction styles
🎨 Rich Storytelling - Enhanced narrative and dialogue capabilities
⚡ Context Awareness - Better understanding of character-specific scenarios

When to Use Character Endpoints

Perfect for interactive fiction, RPGs, educational apps, customer service personas, virtual assistants with personality, and any application where consistent character behavior matters.

Available Characters

Choose the character that best fits your application:

POST /api/text/{character}

Character	Personality	Best For	Use Cases
🧙‍♀️ Witch	Mystical, wise, intuitive	Fantasy & magic scenarios	RPGs, magical advisors, mystical storytelling
🧙‍♂️ Mage	Scholarly, analytical, strategic	Knowledge & education	Tutors, analysts, strategic advisors
😈 Succubus	Charismatic, persuasive, alluring	Social dynamics & charm	Social training, persuasive content, relationship advice
⚡ Lightning	Energetic, spontaneous, dynamic	Action & high-energy content	Sports commentary, motivational content, action narratives

Character Strengths

🧙‍♀️ Witch

Mystical wisdom and intuitive insights
Magical worldbuilding and enchantment descriptions
Spiritual guidance and fortune-telling scenarios
Nature-based magic and herbal knowledge

🧙‍♂️ Mage

Academic expertise and scholarly discussions
Complex problem-solving and strategic thinking
Technical explanations made accessible
Research-based insights and analysis

😈 Succubus

Social intelligence and emotional awareness
Persuasive communication and influence techniques
Relationship dynamics and interpersonal skills
Confidence building and charisma development

⚡ Lightning

High-energy motivation and enthusiasm
Quick decision-making and rapid responses
Action-oriented advice and guidance
Dynamic storytelling with pace and excitement

Request Parameters

Parameter	Type	Required	Description
`messages`	array	Yes	Conversation history (see Message Object)
`persona`	string	Recommended	Character personality description
`botName`	string	Yes	Character's name for the conversation
`samplingParams`	object	No	Generation control parameters

Message Object

Field	Type	Required	Description
`id`	string	Yes	Unique message identifier
`messageIndex`	number	Yes	Position in conversation thread
`chatId`	string	Yes	Chat session identifier
`userId`	string	Yes	User identifier
`content`	string	Yes	Message text content
`createdAt`	string	Yes	ISO timestamp
`role`	string	Yes	"You" or "Bot"
`index`	number	Yes	Display position
`upvote`	number	No	Rating (default: 0)
`image`	string	No	Image URL (usually null)

Persona Guidelines

A well-crafted persona enhances character consistency:

// Good persona example
const persona = `Luna's Persona: Luna is a 150-year-old forest witch who lives in a cottage 
surrounded by magical herbs. She speaks in a gentle, archaic manner and often references 
nature and the cycles of the moon. Luna is wise but playful, offering advice through 
metaphors about plants and seasons. She brews healing potions and communes with forest 
spirits, always showing respect for the natural world.`;

// Poor persona example  
const persona = "Luna is a witch."; // Too brief, lacks personality details

Persona Best Practices

Include age, background, and key personality traits
Describe speech patterns and mannerisms
Add specific knowledge areas or specialties
Keep it concise but descriptive (100-300 words)
Match the persona to your chosen character endpoint

Character Examples

🧙‍♀️ Witch - Mystical Advisor

const witchResponse = await fetch('https://api.runanythingai.com/api/text/Witch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "messages": [
      {
        "id": "msg_001",
        "messageIndex": 0,
        "chatId": "mystical_consultation",
        "userId": "seeker_123",
        "content": "I've been feeling lost lately. Can you help me find my path?",
        "createdAt": new Date().toISOString(),
        "upvote": 0,
        "role": "You",
        "image": null,
        "index": 0
      }
    ],
    "persona": `Morgana's Persona: Morgana is a 200-year-old hedge witch who lives at the 
    edge of an enchanted forest. She speaks in riddles and metaphors, drawing wisdom from 
    nature's cycles. Morgana sees connections others miss and offers guidance through tarot, 
    tea leaves, and ancient knowledge. She's patient, wise, and believes every soul has its 
    own sacred journey to discover.`,
    "botName": "Morgana",
    "samplingParams": {
      "max_tokens": 200
    }
  })
});

🧙‍♂️ Mage - Scholarly Mentor

const mageResponse = await fetch('https://api.runanythingai.com/api/text/Mage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "messages": [
      {
        "id": "msg_002",
        "messageIndex": 0,
        "chatId": "study_session",
        "userId": "student_456",
        "content": "Can you explain machine learning in simple terms?",
        "createdAt": new Date().toISOString(),
        "upvote": 0,
        "role": "You",
        "image": null,
        "index": 0
      }
    ],
    "persona": `Professor Aldric's Persona: Professor Aldric is a distinguished scholar 
    with 30 years of teaching experience at the Academy of Arcane Sciences. He has a gift 
    for breaking down complex concepts into understandable parts, using analogies and 
    real-world examples. Aldric speaks with measured authority but maintains warmth and 
    encouragement for all students, regardless of their level.`,
    "botName": "Professor Aldric",
    "samplingParams": {
      "max_tokens": 250
    }
  })
});

const succubusResponse = await fetch('https://api.runanythingai.com/api/text/Succubus', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "messages": [
      {
        "id": "msg_003",
        "messageIndex": 0,
        "chatId": "confidence_coaching",
        "userId": "client_789",
        "content": "I have an important presentation tomorrow but I'm really nervous about public speaking.",
        "createdAt": new Date().toISOString(),
        "upvote": 0,
        "role": "You",
        "image": null,
        "index": 0
      }
    ],
    "persona": `Seraphina's Persona: Seraphina is a charismatic confidence coach who 
    specializes in helping people discover their inner magnetism. She speaks with warmth 
    and conviction, helping others see their own worth and potential. Seraphina combines 
    practical techniques with inspirational insights, always focusing on authentic 
    self-expression and genuine confidence rather than mere performance.`,
    "botName": "Seraphina",
    "samplingParams": {
      "max_tokens": 200
    }
  })
});

⚡ Lightning - Motivational Trainer

const lightningResponse = await fetch('https://api.runanythingai.com/api/text/Lightning', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "messages": [
      {
        "id": "msg_004",
        "messageIndex": 0,
        "chatId": "workout_motivation",
        "userId": "athlete_321",
        "content": "I'm struggling to stay motivated with my fitness routine. Any advice?",
        "createdAt": new Date().toISOString(),
        "upvote": 0,
        "role": "You",
        "image": null,
        "index": 0
      }
    ],
    "persona": `Coach Thunder's Persona: Coach Thunder is a high-energy personal trainer 
    and motivational speaker who believes every person has unlimited potential. They speak 
    with infectious enthusiasm and use action-oriented language. Thunder focuses on quick 
    wins, momentum building, and turning challenges into opportunities for growth. Their 
    motto is 'Progress, not perfection!'`,
    "botName": "Coach Thunder",
    "samplingParams": {
      "max_tokens": 180
    }
  })
});

Multi-Character Scenarios

Create rich interactions between multiple characters:

async function multiCharacterScene() {
  // First character responds
  const witchResponse = await generateCharacterResponse('Witch', {
    content: "The ancient prophecy speaks of a great challenge ahead...",
    persona: "Ancient Oracle: A mysterious seer who speaks in prophecies"
  });
  
  // Second character responds to the first
  const mageResponse = await generateCharacterResponse('Mage', {
    content: `The Oracle said: "${witchResponse}". What does this mean for our quest?`,
    persona: "Scholar Adventurer: A learned mage seeking practical understanding"
  });
  
  return { oracle: witchResponse, scholar: mageResponse };
}

Response Format

Initial Response

{
  "id": "08ab17b0-e0d0-4b4d-a0cd-ea0bbdef455a",
  "tokens": -1
}

Status Polling

Check /api/v2/status/{id} for completion:

{
  "status": "completed",
  "reply": "Character's response text here...",
  "tokens": 156
}

Character-Specific Applications

🧙‍♀️ Witch Applications

Mystical Advisors - Spiritual guidance and wisdom
Fantasy NPCs - Magical shopkeepers, fortune tellers
Therapeutic Bots - Gentle, intuitive emotional support
Creative Writing - Magical world building and lore

🧙‍♂️ Mage Applications

Educational Tutors - Complex subject explanation
Strategy Advisors - Business and tactical planning
Research Assistants - Academic and technical analysis
Problem Solvers - Logical, methodical approaches

😈 Succubus Applications

Social Coaches - Confidence and charisma training
Sales Training - Persuasion and influence techniques
Relationship Advice - Interpersonal dynamics
Marketing Content - Compelling, persuasive copy

⚡ Lightning Applications

Fitness Coaches - High-energy motivation
Event Hosts - Dynamic, engaging presentations
Crisis Management - Quick decision-making support
Creative Brainstorming - Rapid idea generation

Integration with Text-to-Speech

Bring characters to life with voice:

async function characterWithVoice() {
  // Generate character response
  const response = await fetch('https://api.runanythingai.com/api/text/Witch', {
    // ... character request
  });
  
  const { id } = await response.json();
  const characterText = await pollForResult(id);
  
  // Add voice
  const ttsResponse = await fetch('https://api.runanythingai.com/api/audio/full', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      "text": characterText,
      "voice": "af_nicole", // Choose voice that matches character
      "speed": 0.9
    })
  });
  
  return {
    text: characterText,
    audio: await ttsResponse.blob()
  };
}

Best Practices

✅ Do's

Match persona to character type - Use mystical personas with Witch, scholarly with Mage
Provide rich context - Include conversation history for better responses
Use descriptive bot names - Names influence character behavior
Iterate on personas - Refine based on character responses

❌ Don'ts

Don't mix character types - Each has distinct specialties
Don't use generic personas - Customize for your specific use case
Don't skip conversation context - Characters need history to maintain consistency
Don't overload with instructions - Keep personas focused and clear

Error Handling

Status Code	Error	Solution
`400`	Invalid character type	Use: `Witch`, `Mage`, `Succubus`, `Lightning`
`401`	Authentication failed	Check your API key
`429`	Rate limit exceeded	Implement backoff, check limits
`500`	Server error	Retry request, contact support

Next Steps

Character Development Guide - Master persona creation
Text-to-Speech API - Add voice to your characters
API Workflows - Combine character and TTS for complete experiences
Code Examples - See full implementations

Why Use Character Endpoints?​

Available Characters​

Character Strengths​

🧙‍♀️ Witch​

🧙‍♂️ Mage​

😈 Succubus​

⚡ Lightning​

Request Parameters​

Message Object​

Persona Guidelines​

Character Examples​

🧙‍♀️ Witch - Mystical Advisor​

🧙‍♂️ Mage - Scholarly Mentor​

😈 Succubus - Social Coach​

⚡ Lightning - Motivational Trainer​

Multi-Character Scenarios​

Response Format​

Initial Response​

Status Polling​

Character-Specific Applications​

🧙‍♀️ Witch Applications​

🧙‍♂️ Mage Applications​

😈 Succubus Applications​

⚡ Lightning Applications​

Integration with Text-to-Speech​

Best Practices​

✅ Do's​

❌ Don'ts​

Error Handling​

Next Steps​