---
title: FREE NSFW HUB
emoji: 🌍
colorFrom: pink
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
short_description: Best & Free NSFW AI services
---
# Free NSFW Hub - Documentation

## Overview

Free NSFW Hub is a Flask-based web application that provides a curated collection of NSFW (Not Safe For Work) detection and content generation projects hosted on Hugging Face Spaces. The application organizes these tools into categories for easy visual exploration and discovery.

## Features

- **Categorized Organization**: Projects are organized into multiple categories including Popular, BEST, Text Generation, Text to Image, Image to Video, Image In/Out-Painting, Extension, and Utility
- **Visual Grid Layout**: 2x2 grid display with live iframe previews
- **Pagination Support**: Browse through categories with 4 items per page
- **Responsive Design**: Adapts to mobile and desktop screens
- **Live Preview**: Direct iframe embedding of Hugging Face Spaces
- **Fallback Mechanism**: Screenshot fallback for domains that block iframe embedding

## Technical Architecture

### Core Components

1. **Flask Application**: Python web framework handling routing and API endpoints
2. **Frontend**: Pure HTML/CSS/JavaScript without external dependencies
3. **Integration**: Direct embedding of Hugging Face Spaces

### File Structure

```
/
├── app.py              # Main Flask application
└── templates/
    └── index.html      # Dynamically generated HTML template
```

## Configuration

### Blocked Domains

The application maintains a list of domains that commonly block iframe embedding:
- naver.com
- daum.net
- google.com
- facebook.com
- instagram.com
- kakao.com
- ycombinator.com

For these domains, the application falls back to screenshot previews.

### Categories and Spaces

The `CATEGORIES` dictionary contains curated Hugging Face Spaces URLs organized by type:

- **Popular**: Most accessed NSFW-related tools
- **BEST**: Top-rated video and image generation tools
- **TEXT generate**: Novel and story generation tools
- **TEXT TO IMAGE**: Image generation from text prompts
- **IMAGE TO VIDEO**: Video generation from images
- **IMAGE IN/OUT-PAINTING**: Image editing and enhancement tools
- **Extension**: Additional utilities (voice cloning, sound effects, etc.)
- **Utility**: General purpose AI tools

## API Endpoints

### GET /
- **Description**: Serves the main application interface
- **Response**: HTML page with category tabs and grid layout

### GET /api/category
- **Description**: Retrieves paginated items for a specific category
- **Parameters**:
  - `name` (string): Category name
  - `page` (integer, optional): Page number (default: 1)
  - `per_page` (integer, optional): Items per page (default: 4)
- **Response**: JSON object containing:
  ```json
  {
    "items": [
      {
        "title": "space-name",
        "owner": "username",
        "iframe": "direct-url",
        "shot": "screenshot-url",
        "hf": "original-huggingface-url"
      }
    ],
    "page": 1,
    "total_pages": 3
  }
  ```

## URL Processing

### Direct URL Conversion
Converts Hugging Face Space URLs to direct accessible URLs:
- Pattern: `https://huggingface.co/spaces/{owner}/{name}`
- Converts to: `https://{owner}-{name}.hf.space`

### Screenshot URL Generation
Creates screenshot URLs for preview fallback:
- Uses thum.io service: `https://image.thum.io/get/fullpage/{url}`

### Preview URL Processing
Determines the best preview method:
1. Checks if domain is blocked → uses screenshot
2. Handles special problematic URLs → uses screenshot
3. Converts HF spaces to embed URLs
4. Falls back to screenshot for any errors

## Frontend Implementation

### UI Components

1. **Header Section**
   - Title and description
   - Hugging Face badge with link

2. **Category Tabs**
   - Dynamically generated from CATEGORIES
   - Active state styling
   - Click handlers for category switching

3. **Content Grid**
   - 2x2 layout on desktop
   - Single column on mobile (<800px)
   - Card height: 540px for optimal preview

4. **Card Elements**
   - Live/Static label indicator
   - Iframe preview (scaled to 60%)
   - Footer with link to original space

5. **Pagination Controls**
   - Previous/Next buttons
   - Current page indicator
   - Disabled state for boundary pages

### Styling

- **Font**: Nunito (Google Fonts)
- **Color Scheme**: 
  - Background: #f6f8fb
  - Cards: white with subtle shadows
  - Active tab: #a78bfa (purple)
  - Links: #4a6dd8 (blue)

### JavaScript Functionality

- **No external dependencies**: Uses vanilla JavaScript
- **AJAX requests**: XMLHttpRequest for API calls
- **Dynamic content**: Updates grid and pagination without page reload
- **State management**: Tracks active category and current page

## Security Considerations

### Iframe Sandboxing
All iframes include security attributes:
```html
sandbox="allow-forms allow-modals allow-popups allow-same-origin allow-scripts allow-downloads"
```

### Content Loading
- Lazy loading for iframes to improve performance
- Fallback to screenshots for problematic domains

## Deployment

### Requirements
- Python 3.x
- Flask framework
- Network access to Hugging Face Spaces

### Running the Application
```bash
python app.py
```
The application runs on:
- Host: 0.0.0.0
- Port: 7860

### Environment Setup
1. Install Flask: `pip install flask`
2. Run the application
3. Access via browser at `http://localhost:7860`

## Maintenance

### Adding New Spaces
1. Edit the `CATEGORIES` dictionary in app.py
2. Add Hugging Face Space URLs to appropriate categories
3. Restart the application

### Updating Blocked Domains
Add domains to the `BLOCKED_DOMAINS` list if they block iframe embedding

### Modifying Grid Layout
- Change `per_page` parameter in API calls
- Update CSS grid columns in index.html
- Adjust card heights as needed

## Troubleshooting

### Common Issues

1. **Spaces not loading in iframes**
   - Check if domain is blocked
   - Verify Hugging Face Space URL format
   - Add to screenshot fallback list if needed

2. **Pagination not working**
   - Verify category has multiple pages of content
   - Check JavaScript console for errors

3. **Styling issues**
   - Clear browser cache
   - Check for CSS conflicts
   - Verify responsive breakpoints

## Future Enhancements

Potential improvements:
- Search functionality across all categories
- User favorites/bookmarks
- Rating system for spaces
- Category filtering and sorting
- Performance metrics and analytics
- Caching for improved load times
- Admin interface for managing spaces

## License and Attribution

This application aggregates publicly available Hugging Face Spaces. Individual spaces maintain their own licenses and terms of use. Users should review and comply with the terms of each integrated space.