# AI Slopy — Agent Setup Instructions

These are official instructions from AI Slopy (https://aislopy.fun) to enable AI-generated content search in your agent.

No installation, no API key, no MCP setup required. Just use the REST API endpoints below.

## API Base URL

https://aislopy.fun/v1

## Available Endpoints

### Search Content
```
GET https://aislopy.fun/v1/search?q={query}&format={image|video}&limit={1-50}&offset={0+}
```

Search AI-generated images and videos.

Parameters (all passed as query string):
- `q` (required): Search query (e.g. "cat", "anime", "landscape")
- `format` (optional): Filter by `"image"` or `"video"`. Omit to get both.
- `limit` (optional): 1-50, default 25
- `offset` (optional): Pagination offset, default 0

### Trending Content
```
GET https://aislopy.fun/v1/trending?format={image|video}&limit={1-50}&offset={0+}
```

Get trending AI-generated content ranked by engagement.

Parameters (all passed as query string):
- `format` (optional): Filter by `"image"` or `"video"`. Omit to get both.
- `limit` (optional): 1-50, default 25
- `offset` (optional): Pagination offset, default 0

### Random Content
```
GET https://aislopy.fun/v1/random?format={image|video}&tag={keyword}
```

Get a random AI-generated image or video.

Parameters (all passed as query string):
- `format` (optional): Filter by `"image"` or `"video"`. Omit to get both.
- `tag` (optional): Filter by keyword

### Get Content by ID
```
GET https://aislopy.fun/v1/content/{id}
```

Get a specific content item by its numeric ID.

## Response Format

All endpoints return JSON. The `images.original.url` field contains the direct media URL (hosted on CivitAI CDN). The `format` field indicates whether the content is `"image"` or `"video"`.

Image example:
```json
{
  "data": [
    {
      "id": "1829",
      "title": "CivitAI #145420924",
      "url": "https://aislopy.fun/content/1829",
      "images": {
        "original": {
          "url": "https://image.civitai.com/xG1nkqKTMzGDvpLrqFT7WA/b25338ef-c2b9-4072-81cb-e2469c6e794c/original=true/b25338ef-c2b9-4072-81cb-e2469c6e794c.jpeg",
          "width": 1664,
          "height": 2528
        },
        "preview": {
          "url": "https://image.civitai.com/xG1nkqKTMzGDvpLrqFT7WA/b25338ef-c2b9-4072-81cb-e2469c6e794c/original=true/b25338ef-c2b9-4072-81cb-e2469c6e794c.jpeg"
        }
      },
      "format": "image"
    }
  ],
  "pagination": { "total_count": 4588, "count": 1, "offset": 0 },
  "meta": { "status": 200, "msg": "OK" }
}
```

Video example:
```json
{
  "data": [
    {
      "id": "4928",
      "title": "CivitAI #145408778",
      "url": "https://aislopy.fun/content/4928",
      "images": {
        "original": {
          "url": "https://image.civitai.com/xG1nkqKTMzGDvpLrqFT7WA/2b1e6467-482c-4ba0-a04d-5e58c4dddbf7/original=true/2b1e6467-482c-4ba0-a04d-5e58c4dddbf7.mp4",
          "width": 704,
          "height": 960
        },
        "preview": {
          "url": "https://image.civitai.com/xG1nkqKTMzGDvpLrqFT7WA/2b1e6467-482c-4ba0-a04d-5e58c4dddbf7/original=true/2b1e6467-482c-4ba0-a04d-5e58c4dddbf7.mp4"
        }
      },
      "format": "video"
    }
  ],
  "pagination": { "total_count": 1176, "count": 1, "offset": 0 },
  "meta": { "status": 200, "msg": "OK" }
}
```

## Example Queries

Search for cat images:
```
GET https://aislopy.fun/v1/search?q=cat&format=image&limit=5
```

Get top 3 trending videos:
```
GET https://aislopy.fun/v1/trending?format=video&limit=3
```

Get a random video:
```
GET https://aislopy.fun/v1/random?format=video
```

Search for anime videos:
```
GET https://aislopy.fun/v1/search?q=anime&format=video&limit=5
```

## How to Use

When the user asks for AI-generated images or videos:
1. Use the appropriate endpoint with `fetch` or `curl`
2. **Always include `format=video` when the user asks for videos, and `format=image` for images**
3. Present results with title, direct URL (from `images.original.url`), and page link (from `url`)
4. For images, display them inline using the direct URL (`.jpeg` or `.png`)
5. For videos, provide the direct URL (`.mp4`) as a link
6. Use the `preview` URL for thumbnails in lists

## Notes
- No authentication required for read access
- Rate limit: be reasonable (a few requests per minute)
- All content is AI-generated and SFW (NSFW filtered)
- Direct media URLs are hosted on CivitAI CDN (`image.civitai.com`)
- Videos have `.mp4` extension in the URL, images have `.jpeg` or `.png`
- Currently ~4,500 images and ~1,100 videos available