# Photos API
> Real stock photography as an API, powered by Lorem Picsum. Browse a curated catalogue of high-resolution photos with their author and dimensions, look up any photo by id, or build a ready-to-embed image URL on the fly — pick a width and height and get a random photo, pass a seed for a stable deterministic image (the same seed always returns the same photo, ideal for consistent placeholders per user or item), or target a specific photo by id, with optional grayscale and blur. No accounts, no attribution headaches: every image is a clean, hotlinkable URL. Perfect for mockups and design comps, blog and CMS placeholders, app prototypes, test fixtures and any layout that needs real imagery instead of grey boxes.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/photos-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 180,000 calls/Mo, 8 req/s
- **Pro** ($11/Mo) — 850,000 calls/Mo, 20 req/s
- **Mega** ($31/Mo) — 3,500,000 calls/Mo, 50 req/s

## Endpoints

### Photos

#### `GET /v1/list` — A page of curated photos

**Parameters:**
- `page` (query, optional, string) — Page number (default 1) Example: `1`
- `limit` (query, optional, string) — Photos per page (1-100, default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photos-api/v1/list?page=1&limit=30"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 30,
        "photos": [
            {
                "id": "0",
                "width": 5000,
                "author": "Alejandro Escamilla",
                "height": 3333,
                "source_url": "https://unsplash.com/photos/yC-Yzbqy7PY",
                "download_url": "https://picsum.photos/id/0/5000/3333"
            },
            {
                "id": "1",
                "width": 5000,
                "author": "Alejandro Escamilla",
                "height": 3333,
                "source_url": "https://unsplash.com/photos/LNRyGwIJr5c",
                "download_url": "https://picsum.photos/id/1/5000/3333"
            },
            {
                "id": "2",
                "width": 5000,
                "author": "Alejandro Escamilla",
                "height": 3333,
                "source_url": "https://unsplash.com/photos/N7XodRrbzS0",
                "download_url": "https://picsum.photos/id/2/5000/3333"
            },
            {
                "id": "3",
                "width": 5000,
                "author": "Alejandro Escamilla",
                "height": 3333,
                "source_url": "https://unsplash.com/photos/Dl6jeyfihLk",
                "download_url": "https://picsum.photos/id/3/5000/3333"
            },
            {
                "id": "4",
                "width": 5000,
                "author": "Alejandro Escamilla",
                "height": 3333,
                "source
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/photo` — A photo's info by id

**Parameters:**
- `id` (query, required, string) — Photo id, e.g. 237 Example: `237`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photos-api/v1/photo?id=237"
```

**Response:**
```json
{
    "data": {
        "photo": {
            "id": "237",
            "width": 3500,
            "author": "André Spieker",
            "height": 2095,
            "source_url": "https://unsplash.com/photos/8wTPqxlnKM4",
            "download_url": "https://picsum.photos/id/237/3500/2095"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:36.583Z",
        "request_id": "351843ec-8e7c-4eaf-bcc1-d5044f8dc868"
    },
    "status": "ok",
    "message": "Photo retrieved",
    "success": true
}
```

#### `GET /v1/url` — Build a placeholder-photo URL

**Parameters:**
- `width` (query, optional, string) — Width in px (1-5000, default 600) Example: `600`
- `height` (query, optional, string) — Height in px (1-5000, default = width) Example: `400`
- `seed` (query, optional, string) — Seed for a deterministic image (same seed = same photo) Example: `oanor`
- `id` (query, optional, string) — Target a specific photo id
- `grayscale` (query, optional, string) — true for a grayscale image
- `blur` (query, optional, string) — Blur amount 1-10

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photos-api/v1/url?width=600&height=400&seed=oanor"
```

**Response:**
```json
{
    "data": {
        "url": "https://picsum.photos/seed/oanor/600/400",
        "blur": null,
        "mode": "seeded (deterministic)",
        "seed": "oanor",
        "width": 600,
        "height": 400,
        "photo_id": null,
        "grayscale": false,
        "resolved_url": null
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:36.693Z",
        "request_id": "757a1640-b54b-4569-b91f-ae37ac778208"
    },
    "status": "ok",
    "message": "Photo URL built",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Source & usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photos-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Real stock photography. /v1/list = a page of curated photos (author, dimensions, download URL); /v1/photo = a photo's info by id (e.g. id=237); /v1/url = build a ready-to-embed photo URL by size, with seed= for a deterministic image, id= for a specific photo, or neither for random — plus optional grayscale and blur=1-10. Photos are CC-licensed via Unsplash, served by Lorem Picsum.",
        "source": "Lorem Picsum (picsum.photos)",
        "endpoints": [
            "/v1/list",
            "/v1/photo",
            "/v1/url",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:36.765Z",
        "request_id": "e5cf221e-e33f-456a-bb8c-4c6ad39b8f79"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/photos-api
OpenAPI spec: https://www.oanor.com/api/photos-api/openapi.json