{"id":50369953,"url":"https://github.com/riadvice/placepix","last_synced_at":"2026-05-30T06:30:26.736Z","repository":{"id":359914366,"uuid":"1247992048","full_name":"riadvice/placepix","owner":"riadvice","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-24T04:01:54.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T05:23:53.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riadvice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T03:37:29.000Z","updated_at":"2026-05-24T04:01:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/riadvice/placepix","commit_stats":null,"previous_names":["riadvice/placepix"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/riadvice/placepix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riadvice%2Fplacepix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riadvice%2Fplacepix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riadvice%2Fplacepix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riadvice%2Fplacepix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riadvice","download_url":"https://codeload.github.com/riadvice/placepix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riadvice%2Fplacepix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33682998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T06:30:26.156Z","updated_at":"2026-05-30T06:30:26.728Z","avatar_url":"https://github.com/riadvice.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"static/logo.svg\" alt=\"PlacePix Logo\" width=\"200\"/\u003e\n\n  # PlacePix\n\n  A self-hosted placeholder image server inspired by [picsum.photos](https://picsum.photos).\n\n  Serve random images with on-the-fly resizing, filtering, and formatting.\n\n  **Live:** [placepix.net](https://placepix.net) · **Guide:** [placepix.net/guide](https://placepix.net/guide) · **Made by [RIADVICE](https://riadvice.com)**\n\n  ---\n\u003c/div\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Release](https://img.shields.io/github/v/release/riadvice/placepix)](https://github.com/riadvice/placepix/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/riadvice/placepix?logo=docker)](https://hub.docker.com/r/riadvice/placepix)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?logo=python\u0026logoColor=white)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-009485?logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com)\n[![OpenCV](https://img.shields.io/badge/OpenCV-5C3EE8?logo=opencv\u0026logoColor=white)](https://opencv.org)\n[![Pillow](https://img.shields.io/badge/Pillow-9cf?logo=pillow\u0026logoColor=white)](https://pillow.readthedocs.io)\n[![codecov](https://codecov.io/gh/riadvice/placepix/branch/master/graph/badge.svg)](https://codecov.io/gh/riadvice/placepix)\n[![Website](https://img.shields.io/badge/Website-placepix.net-0ea5e9)](https://placepix.net)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Friadvice%2Fplacepix.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Friadvice%2Fplacepix?ref=badge_shield)\n\n## Contents\n\n- [Features](#features)\n- [Get Started in 5 Steps](#get-started-in-5-steps)\n- [URL Examples](#url-examples)\n- [Developer Guide](https://placepix.net/guide) — full API reference \u0026 feature documentation\n- [Environment Variables](#environment-variables)\n- [API](#api)\n- [Development](#development)\n- [License](#license)\n\n## Features\n\n- **On-the-fly resizing** — `/300/200` with `crop`, `cover`, `scale`, `contain`, or `smart` (OpenCV face detection)\n- **Filters \u0026 effects** — grayscale, blur, sepia, noise, pixelate, tint, brightness, contrast, saturation\n- **Multiple formats** — JPEG, PNG, WebP, AVIF\n- **Solid color placeholders** — `/solid/500/300/ff0000` with optional text overlay\n- **Aspect ratio sizing** — `/ratio/16:9/1080`\n- **Preset dimensions** — Instagram, YouTube, Facebook, and more\n- **Orientation filtering** — `?orientation=landscape|portrait|squarish` to filter by native aspect ratio\n- **Watermark overlay** — image or text with positioning and opacity\n- **Srcset generation** — responsive image sets via `/api/srcset`\n- **Upload API** — add images via `POST /api/upload`\n- **Admin dashboard** — password-protected usage metrics\n- **Browser caching** — ETag, Last-Modified, 304 responses\n- **S3 storage** — optional S3-compatible backend for images\n- **AI generation (experimental)** — OVHcloud AI Endpoints integration\n\n## Get Started in 5 Steps\n\n1. **Install Docker**\n   ```bash\n   docker build -t placepix .\n   ```\n\n2. **Add your images**\n   ```bash\n   mkdir -p images/nature images/people\n   cp ~/photos/*.jpg images/nature/\n   ```\n\n3. **Run the server**\n   ```bash\n   docker run -d -p 3000:3000 -v $(pwd)/images:/app/images --name placepix placepix\n   ```\n   Or use `docker-compose up -d`.\n\n4. **Open the UI**\n   Visit `http://localhost:3000` to browse and build URLs.\n\n5. **Use it in your HTML**\n   ```html\n   \u003cimg src=\"http://localhost:3000/300/200/nature\" /\u003e\n   ```\n\n## URL Examples\n\n```\nGET /300/200                    # Random image, 300x200\nGET /300/200.webp               # WebP format\nGET /300/200/nature             # From \"nature\" category\nGET /300/200?grayscale=true     # With filter\nGET /300/200?text=Hello         # With text overlay\nGET /300/200?orientation=landscape  # Filter by native aspect ratio\nGET /ratio/16:9/1080            # Aspect ratio sizing\nGET /preset/instagram-square    # Preset dimensions\nGET /solid/500/300/ff0000       # Solid color placeholder\n```\n\n**Full reference:** Visit `/url-builder` on your running instance for an interactive explorer.\n\n## Environment Variables\n\nCopy `.env.example` to `.env` and set what you need:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HOST` | Bind address | `127.0.0.1:3000` |\n| `IMAGES_DIR` | Images folder | `./images` |\n| `CACHE` | Enable file cache | `true` |\n| `CDN` | CDN base URL | — |\n| `MAX_WIDTH` / `MAX_HEIGHT` | Size limits | `2000` |\n| `UPLOAD_ENABLED` | Allow API uploads | `true` |\n| `WATERMARK_ENABLED` | Show watermark | `false` |\n| `WATERMARK_TEXT` / `WATERMARK_IMAGE` | Watermark content | — |\n| `WATERMARK_POSITION` | `top-left`, `bottom-right`, etc. | `bottom-right` |\n| `GA_TRACKING_ID` | Google Analytics ID | — |\n| `PRIVACY_POLICY_URL` | Legal link | — |\n| `S3_ENABLED` | Use S3-compatible storage | `false` |\n| `AI_GENERATION_ENABLED` | Auto-generate images via AI | `false` |\n| `ORIENTATION_SQUARISH_TOLERANCE` | Tolerance for squarish filter (0.15 = 15%) | `0.15` |\n\n## API\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/categories` | List categories |\n| `GET /api/images` | List all images |\n| `GET /api/info/id/{id}` | Image metadata |\n| `GET /api/srcset?id={id}\u0026sizes=...` | Responsive srcset JSON |\n| `POST /api/upload` | Upload an image |\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\nRequires **Python 3.12+**. On Linux you may need OpenCV system libs:\n```bash\nsudo apt-get install libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friadvice%2Fplacepix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friadvice%2Fplacepix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friadvice%2Fplacepix/lists"}