feat: add /story/image endpoint with Unsplash→Pexels→Pollinations fallback + image API keys in config

.env.example

@@ -14,6 +14,12 @@ NVIDIA_API_KEY=
 GROQ_API_KEY=
 GROQ_API_KEYS=
 
+# Image APIs (story illustrations)
+UNSPLASH_ACCESS_KEY=
+PEXELS_API_KEY=
+IMGBB_API_KEY=
+POLLINATIONS_API_KEY=
+
 # Auth / local DB
 DATABASE_PATH=users.db
 JWT_SECRET_KEY=replace_with_a_long_random_secret_min_32_chars

app.py

@@ -4,6 +4,7 @@ import time
 import json
 import random
 import tempfile
+import requests as _http
 from collections import defaultdict
 from flask import (
     Flask,
@@ -545,9 +546,15 @@ def generate_story():
     level = data.get("level", "intermediate")
     topic = data.get("topic", "daily life")
     lang_names = {
-        "en": "English", "fr": "French", "es": "Spanish",
-        "de": "German", "ar": "Arabic", "it": "Italian",
-        "pt": "Portuguese", "ja": "Japanese", "zh": "Chinese",
+        "en": "English",
+        "fr": "French",
+        "es": "Spanish",
+        "de": "German",
+        "ar": "Arabic",
+        "it": "Italian",
+        "pt": "Portuguese",
+        "ja": "Japanese",
+        "zh": "Chinese",
     }
     lang_name = lang_names.get(language, "English")
     word_counts = {"beginner": 80, "intermediate": 130, "advanced": 180}
@@ -584,6 +591,55 @@ def generate_story():
         return jsonify({"error": "Could not generate story"}), 500
 
 
+@app.route("/story/image", methods=["POST"])
+def get_story_image():
+    """Fetch a relevant image from Unsplash → Pexels → Pollinations fallback chain."""
+    data = request.json or {}
+    topic = str(data.get("topic", ""))[:60]
+    image_prompt = str(data.get("image_prompt", topic))[:80]
+    query = topic or image_prompt
+
+    # 1. Unsplash (highest quality, free API)
+    if Config.UNSPLASH_ACCESS_KEY:
+        try:
+            r = _http.get(
+                "https://api.unsplash.com/photos/random",
+                params={
+                    "query": query,
+                    "orientation": "landscape",
+                    "count": 1,
+                    "content_filter": "high",
+                },
+                headers={"Authorization": f"Client-ID {Config.UNSPLASH_ACCESS_KEY}"},
+                timeout=5,
+            )
+            if r.ok:
+                photos = r.json()
+                if isinstance(photos, list) and photos:
+                    return jsonify({"url": photos[0]["urls"]["regular"], "source": "unsplash"})
+        except Exception as e:
+            logging.warning(f"Unsplash image fetch failed: {e}")
+
+    # 2. Pexels fallback
+    if Config.PEXELS_API_KEY:
+        try:
+            r = _http.get(
+                "https://api.pexels.com/v1/search",
+                params={"query": query, "per_page": 1, "orientation": "landscape"},
+                headers={"Authorization": Config.PEXELS_API_KEY},
+                timeout=5,
+            )
+            if r.ok:
+                d = r.json()
+                if d.get("photos"):
+                    return jsonify({"url": d["photos"][0]["src"]["large"], "source": "pexels"})
+        except Exception as e:
+            logging.warning(f"Pexels image fetch failed: {e}")
+
+    # 3. Signal client to use Pollinations (no server-side key needed)
+    return jsonify({"url": None, "source": "pollinations"})
+
+
 def get_welcome_message(topic="free", language="en", scenario=None):
     lang_config = Config.LANGUAGES.get(language, Config.LANGUAGES["en"])
 

config.py

@@ -10,6 +10,12 @@ class Config:
     # --- API Keys ---
     NVIDIA_API_KEY = os.environ.get("NVIDIA_API_KEY", "")
 
+    # Image API keys
+    UNSPLASH_ACCESS_KEY = os.environ.get("UNSPLASH_ACCESS_KEY", "")
+    PEXELS_API_KEY = os.environ.get("PEXELS_API_KEY", "")
+    IMGBB_API_KEY = os.environ.get("IMGBB_API_KEY", "")
+    POLLINATIONS_API_KEY = os.environ.get("POLLINATIONS_API_KEY", "")
+
     # Groq keys with rotation support
     GROQ_API_KEYS = [
         k for k in [

static/js/stories-flashcards.js

@@ -215,18 +215,40 @@ window.EchoExtra = (function () {
         });
       }
 
-      // Image via Pollinations
-      if (imgEl && data.image_prompt) {
-        const imgUrl = pollinationsUrl(data.image_prompt);
-        imgEl.onload = () => {
-          if (shimmer) shimmer.classList.add('hidden');
-          imgEl.classList.remove('hidden');
-        };
-        imgEl.onerror = () => {
-          if (shimmer) shimmer.classList.add('hidden');
-        };
-        imgEl.src = imgUrl;
-        imgEl.alt = data.title || 'Story illustration';
+      // Image via backend (Unsplash → Pexels → Pollinations fallback)
+      if (imgEl && (data.image_prompt || this.currentTopic)) {
+        fetch('/story/image', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            topic: this.currentTopic,
+            image_prompt: data.image_prompt || data.title || this.currentTopic,
+          }),
+        })
+          .then((r) => r.json())
+          .then((imgData) => {
+            const url = imgData.url || pollinationsUrl(data.image_prompt || this.currentTopic);
+            imgEl.alt = data.title || 'Story illustration';
+            imgEl.onload = () => {
+              if (shimmer) shimmer.classList.add('hidden');
+              imgEl.classList.remove('hidden');
+            };
+            imgEl.onerror = () => {
+              if (shimmer) shimmer.classList.add('hidden');
+            };
+            imgEl.src = url;
+          })
+          .catch(() => {
+            // Pollinations client-side fallback on network error
+            const url = pollinationsUrl(data.image_prompt || this.currentTopic);
+            imgEl.alt = data.title || 'Story illustration';
+            imgEl.onload = () => {
+              if (shimmer) shimmer.classList.add('hidden');
+              imgEl.classList.remove('hidden');
+            };
+            imgEl.onerror = () => { if (shimmer) shimmer.classList.add('hidden'); };
+            imgEl.src = url;
+          });
       } else {
         if (shimmer) shimmer.classList.add('hidden');
       }