SoLoSage

This is a Next.js project for image generation using AI models from OpenAI, Replicate, and Together AI.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

MCP Server

SoLoSage includes a Model Context Protocol (MCP) server for image generation. The MCP server allows AI assistants to generate images through a standardized protocol.

Configuration

To use the MCP server, you need to set the following environment variables:

• SOLOSAGE_API_KEY: Your API key for authentication (required)
• MCP_PORT: The port for the MCP server (defaults to 3001)
• COOLIFY_FQDN: The fully qualified domain name when deployed on Coolify (optional)

Running the MCP Server

The MCP server runs alongside the Next.js application when you use the following command:

npm run start:mcp

On Windows:

npm run start:mcp:win

MCP Protocol Implementation

The MCP server implements a simple HTTP server that follows the Model Context Protocol. It provides:

1. Tool listing endpoint (list_tools)
2. Tool call endpoint (call_tool)

The server provides a generate_image tool that can generate images using various AI providers (OpenAI, Replicate, Together).

MCP Server Integration

SoLoSage now includes an integrated MCP (Model Context Protocol) server that allows AI systems to access the image generation capabilities through a standardized protocol.

Running the MCP Server

To run both the Next.js app and MCP server together:

npm run dev:mcp

For production deployment:

npm run build
npm run start:mcp

MCP Documentation

For detailed information about the MCP server, including available tools, testing procedures, and integration guide, see the MCP Server Documentation.

API Keys

SoLoSage requires an API key for authentication. See the API Key Guide for details on obtaining and managing API keys.

Development Environment

API Key Generation Testing

By default, the development environment uses mock data for API key generation to avoid connecting to the production database. If you need to test the real API key generation functionality locally:

1. Set the USE_REAL_API=true environment variable in your .env.local file
2. Make sure your Supabase service role key is properly configured
3. Start the development server normally

This allows you to test API key generation with real database connections without having to deploy to production.

API

SoLoSage provides a REST API for accessing its functionality programmatically.

API Key Authentication

All API endpoints require authentication using a SoLoSage API key. You can provide this key in one of two ways:

1. Authorization Header (Recommended):

   Authorization: Bearer YOUR_SOLOSAGE_API_KEY

2. SOLOSAGE_API_KEY Header (Deprecated):

   SOLOSAGE_API_KEY: YOUR_SOLOSAGE_API_KEY

   Note: This method is deprecated and will be removed in a future version. Please use the Authorization header instead.

API keys can be generated and managed in the Settings page of the SoLoSage application.

Available Endpoints

• POST /api/v1/models: Retrieve available models for a specific provider

  • Request body: { "provider": "openai" | "replicate" | "together", "apiKey": "YOUR_PROVIDER_API_KEY" }
  • Response: { "models": [...] }

• POST /api/v1/generate: Generate an image using AI

  • Request body: { "model": "openai" | "replicate" | "together", "modelId": "model-id", "prompt": "your prompt" }
  • Headers: Authorization: Bearer YOUR_SOLOSAGE_API_KEY
  • Response: { "imageUrl": "url-to-generated-image" }

• GET /api/v1/hello: Test endpoint for API key authentication

  • Response: { "message": "Hello, authenticated user!", "userId": "user-id" }

API Key Validation

The API validates API keys by:

1. Checking for the API key in the Authorization header (Bearer token) or SOLOSAGE_API_KEY header (deprecated)

2. Validating the key against the database All v1 API endpoints are protected by middleware that validates your API key. The validation process:

3. Checks for the API key in the Authorization header (preferred) or the SOLOSAGE_API_KEY header (deprecated)

4. Validates the key against the database

5. Returns a 401 Unauthorized error if the key is invalid

API Key Usage

SoLoSage API supports two methods for providing API keys in requests:

1. Authorization Header (Recommended)

Use the Authorization header with a Bearer token:

curl -X GET "https://solosage.sololink.cloud/api/v1/hello" \
  -H "Authorization: Bearer sk-solosage-YOUR_API_KEY"

2. SOLOSAGE_API_KEY Header (Deprecated)

While still supported for backward compatibility, the SOLOSAGE_API_KEY header is deprecated and will be removed in a future version:

curl -X GET "https://solosage.sololink.cloud/api/v1/hello" \
  -H "SOLOSAGE_API_KEY: sk-solosage-YOUR_API_KEY"

The Authorization header is strongly recommended for all integrations.

API Key Architecture

SoLoSage uses a two-tier API key system:

1. SoLoSage API Key: Authenticates requests to the SoLoSage API itself. This key is required for all API endpoints.

2. Provider API Keys: When generating images or listing models, SoLoSage requires API keys for the third-party providers:

   • OpenAI API key for DALL-E models
   • Replicate API key for Replicate models
   • Together AI API key for Together models

These provider keys are typically stored in the browser when using the web interface. When making direct API calls, you need to include both your SoLoSage API key (for authentication) and the relevant provider API key (for the actual service).

Example: Getting Models from Replicate

curl -X POST "https://solosage.sololink.cloud/api/v1/models" \
  -H "Authorization: Bearer sk-solosage-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "replicate",
    "apiKey": "YOUR_REPLICATE_API_KEY"
  }'

Example: Generating an Image with OpenAI

{
  "prompt": "A beautiful sunset over mountains",
  "model": "openai",
  "modelId": "dall-e-3",
  "providerApiKey": "sk-openai-YOUR_OPENAI_KEY"
}

This architecture ensures that SoLoSage doesn't need to store your third-party API keys, enhancing security and giving you direct control over your usage and billing with these providers.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

Deployment

The application can be started on port 3001 with:

npm run build
npm start

This will run the application on port 3001 to avoid conflicts with other services.