Unsplash Source Alternative — Quick Start

A self-hosted version of the old (deprecated) Unsplash Source API. Point any <img src="..."> at it and get a real Unsplash photo back.

1. Get a free Unsplash Access Key

1. Go to https://unsplash.com/developers and log in / sign up
2. Click "Your apps" -> "New Application"
3. Accept the terms, name it anything (e.g. "My Source Alt")
4. Copy the Access Key shown on the app's page

Demo apps are limited to 50 requests/hour — plenty for testing and small personal projects. You can apply for production access later if you need more.

2. Install dependencies

pip install flask requests

3. Set your key as an environment variable

WSL / Linux / Mac:

export UNSPLASH_ACCESS_KEY=your_key_here

Windows (cmd):

set UNSPLASH_ACCESS_KEY=your_key_here

(Or just paste it directly into ACCESS_KEY = ... in app.py for local testing — just don't commit that to a public repo.)

4. Run it locally (for testing before you deploy)

python app.py

5. Use it anywhere

<img src="http://localhost:5000/photo?query=cat">
<img src="http://localhost:5000/random/800x600">

Works as a normal image URL in any app, since it just 302-redirects to the real Unsplash CDN link — no JSON parsing needed on the client side.

Endpoints

URL	What it does
/random	Random photo, original size
/random/800x600	Random photo, cropped to 800x600
/photo?query=cat	Random photo matching "cat"
/photo?query=cat&w=800&h=600	Keyword photo, sized

Deploying to Coolify from VS Code

This project now ships with a Dockerfile, so Coolify can build and run it directly — no buildpacks needed.

1. Push it to a git repo

In VS Code's terminal (inside this project folder):

git init
git add .
git commit -m "Unsplash source alternative"

Create an empty repo on GitHub/GitLab (whichever Coolify is connected to), then:

git remote add origin <your-repo-url>
git branch -M main
git push -u origin main

From now on, any git push from VS Code updates this repo, and Coolify can auto-redeploy on push (see step 3).

2. Create the resource in Coolify

1. In Coolify: + New Resource -> Public/Private Git Repository
2. Point it at your repo/branch
3. Build Pack: Dockerfile (Coolify should auto-detect it)
4. Set the Port Coolify exposes to match the container — 3000 (matches the Dockerfile's default) unless you change ENV PORT in the Dockerfile

3. Set the environment variable

In the resource's Environment Variables tab, add:

UNSPLASH_ACCESS_KEY=your_key_here

Mark it as a runtime variable (not build-time) — it's only needed when the app is running, not while building the image.

4. Deploy

Click Deploy. Coolify builds the Dockerfile and starts the container via gunicorn. Once it's up, attach your domain (or use the Coolify-generated one) and test:

https://your-coolify-domain/photo?query=cat

5. Auto-deploy on push (optional)

Enable the webhook Coolify shows you in the resource's Webhooks tab (or turn on its GitHub App integration) so every git push from VS Code triggers a new deploy automatically.