feat(music-lab): cover.py Pexels 이미지 검색 분기 (image_source=pexels)

music-lab/app/pipeline/cover.py

@@ -13,6 +13,7 @@ from .gradient import make_gradient_with_title
 logger = logging.getLogger("music-lab.cover")
 
 DALLE_TIMEOUT_S = 90
+PEXELS_IMG_TIMEOUT_S = 30
 
 
 def _get_api_key() -> str:
@@ -23,13 +24,68 @@ def _get_model() -> str:
     return os.getenv("OPENAI_IMAGE_MODEL", "gpt-image-1")
 
 
+def _get_pexels_key() -> str:
+    return os.getenv("PEXELS_API_KEY", "")
+
+
+async def _generate_with_pexels(genre: str, mood: str, track_title: str,
+                                  out_path: str, keyword_override: str = "") -> bool:
+    """Pexels 이미지 검색·다운로드. 성공 시 True. API key 없거나 0 결과면 False."""
+    api_key = _get_pexels_key()
+    if not api_key:
+        return False
+    keyword = keyword_override or f"{genre} aesthetic background"
+    try:
+        async with httpx.AsyncClient(timeout=PEXELS_IMG_TIMEOUT_S) as client:
+            resp = await client.get(
+                "https://api.pexels.com/v1/search",
+                headers={"Authorization": api_key},
+                params={"query": keyword, "per_page": 5, "orientation": "landscape"},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            photos = data.get("photos", [])
+            if not photos:
+                return False
+            img_url = photos[0]["src"].get("large2x") or photos[0]["src"].get("original")
+            img_resp = await client.get(img_url)
+            img_resp.raise_for_status()
+            with Image.open(BytesIO(img_resp.content)) as src:
+                img = src.convert("RGB")
+            img.save(out_path, "JPEG", quality=92)
+            return True
+    except (httpx.HTTPError, httpx.TimeoutException, KeyError, ValueError, OSError) as e:
+        logger.warning("Pexels 이미지 검색 실패: %s", e)
+        return False
+
+
 async def generate(*, pipeline_id: int, genre: str, prompt_template: str,
-                   mood: str = "", track_title: str = "", feedback: str = "") -> dict:
+                   mood: str = "", track_title: str = "", feedback: str = "",
+                   image_source: str = "ai",
+                   background_keyword: str = "") -> dict:
     """커버 아트 생성. 성공 시 jpg 저장 + URL 반환. 실패 시 그라데이션 폴백.
 
+    image_source: 'ai' (DALL·E 기본) | 'pexels' (스톡 사진).
     반환: {"url": str, "used_fallback": bool, "error": str | None}
     """
     out_path = os.path.join(storage.pipeline_dir(pipeline_id), "cover.jpg")
+
+    if image_source == "pexels":
+        ok = await _generate_with_pexels(genre, mood, track_title, out_path, background_keyword)
+        if ok:
+            return {
+                "url": storage.media_url(pipeline_id, "cover.jpg"),
+                "used_fallback": False,
+                "error": None,
+            }
+        # Pexels 실패 → 그라데이션 폴백
+        make_gradient_with_title(genre, track_title, out_path)
+        return {
+            "url": storage.media_url(pipeline_id, "cover.jpg"),
+            "used_fallback": True,
+            "error": "Pexels 검색 실패 또는 API 키 없음",
+        }
+
     used_fallback = False
     error = None
 

music-lab/tests/test_cover_generation.py

@@ -91,3 +91,59 @@ async def test_dalle_b64_response_handled(tmp_storage, monkeypatch):
                                 prompt_template="x", mood="", track_title="X")
     assert out["used_fallback"] is False
     assert (tmp_storage / "46" / "cover.jpg").exists()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_pexels_image_source(tmp_storage, monkeypatch):
+    monkeypatch.setenv("PEXELS_API_KEY", "test-pexels-key")
+    img_url = "https://images.pexels.com/photos/123/photo.jpg"
+    respx.get("https://api.pexels.com/v1/search").mock(
+        return_value=Response(200, json={
+            "photos": [{
+                "id": 123,
+                "src": {"large2x": img_url, "original": img_url},
+            }],
+        })
+    )
+    png_bytes = bytes.fromhex(
+        "89504e470d0a1a0a0000000d49484452000000010000000108020000009077"
+        "53de0000000c4944415478da6300010000050001"
+        "0d0a2db40000000049454e44ae426082"
+    )
+    respx.get(img_url).mock(return_value=Response(200, content=png_bytes))
+
+    out = await cover.generate(
+        pipeline_id=99, genre="lo-fi", prompt_template="ignored",
+        mood="chill", track_title="Mix",
+        image_source="pexels",
+    )
+    assert out["used_fallback"] is False
+    assert out["url"].endswith("/cover.jpg")
+    assert (tmp_storage / "99" / "cover.jpg").exists()
+
+
+@pytest.mark.asyncio
+async def test_pexels_no_api_key_falls_back(tmp_storage, monkeypatch):
+    monkeypatch.delenv("PEXELS_API_KEY", raising=False)
+    out = await cover.generate(
+        pipeline_id=98, genre="lo-fi", prompt_template="x",
+        mood="", track_title="Test",
+        image_source="pexels",
+    )
+    assert out["used_fallback"] is True
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_pexels_zero_results_falls_back(tmp_storage, monkeypatch):
+    monkeypatch.setenv("PEXELS_API_KEY", "test-key")
+    respx.get("https://api.pexels.com/v1/search").mock(
+        return_value=Response(200, json={"photos": []})
+    )
+    out = await cover.generate(
+        pipeline_id=97, genre="lo-fi", prompt_template="x",
+        mood="", track_title="Test",
+        image_source="pexels",
+    )
+    assert out["used_fallback"] is True