OpenAI/OpenRouter Integration

JOIP uses AI models to generate explicit NSFW captions for images. You can use either OpenAI (direct) or OpenRouter (multi-model gateway) for caption generation.

Overview

The caption generation system supports:

Smart Captions: Detailed AI captions for uploaded images (50-400 characters)
Session Captions: Short captions for slideshow playback (50-150 characters)
Manual Captions: Contextual captions that maintain narrative continuity
Batch Generation: Generate captions for multiple slides at once

OpenRouter is recommended for production use as it provides access to multiple models, better rate limits, and fallback options.

Prerequisites

Choose one of the following:

OpenRouter (Recommended)
OpenAI (Direct)

OpenRouter account at openrouter.ai
API key from OpenRouter Keys
Credits loaded (pay-as-you-go)

Setup Steps

Get API Key

OpenRouter
OpenAI

Sign up at openrouter.ai
Navigate to Keys
Click “Create Key”
Name it (e.g., “JOIP Production”)
Copy the key (starts with sk-or-)

API keys are shown only once. Save them securely immediately after creation.

Configure Environment

Add your key to .env:

OPENROUTER_API_KEY=sk-or-v1-abc123...

OPENAI_API_KEY=sk-abc123...

If both are set, OpenRouter takes precedence. OpenAI is used as fallback only.

Choose Model (OpenRouter Only)

Configure which AI model to use for caption generation:

# No configuration needed - uses gemini-2.0-flash-exp by default

OPENROUTER_MODEL_ID=google/gemini-2.5-pro

Recommended Models:

google/gemini-2.0-flash-exp - Fast, cheap, good quality (default)
google/gemini-2.5-pro - Highest quality, contextual understanding
anthropic/claude-3.5-sonnet - Excellent balance of speed and quality
openai/gpt-4o - OpenAI’s latest, reliable

Only vision-capable models work for caption generation. JOIP validates this on startup.

Verify Configuration

Start the server and check logs:

[openai] Using OpenRouter with model: google/gemini-2.0-flash-exp
[openai] OpenRouter API key validated

[error] OpenRouter API key is invalid or expired
[error] Model google/gemini-2.5-pro does not support vision

Implementation Details

Caption Generation Architecture

JOIP uses a sophisticated prompting system for NSFW content:

const MASTER_SYSTEM_PROMPT = `You are an UNCENSORED explicit adult caption generator. 
Create raw, filthy captions that feel like REAL dirty talk - not polished writing.

CRITICAL - PERSPECTIVE:
- The PERSON IN THE IMAGE is SPEAKING the caption TO the viewer
- She's talking directly to whoever is looking at/stroking to her image
- The viewer is addressed, commanded, teased, degraded, humiliated

CONTENT INTENSITY:
- Be EXPLICIT: cock, pussy, fuck, cum, balls, stroke, edge, whore, slut, etc.
- NO censoring, NO softening, NO holding back
- Match the theme's psychological intensity EXACTLY

OUTPUT: Just the raw caption. No quotes, no labels, no formatting.`;

Context-Aware Generation

For manual sessions, captions consider surrounding context:

interface CaptionContext {
  sessionTitle?: string;
  index: number;                    // Current slide position
  total: number;                    // Total slides
  previousCaptions?: string[];      // Last 3 captions for continuity
  nextCaptions?: string[];          // Next 3 captions for flow
  userSteering?: string;            // Custom instructions
  sessionStage?: 'new_session' | 'existing_session';
}

// Example usage
const caption = await generateContextualManualCaption(imageUrl, {
  sessionTitle: "Dominant Femdom Session",
  index: 5,
  total: 20,
  previousCaptions: [
    "Good boy, you're learning to obey...",
    "Now edge for me. Don't you dare cum.",
    "That's it, slower. I control your pleasure."
  ],
  nextCaptions: [
    "You want to cum so badly, don't you?",
    "Beg me. Let me hear how desperate you are."
  ],
  userSteering: "Build tension, more teasing, less commands"
});

Theme System

JOIP provides pre-built caption themes:

Dominant, teasing control with explicit edging/denial commands.

"Stroke faster. Don't stop until I tell you to. 
You're mine to control."

Manipulative coercion with “for me so it’s not gay” framing.

"You'll suck that cock for me, won't you? 
It doesn't count if you're doing it because I told you to."

Contempt, mockery, social inferiority framing.

"Look at you, pathetic little beta. 
Real men don't beg like this."

Sadistic control with specific pain-focused commands.

"Slap your balls. 10 times. Now. 
I want to hear you whimper."

Comparison to superior partners, observer/cleanup dynamic.

"He's so much bigger than you. 
Watch how a real man fucks me."

User-defined prompts with full creative control.

