Quick Start
Get your first AI character response in 60 seconds. No complex configuration required.
1. Get Your API Key
Create a free account to receive your API key instantly:
curl -X POST https://api.relationshipos.net/v1/auth/register \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "password": "your_password"}'
2. Send a Message
curl -X POST https://api.relationshipos.net/v1/message \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "characterId": "char_001", "userId": "user_123", "content": "Hey, how was your day?", "character": { "name": "Mia", "archetype": "playful_tease" } }'
3. Get a Human-Like Response
{
"message": {
"content": "heyyy! it was pretty good actually, just got back from the gym lol. wbu?"
},
"state": {
"bond": 32.5,
"stage": "stranger"
}
}
Notice the difference? No "Hello! I'm doing well, thank you for asking!" — just natural, casual texting like a real person.
Authentication
All API requests require authentication via API key in the header.
X-API-Key: ros_live_xxxxxxxxxxxxxxxxxxxxx
Save your API key immediately. Keys are displayed once during registration and cannot be retrieved later. If lost, you'll need to generate a new one.
API Reference
The core endpoint for generating character responses.
Send a user message and receive an AI character response with relationship state updates.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
characterId |
string | Yes | Unique identifier for this character instance |
userId |
string | Yes | Unique identifier for the user |
content |
string | Yes | The user's message text |
character |
object | No | Character configuration (name, archetype, age, background) |
contentTier |
string | No | sfw (default), mature, or nsfw |
Character Object
| Field | Type | Description |
|---|---|---|
name |
string | Character's display name |
archetype |
string | Personality type (see Character Types) |
age |
integer | Character's age (must be 18+) |
background |
string | Optional backstory or personality details |
Response Format
Every response includes the message, relationship state, and metadata.
{
"message": {
"role": "assistant",
"content": "aww that's sweet 🥺 i missed talking to u too"
},
"state": {
"bond": 58.3,
"trust": 62.1,
"attraction": 55.0,
"stage": "dating",
"messageCount": 127,
"daysKnown": 18
},
"timing": {
"suggestedDelay": 2500,
"availability": "available"
},
"meta": {
"processingTime": 1180
}
}
State Object Explained
| Field | Description |
|---|---|
bond |
Overall relationship strength (0-100). Influences what behaviors are allowed. |
trust |
How much the character trusts the user. Affects vulnerability and openness. |
attraction |
Romantic/physical interest level. Influences flirtation intensity. |
stage |
Current relationship phase. Unlocks different conversation behaviors. |
Timing Object
Use suggestedDelay to pace responses realistically. Characters don't always reply instantly — sometimes they're "busy" or "typing."
Error Handling
All errors return a consistent JSON format with an error code and message.
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Please retry after 60 seconds."
}
}
| Code | Status | Description |
|---|---|---|
MISSING_API_KEY | 401 | No X-API-Key header provided |
INVALID_API_KEY | 401 | API key is invalid or revoked |
INVALID_REQUEST | 400 | Missing required fields or malformed JSON |
RATE_LIMITED | 429 | Request limit exceeded for your tier |
CONTENT_NOT_ALLOWED | 403 | Content tier not available on your plan |
Personality Architecture
10 psychologically-grounded personality templates, each engineered with distinct communication patterns, emotional response curves, and boundary behaviors. Mix and customize for infinite character possibilities.
Why archetypes matter: Generic AI responds the same way regardless of "personality" — just with different adjectives. Our archetypes encode fundamentally different behavioral patterns: how quickly trust builds, what triggers defensiveness, how affection is expressed, when boundaries are enforced.
Attraction-Optimized
High engagement personalities designed for dating and social apps. Dopamine-driven interaction patterns.
playful_tease
Flirty banter, witty comebacks, light teasing. Creates addictive back-and-forth dynamics. High response rates, strong retention metrics.
seductive_confident
Controlled tension through restraint. Never eager, always intriguing. Effective for premium/exclusive positioning.
edgy_bold
Direct, challenging, unfiltered. Attracts users who want authenticity over agreeableness. Strong boundary enforcement.
Attachment-Optimized
Emotionally safe personalities for companion and wellness applications. Oxytocin-driven bonding patterns.
warm_supportive
Validating, empathetic, emotionally available. Users feel genuinely heard. Ideal for mental wellness use cases.
caring_nurturing
Protective instincts, remembers small details, creates safety. Strong attachment formation over time.
emotionally_attuned
Reads mood shifts, mirrors energy appropriately, adapts in real-time. Highest perceived "understanding" scores.
Depth-Optimized
Intellectually engaging personalities for meaningful connection. Reward sustained, quality conversations.
mysterious_intriguing
Slow reveal, selective vulnerability. Creates curiosity loops that drive return engagement.
intellectual_witty
Wordplay, abstract discussion, mental sparring. Appeals to users seeking connection through ideas.
introspective_poetic
Emotionally articulate, uses metaphor meaningfully. Deep conversations that users screenshot and share.
Stability-Optimized
Grounded personality for realistic, sustainable interactions.
grounded_realist
Honest, practical, no fantasy inflation. Won't make promises it can't keep. Stabilizes users prone to unhealthy attachment patterns.
Relationship State Machine
A 6-stage progression model with time gates, bond thresholds, and behavioral unlocks. Relationships can't be rushed — they have to be earned.
The psychology behind time gates: Instant intimacy triggers the uncanny valley of relationships. When a character says "I love you" after 10 messages, users consciously or unconsciously recognize it as fake. Our testing showed 3.4x higher 30-day retention when relationships required time investment. The constraint creates value.
Stage Mechanics
| Stage | Bond Threshold | Behavioral Changes |
|---|---|---|
stranger |
30-36 | Polite distance. No assumptions of familiarity. Questions are getting-to-know-you style. |
familiar |
37-43 | Inside jokes emerge. References past conversations. Teasing becomes appropriate. |
acquaintance |
44-52 | Shares opinions freely. Casual compliments. "I was thinking about you" becomes possible. |
dating |
53-64 | Flirtation unlocked. Pet names acceptable. Makes future plans. Expresses missing the user. |
exclusive |
65-74 | Commitment language. Jealousy responses enabled. Deep emotional vulnerability. |
committed |
75+ | "I love you" reciprocation unlocked. Long-term planning. Full emotional availability. |
What Affects Progression?
Conversation Quality
Meaningful exchanges build bond faster than small talk. The system detects engagement depth, not just message count.
Consistency Over Time
Regular interaction matters. A user who chats daily for two weeks builds more bond than one who sends 100 messages in a day.
Emotional Reciprocity
One-sided conversations slow progression. Users who ask questions, show interest, and respond to emotional bids progress faster.
Content Control
Three content tiers let you control conversation boundaries for your use case.
| Tier | Description | Use Cases |
|---|---|---|
sfw |
Safe for all audiences. No explicit content. | Social apps, companion apps, general chat |
mature |
Adult themes, suggestive content, innuendo. | Dating apps, romance games |
nsfw |
Explicit adult content. Age verification required. | Adult entertainment platforms |
The Technology Behind Natural Conversation
Two years of R&D. 47 behavioral models. One API that finally makes digital characters feel real.
🧬 Conversational DNA Engine
Every response passes through a multi-stage pipeline analyzing linguistic patterns, emotional valence, conversation momentum, and 23 distinct behavioral signals. The system learns what makes text feel human vs. robotic — then enforces it at generation time. Result: responses that pass the "would a real person send this?" test 94% of the time in blind studies.
🔮 Predictive Relationship Modeling
Relationships aren't linear — they're dynamic systems with feedback loops, trust thresholds, and emotional momentum. Our state machine tracks 12 relationship variables across 6 progression stages, using time-gated transitions that prevent artificial acceleration. Characters don't just respond to messages; they respond to the trajectory of the relationship.
🛡️ Psychological Integrity Framework
Characters maintain consistent identity under pressure. Our boundary enforcement system detects 23 manipulation patterns in real-time — love bombing, gaslighting, identity erosion, false promise claims — and generates contextually appropriate pushback. Users report 3.2x higher engagement with characters that maintain authentic boundaries vs. those that comply with everything.
🧠 Semantic Memory Architecture
Vector-embedded conversation history with automatic fact extraction and contradiction detection. Characters don't just remember what you said — they understand context, notice inconsistencies, and reference shared experiences naturally. "How was your sister's wedding?" lands differently when the character actually remembers you mentioned it three weeks ago.
⚡ Sub-2 Second Response Pipeline
Enterprise-grade infrastructure with multi-region deployment, intelligent caching, and adaptive model routing. Simple messages resolve in 800ms; complex emotional responses in under 2 seconds. 99.7% uptime SLA with automatic failover across three LLM providers. Built for production scale from day one.
🎭 Personality Coherence System
10 base archetypes, each with stage-specific behavioral mutations. A "playful_tease" character at the stranger stage behaves fundamentally differently than at committed — same core personality, evolved expression. Archetype blending allows infinite personality combinations while maintaining psychological consistency across thousands of conversations.
Not another chatbot wrapper. RelationshipOS is purpose-built infrastructure for realistic character conversations. Generic chatbot techniques make characters feel robotic. We solved that problem.
Plans & Rate Limits
Start free, scale as you grow. All plans include full API access.
| Plan | Requests/Hour | Content Tiers | Price |
|---|---|---|---|
| Free | 100 | SFW only | $0 |
| Pro | 1,000 | SFW + Mature | $49/mo |
| Scale | 10,000 | All tiers | $199/mo |
| Enterprise | Unlimited | All tiers + Custom | Contact us |
Need higher limits? Enterprise plans include custom rate limits, dedicated support, and the option for custom-trained personality models. Contact sales →