DOCSEARCHbyAlgolia
Submit Docs

FreeTheAi Documentation

repository·master·Indexed 21 days ago

https://github.com/free-the-ai/free-ai

An OpenAI-compatible API gateway providing free access to over 60 active AI models, including chat, image generation, and audio capabilities. It serves as a drop-in replacement for OpenAI SDKs, supporting Python, JavaScript/TypeScript, and curl integrations. Features include role-gated model aliases, a tiered rate-limit system managed via Discord, and endpoints for chat completions, image generation, and speech-to-text/text-to-speech.

Tokens
42.7K
Snippets
126
Records
211
Agent score
72%

What's inside FreeTheAi

  1. Capabilities of the OKLCH Skill

    master

    The OKLCH Skill provides the following capabilities for web development tasks:

    • Color Conversion: Converting hex, rgb, and hsl to oklch.
    • Palette Generation: Creating perceptually uniform palette scales (e.g., 50–950).
    • Theming: Deriving dark mode themes via lightness manipulation and implementing Tailwind v4 oklch theming and custom tokens.
    • Accessibility: Performing WCAG 2 and APCA contrast checking.
    • Color Science: Detecting hue drift in HSL-based palettes and managing sRGB and Display P3 gamut boundaries.
    • CSS Implementation: Applying CSS fallback patterns for wider gamut support.

  2. Implement Spring Animations for natural motion

    master

    Spring animations simulate real physics and are superior to duration-based animations for:

    • Drag interactions with momentum.
    • Elements that feel "alive" (e.g., Apple's Dynamic Island).
    • Gestures that can be interrupted mid-animation (springs maintain velocity when interrupted, whereas CSS animations restart from zero).
    • Decorative mouse-tracking interactions.

    Implementation with Framer Motion

    When tying visual changes to mouse position, use useSpring to interpolate values. This prevents the motion from feeling artificial or instant.

    Configuration Styles

    1. Apple-style (Recommended): Uses type, duration, and bounce. Keep bounce subtle (0.1-0.3).
    2. Traditional Physics: Uses mass, stiffness, and damping for granular control.
    import { useSpring } from 'framer-motion';

// Without spring: feels artificial, instant
const rotation = mouseX * 0.1;

// With spring: feels natural, has momentum
const springRotation = useSpring(mouseX * 0.1, {
  stiffness: 100,
  damping: 10,
});

  4. Implement the Skeuomorphic UI design system

    master

    Use the skeuomorphic-ui skill to design dark, tactile UI components like knobs, sliders, and recessed controls. The system relies on consistent top-down lighting, layered shadows, and specific material depth to create a realistic hardware-like appearance.

    Core Design Principles

    • Lighting: Light direction must always come from the top.
    • Backgrounds: Scene/background colors must stay within the #080808 to #1a1a1a range.
    • Layering Order: To ensure believable depth, always structure components in this order:
      1. Scene background (very dark)
      2. Parent raised shell
      3. Inset zones (tracks, wells, cavities)
      4. Raised interactive objects (dial/button caps)
      5. Readout/details (numbers, ticks, icon glows)

  6. Why use OKLCH instead of HSL for palettes?

    master

    OKLCH is preferred over HSL for design systems due to two critical issues in HSL:

    1. Hue Drift: In HSL, changing lightness can cause the perceived hue to shift (e.g., a light blue might shift toward purple). OKLCH maintains a stable hue regardless of lightness.
    2. Brightness Inconsistency: In HSL, different hues at the same lightness value have wildly different perceived brightness (e.g., HSL yellow vs. HSL blue). OKLCH provides perceptual uniformity, meaning equal L values result in equal perceived brightness.

  7. Choose the correct easing for UI animations

    master

    Select easing based on the element's movement pattern. Never use ease-in for UI animations, as it makes the interface feel sluggish. Use custom cubic-bezier curves instead of built-in CSS easings for more intentional movement.

    • Entering element: Use ease-out (starts fast, feels responsive).
    • Moving/morphing on screen: Use ease-in-out (natural acceleration/deceleration).
    • Hover/color change: Use ease.
    • Constant motion (marquee, progress bar): Use linear.
    • Default: ease-out.

    Recommended Custom Easings

    /* Strong ease-out for UI interactions */
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);

