lum3on-ComfyUI_Reve-API/docs/unified_architecture.md

ComfyUI Reve API Integration Node - Unified Architecture Design

Overview

This document defines the architecture for a unified ComfyUI custom node that integrates all Reve API endpoints (Create, Edit, Remix) into a single, dynamic node with operation-specific inputs and outputs.

Core Design Principles

1. Unified Interface: Single node handles all three operations (Create, Edit, Remix)
2. Dynamic Inputs: Show/hide parameters based on selected operation type
3. Consistent Outputs: Standardized output format across all operations
4. Error Handling: Unified error management with operation-specific context
5. Credit Tracking: Integrated credit monitoring and usage tracking

Node Architecture

Main Node Class: ReveAPI

class ReveAPI:
    """
    Unified Reve API node supporting Create, Edit, and Remix operations
    with dynamic input system and consistent output handling.
    """
    
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "operation": (["create", "edit", "remix"], {"default": "create"}),
                "prompt": ("STRING", {"multiline": True, "default": "A beautiful landscape"})
            },
            "optional": {
                "api_key": ("STRING", {"default": ""}),
                "version": (["latest", "reve-create@20250915", "reve-edit@20250915", "reve-remix@20250915"], 
                          {"default": "latest"}),
                "aspect_ratio": (["16:9", "9:16", "3:2", "2:3", "4:3", "3:4", "1:1"], 
                               {"default": "3:2"}),
                "output_format": (["png", "jpeg", "webp", "json"], {"default": "png"}),
                "reference_image": ("IMAGE",),
                "reference_images": ("IMAGE",)  # Multi-image input for Remix
            }
        }
    
    RETURN_TYPES = ("IMAGE", "STRING", "STRING", "INT", "INT")
    RETURN_NAMES = ("image", "metadata", "request_id", "credits_used", "credits_remaining")
    FUNCTION = "process_request"
    CATEGORY = "image/ai"

Dynamic Input System

The node implements conditional input visibility based on operation type:

Create Mode

• Show: prompt, aspect_ratio, version, output_format, api_key
• Hide: reference_image, reference_images
• Validation: prompt required, aspect_ratio valid, version valid

Edit Mode

• Show: prompt, reference_image, version, output_format, api_key
• Hide: reference_images, aspect_ratio
• Validation: prompt required, reference_image required, version valid

Remix Mode

• Show: prompt, reference_images, aspect_ratio, version, output_format, api_key
• Hide: reference_image
• Validation: prompt required, reference_images (1-4), aspect_ratio valid, XML tags valid

Module Structure

custom_nodes/ComfyUI_Reve-API/
├── __init__.py                 # Node registration and ComfyUI integration
├── requirements.txt            # Dependencies
├── README.md                   # Installation and usage guide
├── nodes/
│   ├── __init__.py
│   ├── reve_api_node.py       # Main unified ReveAPI node
│   ├── dynamic_inputs.py      # Dynamic input system implementation
│   └── operation_handlers.py  # Operation-specific logic handlers
├── core/
│   ├── __init__.py
│   ├── reve_api_client.py     # HTTP client for Reve API
│   ├── image_utils.py         # Image conversion utilities
│   ├── credit_monitor.py      # Credit tracking and monitoring
│   └── error_handler.py       # Error handling and content policy detection
├── docs/
│   ├── api_research.md        # Reve API specifications
│   ├── unified_architecture.md # This document
│   └── examples/              # Usage examples and workflows
└── tests/
    ├── __init__.py
    ├── test_api_client.py
    ├── test_image_utils.py
    ├── test_unified_node.py
    ├── test_dynamic_inputs.py
    ├── test_operation_handlers.py
    └── test_error_handling.py

Core Components

1. API Client (reve_api_client.py)

• HTTP request handling with authentication
• Request formatting for each operation type
• Response parsing and error handling
• Retry logic for rate limiting
• Credit tracking integration

2. Image Utilities (image_utils.py)

• ComfyUI tensor to base64 conversion
• Multi-image handling for Remix operation
• Format validation and size checking
• Quality preservation during conversion

3. Dynamic Input System (dynamic_inputs.py)

• Operation-based input visibility control
• Parameter validation per operation type
• Input mapping and transformation
• ComfyUI refresh handling

4. Operation Handlers (operation_handlers.py)

• Create operation: Text-to-image generation
• Edit operation: Image editing with instructions
• Remix operation: Multi-image combination with XML parsing
• Unified response processing

API Integration Specifications

Reve API Endpoints

• Create: POST /api/create - Text-to-image generation (18 credits)
• Edit: POST /api/edit - Image editing (30 credits)
• Remix: POST /api/remix - Multi-image combination (30 credits)

Authentication

• API key via header: Authorization: Bearer {api_key}
• Environment variable fallback: REVE_API_KEY
• Per-request override via node input

Request/Response Format

All operations return standardized response:

{
    "image": "base64_encoded_image",
    "request_id": "unique_request_identifier", 
    "credits_used": 18,
    "credits_remaining": 982,
    "metadata": {
        "operation": "create|edit|remix",
        "parameters": {...},
        "processing_time": 2.5
    }
}

Error Handling Strategy

Error Categories

1. Authentication Errors (401): Invalid API key
2. Validation Errors (400): Invalid parameters
3. Content Policy (400): Content policy violations
4. Rate Limiting (429): Too many requests
5. Server Errors (500): API service issues

Error Response Format

{
    "success": False,
    "error_code": "CONTENT_POLICY_VIOLATION",
    "error_message": "Content violates policy guidelines",
    "operation": "create",
    "retry_after": None  # For rate limiting
}

Performance Considerations

1. API Client Caching: Reuse HTTP client instances
2. Image Conversion Optimization: Efficient tensor/base64 conversion
3. Memory Management: Cleanup after operation switching
4. Parameter Validation: Early validation to prevent wasted credits
5. Lazy Loading: Dynamic input system with minimal overhead

User Experience Features

1. Operation Mode Indicator: Visual feedback in node title
2. Parameter Tooltips: Context-sensitive help text
3. Credit Cost Preview: Show estimated cost before execution
4. Progress Indicators: Real-time processing feedback
5. Smart Parameter Preservation: Maintain compatible settings when switching operations

This architecture provides a solid foundation for implementing the unified Reve API integration node with all required functionality while maintaining ComfyUI best practices and user experience standards.