logimage-generator/docs/superpowers/specs/2026-05-20-pexels-image-source-design.md

Design : intégration Pexels et aiguillage multi-provider

Date : 2026-05-20

Contexte

Le projet dispose déjà d'un port ImageSource (ABC) et d'une implémentation UnsplashImageSource. La clé API Unsplash n'est pas encore disponible ; une clé Pexels est disponible maintenant. L'objectif est d'ajouter le support Pexels et de router automatiquement vers le bon provider selon les variables d'environnement.

Périmètre

• Ajouter PexelsImageSource dans l'infrastructure
• Modifier main.py pour router selon les clés d'API présentes
• Pas de changement au domain, au port, ni au use case

Nouveau fichier : PexelsImageSource

Chemin : src/logimage/infrastructure/image/pexels_source.py

Implémente ImageSource. Deux endpoints selon la présence d'un thème :

• Avec thème : GET https://api.pexels.com/v1/search?query=<theme>&per_page=1
• Sans thème : GET https://api.pexels.com/v1/curated?per_page=1

Authentification : header Authorization: <api_key> (pas de préfixe).

Extraction des données :

• URL image : photo["src"]["large"]
• Titre : photo["alt"] ou theme ou "logimage" en fallback

Modification : routing dans main.py

Remplacer la logique actuelle (Unsplash uniquement) par :

1. Lire PEXELS_API_KEY et UNSPLASH_ACCESS_KEY depuis l'environnement
2. Si PEXELS_API_KEY est présente → instancier PexelsImageSource
3. Sinon si UNSPLASH_ACCESS_KEY est présente → instancier UnsplashImageSource
4. Sinon → afficher une erreur claire et quitter : "Error: set PEXELS_API_KEY or UNSPLASH_ACCESS_KEY in .env"

Pexels est prioritaire car c'est la clé disponible aujourd'hui.

Ce qui ne change pas

• Le port ImageSource reste inchangé
• Le use case GeneratePuzzlesUseCase reste inchangé
• UnsplashImageSource reste inchangé (prêt pour quand la clé sera disponible)