/* Strong ease-in-out for on-screen movement */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);

/* iOS-like drawer curve (from Ionic Framework) */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);

  8. Configure Nested Inset and Popping Button Patterns

    master

    When designing rows with multiple circular action buttons, do not use a single shared inset. Instead, use individual inset wells for each button to maintain visual symmetry and depth.

    Correct Structure

    Outer raised shell $\rightarrow$ InsetSlot (per button) $\rightarrow$ CircleBtn (raised/popping)

    Implementation Details

    • Symmetry: The button should be flush on the Y-axis (touching the top and bottom of the inset interior). Keep margins/padding primarily on the X-axis.
    • Sizing:
      • Inset well: h-full ... p-1.5
      • Button inside: size-full aspect-square rounded-full
    • Material Consistency: Raised child controls (like buttons) should use the same material gradient as the parent shell (bg-gradient-to-b from-[#202020] to-[#191919]) unless explicit contrast is requested.
    <!-- Pattern: Nested Inset + Popping Button -->
<div class="bg-gradient-to-b from-[#202020] to-[#191919] ...">
  <!-- Button 1 Well -->
  <div class="h-full p-1.5 shadow-[0_0.5px_0_#ffffff50,0_2px_6px_#00000090_inset]">
    <button class="size-full aspect-square rounded-full bg-gradient-to-b from-[#202020] to-[#191919] shadow-[0_1px_0.5px_#ffffff1a_inset,0_1px_2px_#ffffff35_inset,...]">
      <!-- Icon -->
    </button>
  </div>
  <!-- Button 2 Well ... -->
</div>

  9. Planned SDK and Package Availability

    master

    FreeTheAi is moving towards providing official, thin OpenAI-compatible wrappers to simplify integration. Developers should look out for the following packages which are planned for release via npm and PyPI:

    • JavaScript/TypeScript: @freetheai/sdk on npm.
    • Python: freetheai on PyPI.

    These packages are intended to be thin wrappers around the OpenAI-compatible API, allowing for easy migration from standard OpenAI clients.

  10. Decide whether to animate an element

    master

    Use the following frequency-based decision framework to determine if an animation is appropriate. A key rule is to never animate keyboard-initiated actions, as they occur too frequently and make the interface feel slow.

    FrequencyDecision
    100+ times/day (keyboard shortcuts, command palette toggle)No animation. Ever.
    Tens of times/day (hover effects, list navigation)Remove or drastically reduce
    Occasional (modals, drawers, toasts)Standard animation
    Rare/first-time (onboarding, feedback forms, celebrations)Can add delight

    Valid purposes for animation include spatial consistency, state indication, explanation, feedback, and preventing jarring changes.

  11. Understand FreeTheAi Model Prefixes

    master

    Models in the FreeTheAi catalog are organized by prefixes that indicate their primary capability. Use these prefixes to identify suitable models for your task:

    PrefixCapability
    bbl/*General chat models
    eve/*Image generation models
    ever/*Chat, image generation, and image edit models
    exa/*Role-gated web search models
    glm/*Long-context chat models
    kai/*Aggregated free chat and coding models
    mim/*Chat and voice models
    min/*Chat models
    olm/*DeepSeek and coding-oriented models
    opc/*Free chat/coding models
    pplx/*Role-gated web search
    xai/*Role-gated voice models

  12. How the OKLCH palette generation algorithm works

    master

    The algorithm generates a palette from a base color defined by Lightness (L), Chroma percentage (C%), and Hue (H) using three steps:

    1. Lightness Bounds: It calculates a lightness range using a delta of 0.4. The lightness is clamped between 0.05 and 0.95 to prevent pure black or white, which have zero chroma.
      • minL = max(0.05, baseL - delta)
      • maxL = min(0.95, baseL + delta)
    2. Lightness Distribution: Lightness is distributed evenly from maxL (assigned to label 50) down to minL (assigned to label 950).
    3. Chroma Clamping: To ensure every color remains within the color gamut, the chroma for each step is calculated as a percentage of the maximum possible chroma for that specific lightness and hue:
      • step[i].C = (chromaPercentage / 100) * maxChroma