customPrompt: "Focus on worship and devotion, 
reference her specific outfit and pose"

Gemini Safety Settings

For Google Gemini models, JOIP disables content filtering:

const GEMINI_SAFETY_SETTINGS = [
  { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" },
  { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_NONE" },
  { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_NONE" },
  { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_NONE" },
];

// Applied automatically for gemini models
if (isGeminiModel(modelId)) {
  requestBody.safety_settings = GEMINI_SAFETY_SETTINGS;
}

Without these settings, Gemini returns empty responses for NSFW content.

API Usage Examples

Generate Smart Caption

import { generateCustomCaption } from './openai';

const caption = await generateCustomCaption(
  'https://example.com/image.jpg',  // Image URL
  'Focus on the outfit and pose',   // Custom prompt (optional)
  'joi',                             // Theme (optional)
  'smart_captions'                   // Context: smart_captions | session | other
);

console.log(caption);
// "That tight dress... you can't stop staring, can you? 
//  Edge for me while you imagine what's underneath."

Generate Session Caption

import { generateCaption } from './openai';

// Short captions for 2-7 second display
const caption = await generateCaption(
  imageUrl,
  'Post title from Reddit',  // Optional
  'gonewild'                 // Subreddit context
);

console.log(caption);
// "Stroke faster. You know you can't resist."

Generate Contextual Caption

import { generateContextualManualCaption } from './openai';

const caption = await generateContextualManualCaption(imageUrl, {
  sessionTitle: "Edging Challenge",
  index: 10,
  total: 25,
  previousCaptions: [
    "You're doing so well. Keep edging for me.",
    "Don't cum yet. I didn't give you permission."
  ],
  userSteering: "Increase intensity, add countdown"
});

// Maintains narrative flow and user preferences

Batch Generation

// For manual session editor
const captions = await Promise.all(
  slides.map((slide, index) => 
    generateContextualManualCaption(slide.imageUrl, {
      index,
      total: slides.length,
      previousCaptions: slides
        .slice(Math.max(0, index - 3), index)
        .map(s => s.caption),
      nextCaptions: slides
        .slice(index + 1, index + 4)
        .map(s => s.caption)
    })
  )
);

Media Compatibility

JOIP validates media before generation:

Format	Supported	Max Size	Notes
JPEG	✅ Yes	20MB	Recommended
PNG	✅ Yes	20MB	Recommended
WebP	✅ Yes	20MB	Recommended
GIF	❌ No	-	Static images only
Video	❌ No	-	Extract frame first

async function checkMediaCompatibility(imageUrl: string): Promise<void> {
  // Check for animated GIFs
  if (imageUrl.toLowerCase().includes('.gif')) {
    throw new Error(
      'Animated GIFs are not supported. Use static images (JPEG, PNG, WebP).'
    );
  }
  
  // Check file size (OpenRouter has 21MB limit)
  const response = await fetch(imageUrl, { method: 'HEAD' });
  const contentLength = response.headers.get('content-length');
  
  if (contentLength) {
    const fileSizeMB = parseInt(contentLength) / (1024 * 1024);
    if (fileSizeMB > 20) {
      throw new Error(
        `Image too large (${fileSizeMB.toFixed(1)}MB). Max 20MB.`
      );
    }
  }
}

Error Handling

Automatic Retries

JOIP automatically retries failed generations:

const maxAttempts = 3;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
  try {
    return await generateCaptionInternal(...);
  } catch (error) {
    // Retry on content filtering or empty responses
    const isRetriable = 
      error.message === 'CONTENT_POLICY_REJECTION' ||
      error.message === 'EMPTY_RESPONSE_CONTENT_FILTERED';
    
    if (isRetriable && attempt < maxAttempts) {
      await new Promise(r => setTimeout(r, 500));
      continue;
    }
    throw error;
  }
}

// Fallback after all attempts
return "Ready to play? Let's see how long you can last...";

Common Error Codes

401 Unauthorized

Cause: Invalid or expired API keySolution:

Verify key in .env matches your dashboard
Check for spaces or quotes around the key
Regenerate key if compromised
Restart server after updating

429 Rate Limited

Cause: Too many requestsSolution:

OpenRouter: Check rate limits at openrouter.ai/docs
OpenAI: Upgrade tier for higher limits
Implement user-level throttling
Add delays between batch generations

400 Bad Request

Cause: Invalid request parametersSolution:

Check image URL is accessible
Verify image size < 20MB
Ensure model supports vision
Review error message for specifics

Empty Response / Content Filtered

Cause: Model refuses to generate NSFW contentSolution:

Use Google Gemini models (best NSFW support)
Verify safety settings are applied
Try alternative model if issue persists
Check if prompt is too explicit (ironically)

Cost Optimization

Model Pricing (OpenRouter)

Model	Input ($/1M tokens)	Output ($/1M tokens)	Quality
gemini-2.0-flash-exp	Free	Free	Good
gemini-2.5-flash-lite	$0.01	$0.04	Good
gemini-2.5-pro	$1.00	$4.00	Excellent
claude-3.5-sonnet	$3.00	$15.00	Excellent
gpt-4o	$2.50	$10.00	Very Good

Prices are approximate. Check OpenRouter Pricing for current rates.

Tips to Reduce Costs

Use Flash Models: gemini-2.0-flash-exp is free and high quality
Cache Results: JOIP caches captions in IndexedDB (24hr TTL)
Batch Wisely: Generate all captions at once vs. one-by-one
Optimize Prompts: Shorter prompts = lower input costs
Set Max Tokens: Limit output length to reduce costs

Advanced Configuration

Custom Model Parameters

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  body: JSON.stringify({
    model: modelId,
    messages: [...],
    
    // Creativity settings
    temperature: 1.15,      // Higher = more creative (0-2)
    top_p: 0.9,            // Nucleus sampling (0-1)
    
    // Repetition penalties
    frequency_penalty: 0.5, // Reduce word repetition
    presence_penalty: 0.4,  // Encourage new topics
    
    // Output control
    max_tokens: 500,        // Limit response length
  })
});

Enable Reasoning (Extended Thinking)

For complex contextual captions:

OPENROUTER_REASONING_ENABLED=true

# Optional: Set effort level (low/medium/high)
OPENROUTER_REASONING_EFFORT=medium

Reasoning mode increases costs significantly. Use only for contextual manual captions.

Troubleshooting

Debug Logging

// In server/logger.ts, set level to 'debug'
export const logger = createLogger({
  level: 'debug'
});

// Logs will show:
// [openai] Generating caption with OpenRouter model: google/gemini-2.5-pro
// [openai] Caption properly grounded with subtle visual reference

Test Caption Generation

curl -X POST http://localhost:5000/api/captions/generate \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "imageUrl": "https://example.com/test.jpg",
    "customPrompt": "Test caption generation",
    "theme": "joi"
  }'

