Unsplash & Pexels

Overzicht

Beam biedt een ingebouwde stock foto browser. Gebruikers zoeken via de media library, de API proxied de requests naar Unsplash en Pexels.

Architectuur

Dashboard (media library)
  → GET /stock-photos/search?query=...&provider=unsplash&page=1
  → API Worker proxied naar Unsplash/Pexels API
  → Genormaliseerd response (zelfde schema ongeacht provider)
  → Gebruiker selecteert foto
  → POST /stock-photos/download (Unsplash TOS: tracking verplicht)
  → Foto URL opgeslagen als externe media

API Endpoints

`GET /stock-photos/search`

Parameter	Type	Verplicht	Beschrijving
`query`	string	Ja	Zoekterm
`provider`	`unsplash` \| `pexels`	Ja	Bron
`page`	number	Nee	Pagina (default: 1)

Response: 20 resultaten per pagina.

{
  photos: [{
    id: string
    provider: 'unsplash' | 'pexels'
    width: number
    height: number
    color: string | null
    description: string | null
    tinyUrl: string          // ~200px (thumbnails)
    thumbnailUrl: string     // ~400px
    regularUrl: string       // ~1080px (voor gebruik)
    photographer: string
    photographerUrl: string
    sourceUrl: string        // Link naar origineel
    downloadLocation?: string // Unsplash only (tracking URL)
  }],
  total: number
  totalPages: number
}

`POST /stock-photos/download`

Verplicht voor Unsplash TOS — triggert een download tracking event.

Parameter	Type	Validatie
`downloadLocation`	string	Moet beginnen met `https://api.unsplash.com/`

Provider-specifieke Details

Unsplash

API: https://api.unsplash.com/search/photos
Auth: Authorization: Client-ID {UNSPLASH_ACCESS_KEY}
TOS vereiste: Download tracking bij elke “download” actie
Rate limit: 50 req/uur (demo), 5000 req/uur (productie)
Attributie: Fotograafnaam en link worden opgeslagen

Pexels

API: https://api.pexels.com/v1/search
Auth: Authorization: {PEXELS_API_KEY}
Rate limit: 200 req/uur
Attributie: Fotograafnaam en link worden opgeslagen

Graceful Degradation

Bij rate limits (403/429) of API errors:

Response bevat error veld met generieke melding
Dashboard toont “Geen resultaten gevonden” — geen technische foutmelding
Andere provider blijft beschikbaar

Environment Variables

Variabele	Waar	Type
`UNSPLASH_ACCESS_KEY`	API Worker	Secret
`PEXELS_API_KEY`	API Worker	Secret