AI Endpoints

ryOS provides several AI-powered endpoints for content generation, separate from the main chat interface. These endpoints power specialized features like applet generation, time-travel web pages, memory extraction, and music metadata extraction.

Most AI endpoints are wrapped with the shared apiHandler utility (CORS, method checks, auth boundaries, Redis/logger context), with endpoint-specific rate limits layered on top.

Applet AI

The Applet AI endpoint powers intelligent responses within sandboxed HTML applets, supporting both text generation and AI image generation.

Endpoint

Request

{
  // Text prompt (required if no messages provided)
  prompt?: string;           // max 4000 characters
  
  // Conversation history (alternative to prompt)
  messages?: Array<{
    role: "user" | "assistant" | "system";
    content?: string;        // max 4000 characters
    attachments?: Array<{    // max 4 per message, user messages only
      mediaType: string;     // e.g., "image/png", "image/jpeg"
      data: string;          // base64-encoded image data
    }>;
  }>;                        // max 12 messages
  
  // Optional applet context
  context?: string;          // max 2000 characters
  
  // Generation parameters
  temperature?: number;      // 0-1, default 0.6
  mode?: "text" | "image";   // default "text"
  
  // Image attachments (mode="image" only)
  images?: Array<{           // max 4 images
    mediaType: string;
    data: string;            // base64-encoded
  }>;
}

Headers

Response

{
  "reply": "Generated response text"
}

Returns binary image data with headers:

Rate Limits

Note: The main Chat API (/api/chat) has separate rate limits: 15 messages per 5 hours for authenticated users, 3 messages per 24 hours for anonymous users.

Rate limit headers included in responses:

• X-RateLimit-Limit: Maximum requests allowed

• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Seconds until reset
• Retry-After: Seconds to wait (on 429)

Models

• Text: gemini-3-flash-preview

• Image: gemini-3.1-flash-image-preview

Example

curl -X POST https://os.ryo.lu/api/applet-ai \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the weather like today?",
    "context": "Weather applet showing San Francisco",
    "temperature": 0.7
  }'

Response:

{
  "reply": "I don't have access to real-time weather data, but based on San Francisco's typical climate..."
}

curl -X POST https://os.ryo.lu/api/applet-ai \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "image",
    "prompt": "A pixel art sunset over mountains"
  }' \
  --output generated-image.png

curl -X POST https://os.ryo.lu/api/applet-ai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Username: yourname" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is in this image?",
        "attachments": [{
          "mediaType": "image/png",
          "data": "iVBORw0KGgoAAAANSUhEUgAA..."
        }]
      }
    ]
  }'

Error Responses

Internet Explorer Generator

The Internet Explorer Generator creates "time-travel" web pages, reimagining how websites might have looked in different eras (past or future). It generates complete HTML pages styled to match historical design trends or speculative future aesthetics.

Endpoint

Request

{
  url?: string;              // Target URL (alternative to query param)
  year?: string;             // Target year (alternative to query param)
  messages?: Array<{         // Conversation context
    role: "user" | "assistant" | "system";
    content: string;
    // ... UIMessage fields
  }>;
  model?: SupportedModel;    // AI model selection
}

Headers

Response

Returns a streaming response (text/event-stream) containing the generated HTML page. The response follows the AI SDK's UI message stream format.

Generated HTML includes:

• Era-appropriate styling and typography
• Historical or futuristic design elements
• <!-- TITLE: ... --> comment with page title
• Complete, self-contained HTML document

Results are cached in Redis for future retrieval.

Rate Limits

Supported Models

Design Guidelines

The AI applies different design principles based on the target year:

• Bold, creative speculation about design trends
• Embraces backdrop-blur, simple animations
• Uses emojis or simple SVGs for icons
• Considers potential technological breakthroughs

• Matches historical design era (Art Deco, Web 1.0, etc.)
• Considers available technology of the time
• Simulates period-appropriate materials and textures
• May output as print, newspaper, telegram, etc. for very old dates

• Reflects current website state accurately
• Up-to-date styling and branding

Example

curl -X POST "https://os.ryo.lu/api/ie-generate?url=apple.com&year=1984" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Generate a page for Apple in 1984"
      }
    ]
  }'

Error Responses

Parse Title (Music Metadata)

The Parse Title endpoint uses AI to extract structured music metadata from YouTube video titles. It intelligently parses song titles, artist names, and album information from various title formats.

Endpoint

Request

{
  title: string;           // Raw YouTube video title (required)
  author_name?: string;    // YouTube channel name (optional, helps identify artist)
}

Headers

Response

{
  title: string;           // Extracted song title (falls back to raw title)
  artist?: string;         // Extracted artist name (if found)
  album?: string;          // Extracted album name (if found)
}

Rate Limits

Model

Uses gpt-4.1-mini for efficient metadata parsing.

Language Handling

The parser prefers original language names over romanized/translated versions:

Example

curl -X POST https://os.ryo.lu/api/parse-title \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daft Punk - Get Lucky (Official Audio) ft. Pharrell Williams, Nile Rodgers",
    "author_name": "Daft Punk"
  }'

Response:

{
  "title": "Get Lucky",
  "artist": "Daft Punk"
}

curl -X POST https://os.ryo.lu/api/parse-title \
  -H "Content-Type: application/json" \
  -d '{
    "title": "[MV] IU(아이유) _ Blueming(블루밍)",
    "author_name": "1theK (원더케이)"
  }'

Response:

{
  "title": "Blueming",
  "artist": "아이유"
}

Error Responses

Memory Extraction Endpoints

These endpoints support ryOS memory features (daily notes + long-term memory).

Endpoint Summary

POST /api/ai/extract-memories

Request body:

{
  "messages": [{ "role": "user", "content": "..." }],
  "timeZone": "America/Los_Angeles"
}

Response:

{
  "extracted": 2,
  "dailyNotes": 4,
  "analyzed": 3,
  "message": "Logged 4 daily notes, extracted 2 long-term memories"
}

POST /api/ai/process-daily-notes

Request body (optional):

{
  "timeZone": "America/Los_Angeles"
}

Response:

{
  "processed": 3,
  "extracted": 2,
  "created": 1,
  "updated": 1,
  "dates": ["2026-02-26", "2026-02-27", "2026-02-28"],
  "skippedDates": [],
  "message": "Processed 3 daily notes → 1 new memories, 1 updated"
}

Related

• Chat API - Main AI chat endpoint with tool calling

• AI System - AI providers and available tools
• API Reference - Overview of all ryOS API endpoints
• Chats App - Frontend chat application documentation