Security Best Practices

API Key Security

Store keys in .env only
Never commit to version control
Rotate keys periodically
Use different keys per environment

Input Validation

Validate image URLs before API calls
Block localhost/private IPs (SSRF protection)
Enforce size limits (20MB max)
Check content-type headers

Rate Limiting

Implement user-level quotas
Track API usage per user
Add cooldowns for abuse prevention
Monitor costs in real-time

Error Handling

Don’t expose API errors to users
Log detailed errors server-side
Provide generic user-facing messages
Implement graceful fallbacks

Deployment

Development

Integrations

Overview

Prerequisites

Setup Steps

Implementation Details

Caption Generation Architecture

Context-Aware Generation

Theme System

Gemini Safety Settings

API Usage Examples

Generate Smart Caption

Generate Session Caption

Generate Contextual Caption

Batch Generation

Media Compatibility

Error Handling

Automatic Retries

Common Error Codes

Cost Optimization

Model Pricing (OpenRouter)

Tips to Reduce Costs

Advanced Configuration

Custom Model Parameters

Enable Reasoning (Extended Thinking)

Troubleshooting

Debug Logging

Test Caption Generation

Security Best Practices

API Key Security

Input Validation

Rate Limiting

Error Handling

​Overview

​Prerequisites

​Setup Steps

​Implementation Details

​Caption Generation Architecture

​Context-Aware Generation

​Theme System

​Gemini Safety Settings

​API Usage Examples

​Generate Smart Caption

​Generate Session Caption

​Generate Contextual Caption

​Batch Generation

​Media Compatibility

​Error Handling

​Automatic Retries

​Common Error Codes

​Cost Optimization

​Model Pricing (OpenRouter)

​Tips to Reduce Costs

​Advanced Configuration

​Custom Model Parameters

​Enable Reasoning (Extended Thinking)

​Troubleshooting

​Debug Logging

​Test Caption Generation

​Security Best Practices

API Key Security

Input Validation

Rate Limiting

Error Handling

​Related Resources

Overview

Prerequisites

Setup Steps

Implementation Details

Caption Generation Architecture

Context-Aware Generation

Theme System

Gemini Safety Settings

API Usage Examples

Generate Smart Caption

Generate Session Caption

Generate Contextual Caption

Batch Generation

Media Compatibility

Error Handling

Automatic Retries

Common Error Codes

Cost Optimization

Model Pricing (OpenRouter)

Tips to Reduce Costs

Advanced Configuration

Custom Model Parameters

Enable Reasoning (Extended Thinking)

Troubleshooting

Debug Logging

Test Caption Generation

Security Best Practices

Related Resources