This comprehensive technical reference documents NPC Forge's internal API structure for developers who want to understand system functionality or contribute to development.
NPC Forge uses Next.js 15 API routes for all backend functionality with server-side OpenAI integration:
POST /api/generatePurpose: Creates new characters based on user specifications with AI generation
Request Format:
{
// Required Core Fields
description: string; // Character description (2-500 characters)
include_quests: boolean; // Generate quest content
include_dialogue: boolean; // Generate dialogue options
include_items: boolean; // Generate item inventory
include_portrait: boolean; // Generate character portrait
// Optional Character Configuration
genre?: string; // Selected genre category
sub_genre?: string; // Specific sub-genre template
gender?: string; // Character gender option
age_group?: string; // Age category selection
moral_alignment?: string; // Good/Neutral/Evil alignment
relationship_to_player?: string; // Ally/Enemy/Neutral/etc.
// Advanced Configuration Objects
advanced_options?: {
height?: string; // Physical height category
build?: string; // Physical build type
distinctive_features?: string; // Special physical characteristics
social_class?: string; // Social/economic status
homeland?: string; // Origin/background location
occupation?: string; // Character profession
personality_traits?: string[]; // Selected personality characteristics
};
// Content Generation Configuration
quest_options?: {
num_quests?: number; // Number of quests (3-7)
quest_types?: string[]; // Types of quests to generate
reward_types?: string[]; // Types of rewards to include
};
dialogue_options?: {
num_lines?: number; // Number of dialogue lines (5-15)
dialogue_contexts?: string[]; // Conversation contexts
};
item_options?: {
num_items?: number; // Number of items (3-10)
rarity_distribution?: string; // Item rarity preferences
item_categories?: string[]; // Types of items to generate
};
// Portrait Configuration
portrait_options?: {
art_style?: string; // Visual art style preference
expression?: string; // Character expression/mood
framing?: string; // Portrait composition type
background?: string; // Background style option
};
// Model Selection
text_model?: string; // Selected text generation model
image_model?: string; // Selected image generation model
}Response Formats:
Success Response (200 OK):
{
character: {
// Core Identity
id: string; // Unique character identifier
name: string; // Generated character name
age_group: string; // Age category
gender: string; // Character gender
moral_alignment: string; // Character alignment
relationship_to_player: string; // Player relationship
// Generated Content
appearance: string; // Physical description
personality: string; // Personality overview
backstory_hook: string; // Background narrative
// Optional Generated Content
quests?: Array<{
title: string; // Quest name
description: string; // Quest details
reward: string; // Quest completion reward
}>;
dialogue?: string[]; // Character dialogue options
items?: Array<{
name: string; // Item name
description: string; // Item details
rarity?: string; // Item rarity level
}>;
// Portrait Data
portrait?: {
url: string; // Generated image URL
alt_text: string; // Accessibility description
style: string; // Art style used
};
// Metadata
created_at: string; // Creation timestamp
generation_models: {
text_model: string; // Model used for text
image_model?: string; // Model used for image
};
// Additional Traits
additional_traits?: Record<string, string>; // AI-generated character traits
}
}Error Response (400/500):
{
error: string; // Technical error message
character: null; // Null character data
errorType: string; // Error category classification
userMessage: string; // User-friendly error description
details?: {
field?: string; // Problematic field if validation error
suggestion?: string; // Suggested resolution
}
}Error Categories:
validation_error: Invalid input parametersusage_limit_exceeded: Monthly generation limits reachedapi_error: OpenAI API issues (rate limits, service issues)content_policy_violation: Generated content blocked by content filterstimeout_error: Generation took too long and timed outnetwork_error: Connection issues with external servicesPOST /api/regeneratePurpose: Regenerates specific character elements or adds new content to existing characters
Request Format:
{
// Required Fields
character: Character; // Complete existing character object
field: string; // Regeneration target specification
// Optional Configuration
model?: string; // Text model for regeneration
portraitOptions?: { // Portrait-specific options
art_style?: string;
expression?: string;
framing?: string;
background?: string;
};
// Advanced Options
regeneration_context?: {
preserve_relationships?: boolean; // Maintain character relationships
maintain_core_identity?: boolean; // Keep essential character elements
enhancement_focus?: string; // Specific improvement area
};
}Supported Regeneration Fields:
Character Attributes:
name - Generate new character nameappearance - Regenerate physical descriptionpersonality - Create new personality descriptionbackstory_hook - Generate new background narrativePortrait Operations:
portrait - Regenerate character portrait with new settingsContent Elements:
quest_[index]_title - Regenerate specific quest titlequest_[index]_description - Regenerate quest descriptionquest_[index]_reward - Regenerate quest rewardquest_[index] - Regenerate complete questdialogue_[index] - Regenerate specific dialogue lineitem_[index] - Regenerate specific itemTrait Management:
additional_traits - Generate multiple new traitsadd_single_trait - Generate one new traitregenerate_trait_[traitKey] - Regenerate specific existing traitResponse Format: Same as generation API, returning updated character object
POST /api/edit-portraitPurpose: Edit existing character portraits using AI-powered image modification
Request Format:
{
// Required Fields
character: Character; // Character with existing portrait
editPrompt: string; // Natural language edit description
// Optional Configuration
imageModel?: string; // Image model for editing (gpt-image-1 only)
// Advanced Edit Options
editOptions?: {
preserve_style?: boolean; // Maintain original art style
enhancement_mode?: boolean; // Focus on improvements vs changes
iteration_count?: number; // Number of edit attempts (1-3)
};
}Edit Prompt Guidelines:
"change hair color to blonde""add round glasses""remove the hat""make them smile""change shirt to red"Model Support:
Response Format:
{
success: boolean; // Edit operation success status
character: Character; // Updated character with edited portrait
editMetadata?: {
originalPrompt: string; // Original edit request
processingTime: number; // Edit processing duration
modelUsed: string; // AI model used for editing
};
error?: string; // Error message if edit failed
}POST /api/chatPurpose: Generate AI responses for character conversations maintaining personality consistency
Request Format:
{
// Required Fields
characterId: string; // Unique character identifier
character: Character; // Complete character object
messages: ChatMessage[]; // Previous conversation history
newMessage: string; // User's current message (max 1000 chars)
model: string; // Selected AI model for response
// Optional Configuration
conversationContext?: {
maxContextMessages?: number; // Number of previous messages to include (default: 15)
responseStylePreference?: string; // Preferred response style or length
emotionalContext?: string; // Current conversation emotional state
};
}ChatMessage Interface:
{
id: string; // Unique message identifier
role: 'user' | 'character'; // Message sender type
content: string; // Message text content
timestamp: string; // Message creation time
characterId: string; // Associated character ID
metadata?: {
modelUsed?: string; // AI model for character responses
processingTime?: number; // Response generation time
tokenCount?: number; // Message token usage
};
}Response Format:
{
success: boolean; // Response generation success
message: ChatMessage; // Generated character response
conversationMetadata?: {
totalMessages: number; // Total conversation length
characterConsistencyScore?: number; // Personality consistency rating
responseQuality?: string; // Response quality assessment
};
error?: string; // Error message if generation failed
}Character Response Features:
GET /api/proxy-image?url={imageUrl}Purpose: Proxy external image URLs for CORS compatibility and caching
Query Parameters:
url (required): External image URL to proxyResponse: Image data with appropriate headers for browser compatibility
Use Cases:
API Security:
Request Authentication:
Request Validation:
Data Sanitization:
OpenAI Integration:
Safety Measures:
Limit Structure:
Usage Calculation:
Limit Enforcement:
Testing Support:
Error Types and Handling:
Validation Errors (400):
Usage Limit Errors (429):
API Integration Errors (502/503):
Content Policy Errors (400):
Timeout Errors (408):
Retry Logic:
Data Recovery:
API Performance Targets:
Optimization Strategies:
Architecture Scalability:
Local Development:
API Testing Tools:
Development Guidelines:
Code Standards: