added byok and replicate

.env.example

@@ -1,7 +1,8 @@
 # Copy this file to .env for local development (never commit .env itself).
-# On Hugging Face Spaces, set these as Space secrets instead - they are
-# injected directly into the environment and .env is not used there.
-
-# fal.ai API key, used by both the ltx-2-fal and wan2.1-i2v-720p-fal
-# providers configured in providers.py. Get one at https://fal.ai/dashboard/keys
-FAL_KEY=your_fal_api_key_here
+#
+# NOTE: provider API keys (fal.ai, Replicate, ...) are BYOK - each user
+# enters their own key(s) in the app UI, persisted in browser localStorage.
+# They are NOT read from this file or the server environment; nothing
+# provider-related belongs here. This file is only for non-provider local
+# config, e.g.:
+# LOG_LEVEL=DEBUG

DEVELOPER.md

@@ -4,22 +4,23 @@ This documents how local development differs from running on the Hugging
 Face Space, since a few things (persistent storage, secrets) work
 differently in each environment.
 
-## Environment variables / API tokens
-
-- **On the Space**: set provider tokens (e.g. `FAL_KEY`) as [Space secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets).
-  They are injected directly into the process environment - no extra setup
-  needed.
-- **Locally**: copy [.env.example](.env.example) to `.env` and fill in real
-  values. `app.py` calls `load_dotenv()` on startup, which loads `.env` into
-  the environment (without overriding any variable that's already set, so
-  Space secrets always win if both happen to be present).
-- `.env` is gitignored and must never be committed. `.env.example` is the
-  template that *is* committed.
+## Provider API tokens (BYOK)
+
+- Every provider is **bring-your-own-key**: each user pastes their own API
+  key(s) into the UI. Keys are persisted in the browser's `localStorage` and
+  sent to the server only transiently, as part of each generation request -
+  they are never read from the server environment and never written to
+  disk by this app.
 - Each `ModelProvider` in [providers.py](providers.py) declares its own
-  `api_token_env` (the env var name to read at call time), so different
-  providers can use different tokens. The two configured fal.ai providers
-  both read `FAL_KEY` (fal's own standard key name), since one fal.ai key
-  covers all fal-hosted models.
+  `api_token_env` (just a label identifying which key it needs, e.g.
+  `FAL_KEY` or `REPLICATE_API_TOKEN` - not an actual env var read at
+  runtime). `app.py` derives one key input field per distinct
+  `api_token_env` automatically (`TOKEN_ENVS` in [app.py](app.py)), so
+  adding a new provider with a new `api_token_env` adds its input field
+  with no other UI changes needed. Providers that share an `api_token_env`
+  (e.g. the two fal.ai providers both use `FAL_KEY`) share one input field.
+- `.env` / `load_dotenv()` still exist for non-provider local config (e.g.
+  `LOG_LEVEL`), but no longer carry provider API keys.
 
 ## Persistent storage (`/data`)
 
@@ -47,8 +48,10 @@ Then open the printed local URL (e.g. `http://127.0.0.1:7860`).
 ## Adding a new model provider
 
 Add a `ModelProvider(...)` entry to `PROVIDERS` in [providers.py](providers.py).
-Reuse `fal_queue_call` if the new model is also on fal.ai, or write a new
-`call` function matching the signature `(provider, image_path) -> bytes` for
-providers with a different API contract (see `generic_sync_call` and
-`polling_call` for templates of direct-response vs. job-polling contracts).
-No subclassing is needed - the `call` field is what makes this duck-typed.
+Reuse `fal_queue_call` if the new model is also on fal.ai, `replicate_call` if
+it's on Replicate, or write a new `call` function matching the signature
+`(provider, image_path) -> bytes` for providers with a different API contract
+(see `generic_sync_call` and `polling_call` for templates of direct-response
+vs. job-polling contracts). No subclassing is needed - the `call` field is
+what makes this duck-typed. Give the provider an `api_token_env` label (new
+or reused) - the UI picks up a BYOK input field for it automatically.

app.py

@@ -4,11 +4,9 @@ provider concurrently, and preview each provider's generated video.
 Every run (input image + per-provider output videos + metadata) is
 persisted under /data so past runs can be shown in the history section.
 
-Provider API tokens are read from the process environment. On a Hugging
-Face Space, secrets configured in the Space settings are injected directly
-into the environment. For local development, load_dotenv() below reads a
-.env file (if present) into the environment; it never overrides variables
-that are already set, so Space secrets always take priority.
+Provider API keys are BYOK: each browser user supplies their own key(s) in
+the UI. Keys are persisted in browser localStorage and are never written to
+disk by this server.
 """
 
 from __future__ import annotations
@@ -17,8 +15,11 @@ import dataclasses
 import logging
 import os
 import time
+import warnings
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
+os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
+
 import gradio as gr
 from dotenv import load_dotenv
 
@@ -36,6 +37,15 @@ from runs import (
 
 load_dotenv()
 
+warnings.filterwarnings(
+    "ignore",
+    message=".*HTTP_422_UNPROCESSABLE_ENTITY.*",
+    category=DeprecationWarning,
+    module=r"gradio\.routes",
+)
+
+TOKEN_ENVS = sorted({provider.api_token_env for provider in PROVIDERS})
+
 logging.basicConfig(
     level=os.environ.get("LOG_LEVEL", "INFO").upper(),
     format="%(asctime)s %(levelname)s %(name)s: %(message)s",
@@ -106,22 +116,68 @@ def format_result_metadata(result: RunResult) -> str:
     return "\n".join(lines)
 
 
-def on_submit(image_path, prompt, history):
+def on_submit(image_path, prompt, history, *dynamic_inputs):
     if not image_path:
         raise gr.Error("Please upload an image first.")
 
+    token_values = list(dynamic_inputs[: len(TOKEN_ENVS)])
+    enabled_values = list(dynamic_inputs[len(TOKEN_ENVS) :])
+
+    token_map = {
+        token_env: (token_value.strip() if isinstance(token_value, str) else "")
+        for token_env, token_value in zip(TOKEN_ENVS, token_values)
+    }
+
+    selected_providers = [provider for provider, enabled in zip(PROVIDERS, enabled_values) if enabled]
+    if not selected_providers:
+        raise gr.Error("Select at least one model to run.")
+
+    missing_token_envs = sorted(
+        {
+            provider.api_token_env
+            for provider in selected_providers
+            if not token_map.get(provider.api_token_env)
+        }
+    )
+    if missing_token_envs:
+        missing_label = ", ".join(missing_token_envs)
+        raise gr.Error(f"Missing required API key(s): {missing_label}")
+
+    selected_runtime_providers = [
+        dataclasses.replace(provider, api_token_value=token_map.get(provider.api_token_env, ""))
+        for provider in selected_providers
+    ]
+
     run_id, run_dir, input_path = create_run(image_path)
-    logger.info("Run %s: created (providers=%d, prompt=%r)", run_id, len(PROVIDERS), bool(prompt))
+    logger.info(
+        "Run %s: created (selected_providers=%d total_providers=%d, prompt=%r)",
+        run_id,
+        len(selected_runtime_providers),
+        len(PROVIDERS),
+        bool(prompt),
+    )
     provider_index = {provider.name: i for i, provider in enumerate(PROVIDERS)}
     results_by_name: dict[str, RunResult] = {}
+    selected_names = {provider.name for provider in selected_runtime_providers}
 
-    metadata_values = [
-        format_metadata(_effective_provider(provider, prompt), "running") for provider in PROVIDERS
-    ]
+    metadata_values = []
+    for provider in PROVIDERS:
+        if provider.name in selected_names:
+            metadata_values.append(format_metadata(_effective_provider(provider, prompt), "running"))
+        else:
+            metadata_values.append(format_metadata(_effective_provider(provider, prompt), "skipped"))
+            results_by_name[provider.name] = RunResult(
+                provider_name=provider.name,
+                output_path=None,
+                status="skipped",
+                error=None,
+                duration_seconds=0.0,
+                params_used=provider.params,
+            )
     video_values = [None] * len(PROVIDERS)
     yield metadata_values + video_values + [history]
 
-    for provider, video_bytes, error, duration in run_providers(PROVIDERS, image_path, prompt):
+    for provider, video_bytes, error, duration in run_providers(selected_runtime_providers, image_path, prompt):
         index = provider_index[provider.name]
 
         if error is None:
@@ -169,6 +225,18 @@ with gr.Blocks(title="Kaleidoscope") as demo:
         "Upload an image to generate a short video with each configured provider."
     )
 
+    gr.Markdown("## API Keys (BYOK)")
+    gr.Markdown("Keys are saved in your browser local storage and never persisted by this server.")
+    token_inputs = []
+    for token_env in TOKEN_ENVS:
+        token_inputs.append(
+            gr.Textbox(
+                label=token_env,
+                placeholder=f"Enter {token_env}",
+                type="password",
+            )
+        )
+
     image_input = gr.Image(type="filepath", label="Input image")
     prompt_input = gr.Textbox(
         label="Prompt (optional)",
@@ -177,14 +245,19 @@ with gr.Blocks(title="Kaleidoscope") as demo:
     submit_btn = gr.Button("Submit", variant="primary")
 
     gr.Markdown("## Results")
+    check_all_btn = gr.Button("Check all models")
+    enabled_components = []
     metadata_components = []
     video_components = []
     for provider in PROVIDERS:
         with gr.Row():
-            with gr.Column(scale=1):
-                metadata_components.append(gr.Markdown(format_metadata(provider, "idle")))
-            with gr.Column(scale=2):
-                video_components.append(gr.Video(label=provider.name))
+            enabled_components.append(gr.Checkbox(label="Use", value=True))
+            with gr.Accordion(label=provider.name, open=False):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        metadata_components.append(gr.Markdown(format_metadata(provider, "idle")))
+                    with gr.Column(scale=2):
+                        video_components.append(gr.Video(label=provider.name))
 
     gr.Markdown("## Past runs")
     # Start empty and populate via demo.load() below, so every new page
@@ -193,6 +266,43 @@ with gr.Blocks(title="Kaleidoscope") as demo:
     history_state = gr.State([])
     demo.load(load_runs, outputs=history_state)
 
+    storage_keys = [f"kaleidoscope.byok.{token_env.lower()}" for token_env in TOKEN_ENVS]
+    if token_inputs:
+        # Gradio's JS-return convention mirrors Python fn returns: with exactly
+        # one output, return the bare value (not wrapped in an array); with
+        # multiple outputs, return an array of values in output order.
+        # Returning a 1-element array for a single output corrupts that
+        # component's internal block registry (it gets replaced by the raw
+        # list), crashing later interactions with
+        # "'list' object has no attribute 'stateful'" - so the single- and
+        # multi-output cases must be built differently below.
+        if len(token_inputs) == 1:
+            load_js = f"() => localStorage.getItem('{storage_keys[0]}') || ''"
+        else:
+            load_js = (
+                "() => ["
+                + ", ".join(f"localStorage.getItem('{key}') || ''" for key in storage_keys)
+                + "]"
+            )
+        demo.load(fn=None, inputs=None, outputs=token_inputs, js=load_js)
+
+    for storage_key, token_input in zip(storage_keys, token_inputs):
+        token_input.change(
+            fn=None,
+            inputs=[token_input],
+            outputs=[],
+            js=f"(value) => localStorage.setItem('{storage_key}', value || '')",
+        )
+
+    check_all_btn.click(
+        # A bare `True` (not a list) when there's exactly one output, else a
+        # list matching the output count - see the load_js comment above for
+        # why this distinction matters.
+        fn=(lambda: True) if len(enabled_components) == 1 else (lambda: [True] * len(enabled_components)),
+        inputs=None,
+        outputs=enabled_components,
+    )
+
     @gr.render(inputs=history_state)
     def render_history(history):
         if not history:
@@ -213,7 +323,7 @@ with gr.Blocks(title="Kaleidoscope") as demo:
 
     submit_btn.click(
         on_submit,
-        inputs=[image_input, prompt_input, history_state],
+        inputs=[image_input, prompt_input, history_state] + token_inputs + enabled_components,
         outputs=metadata_components + video_components + [history_state],
     )
 

providers.py

@@ -11,30 +11,89 @@ provider instance, which is how providers with different API contracts
 from __future__ import annotations
 
 import base64
+import io
 import logging
 import mimetypes
-import os
 import time
 from dataclasses import dataclass, field
 from typing import Callable
 
 import requests
+from PIL import Image, ImageOps
 
 logger = logging.getLogger(__name__)
 
+# fal.ai's wan-i2v endpoint only supports these fixed aspect ratios; passing
+# "auto" can resolve to an unsupported computed size (422) for some input
+# image dimensions, so "auto" in a provider's params is a sentinel meaning
+# "pick the closest of these from the actual uploaded image" (see
+# _closest_supported_aspect_ratio below).
+_SUPPORTED_ASPECT_RATIOS = {
+    "16:9": 16 / 9,
+    "9:16": 9 / 16,
+    "1:1": 1.0,
+}
+
+_MIME_TO_PIL_FORMAT = {
+    "image/jpeg": "JPEG",
+    "image/png": "PNG",
+    "image/webp": "WEBP",
+}
+
+
+def _load_oriented_image(image_path: str) -> Image.Image:
+    """Opens `image_path` and bakes in its EXIF orientation, if any.
+
+    Phone photos are frequently stored with a raw pixel buffer in one
+    orientation plus an EXIF "Orientation" tag telling viewers to rotate it
+    (e.g. a portrait photo stored as landscape pixels + "rotate 90"). Image
+    viewers and Gradio's own preview apply that tag automatically, but a
+    naive `Image.open(...).size` read (and the raw bytes sent to fal.ai)
+    does not - so without correcting for it here, the aspect ratio we
+    compute and the pixels we send to the video model both end up
+    reflecting the wrong (physical, not visual) orientation, producing a
+    sideways video.
+    """
+    image = Image.open(image_path)
+    return ImageOps.exif_transpose(image) or image
+
+
+def _closest_supported_aspect_ratio(image_path: str) -> str:
+    with _load_oriented_image(image_path) as image:
+        width, height = image.size
+    ratio = width / height if height else 1.0
+    return min(_SUPPORTED_ASPECT_RATIOS, key=lambda label: abs(_SUPPORTED_ASPECT_RATIOS[label] - ratio))
+
+
+def _format_http_error(response: requests.Response) -> str:
+    """Builds a concise, useful error from an HTTP response body."""
+    try:
+        body = response.json()
+    except ValueError:
+        text = (response.text or "").strip()
+        return text or f"HTTP {response.status_code}"
+
+    if isinstance(body, dict):
+        for key in ("detail", "error", "message"):
+            value = body.get(key)
+            if value:
+                return str(value)
+    return str(body)
+
 
 @dataclass
 class ModelProvider:
     name: str
     api_url: str
     api_token_env: str
+    api_token_value: str = ""
     params: dict = field(default_factory=dict)
     call: Callable[["ModelProvider", str], bytes] = None
 
     @property
     def api_token(self) -> str:
-        """Reads the provider's API token from the Space environment at call time."""
-        return os.environ.get(self.api_token_env, "")
+        """Returns the per-request API token supplied by the current browser user."""
+        return self.api_token_value or ""
 
 
 def generic_sync_call(provider: ModelProvider, image_path: str) -> bytes:
@@ -117,8 +176,15 @@ FAL_QUEUE_BASE = "https://queue.fal.run"
 def _image_to_data_uri(image_path: str) -> str:
     mime_type, _ = mimetypes.guess_type(image_path)
     mime_type = mime_type or "image/png"
-    with open(image_path, "rb") as image_file:
-        encoded = base64.b64encode(image_file.read()).decode("ascii")
+
+    with _load_oriented_image(image_path) as image:
+        pil_format = _MIME_TO_PIL_FORMAT.get(mime_type, image.format or "PNG")
+        if pil_format == "JPEG" and image.mode in ("RGBA", "P"):
+            image = image.convert("RGB")
+        buffer = io.BytesIO()
+        image.save(buffer, format=pil_format)
+
+    encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
     return f"data:{mime_type};base64,{encoded}"
 
 
@@ -141,6 +207,8 @@ def fal_queue_call(
         "Content-Type": "application/json",
     }
     payload = {**provider.params, "image_url": _image_to_data_uri(image_path)}
+    if payload.get("aspect_ratio") == "auto":
+        payload["aspect_ratio"] = _closest_supported_aspect_ratio(image_path)
 
     logger.debug("fal.ai %s: submitting job to %s", provider.name, provider.api_url)
     submit_response = requests.post(
@@ -173,7 +241,12 @@ def fal_queue_call(
         raise TimeoutError(f"fal.ai job for '{provider.name}' timed out after {max_wait_seconds}s")
 
     result_response = requests.get(response_url, headers=headers, timeout=30)
-    result_response.raise_for_status()
+    if not result_response.ok:
+        detail = _format_http_error(result_response)
+        raise RuntimeError(
+            f"fal.ai result fetch failed for '{provider.name}' "
+            f"({result_response.status_code}): {detail}"
+        )
     result = result_response.json()
     video_url = result["video"]["url"]
 
@@ -182,10 +255,102 @@ def fal_queue_call(
     return video_response.content
 
 
-# Registry of configured providers. Both use fal.ai's queue API (submit ->
-# poll -> fetch result) via the shared `fal_queue_call`, authenticated with
-# the same FAL_KEY (fal's standard API key env var). Set FAL_KEY as a secret
-# on the Hugging Face Space, or in a local .env file for development.
+REPLICATE_API_BASE = "https://api.replicate.com/v1"
+
+
+def _extract_replicate_output_url(output) -> str | None:
+    """Normalizes Replicate's `output` field to a single file URL.
+
+    Different model schemas represent a single output file as a bare
+    string URL, a one-item list, or (rarely) a dict with a "url"/"video"
+    key - this isn't a universal contract, just the shapes seen in
+    practice, so adapt if a new provider's schema differs.
+    """
+    if isinstance(output, str):
+        return output
+    if isinstance(output, list) and output:
+        return _extract_replicate_output_url(output[0])
+    if isinstance(output, dict):
+        return output.get("url") or output.get("video")
+    return None
+
+
+def replicate_call(
+    provider: ModelProvider,
+    image_path: str,
+    poll_interval_seconds: float = 2.0,
+    max_wait_seconds: float = 600.0,
+) -> bytes:
+    """Calls a Replicate model via its official REST API (create prediction
+    -> poll -> fetch output), authenticated with the user's own Replicate
+    API token (BYOK).
+
+    `provider.api_url` must be the Replicate model id, e.g.
+    "alibaba/happyhorse-1.1". `provider.params` is sent as the prediction's
+    "input", merged with the uploaded image as a base64 data URI in an
+    "images" array - Replicate's API accepts a data URI directly for
+    file-type inputs, so no public upload step is needed.
+    See https://replicate.com/docs/reference/http for the create/poll
+    prediction contract.
+    """
+    headers = {
+        "Authorization": f"Bearer {provider.api_token}",
+        "Content-Type": "application/json",
+    }
+    payload = {"input": {**provider.params, "images": [_image_to_data_uri(image_path)]}}
+
+    logger.debug("replicate %s: creating prediction for %s", provider.name, provider.api_url)
+    create_response = requests.post(
+        f"{REPLICATE_API_BASE}/models/{provider.api_url}/predictions",
+        headers=headers,
+        json=payload,
+        timeout=30,
+    )
+    if not create_response.ok:
+        detail = _format_http_error(create_response)
+        raise RuntimeError(
+            f"replicate prediction creation failed for '{provider.name}' "
+            f"({create_response.status_code}): {detail}"
+        )
+    prediction = create_response.json()
+    status_url = prediction["urls"]["get"]
+
+    deadline = time.monotonic() + max_wait_seconds
+    while True:
+        status_response = requests.get(status_url, headers=headers, timeout=30)
+        status_response.raise_for_status()
+        prediction = status_response.json()
+        status = prediction.get("status")
+
+        if status == "succeeded":
+            logger.debug("replicate %s: prediction succeeded", provider.name)
+            break
+        if status in ("failed", "canceled"):
+            logger.error("replicate %s: prediction %s: %s", provider.name, status, prediction.get("error"))
+            raise RuntimeError(f"replicate prediction {status} for '{provider.name}': {prediction.get('error')}")
+
+        if time.monotonic() >= deadline:
+            logger.error("replicate %s: prediction timed out after %.0fs", provider.name, max_wait_seconds)
+            raise TimeoutError(f"replicate prediction for '{provider.name}' timed out after {max_wait_seconds}s")
+
+        time.sleep(poll_interval_seconds)
+
+    video_url = _extract_replicate_output_url(prediction.get("output"))
+    if not video_url:
+        raise RuntimeError(f"replicate prediction for '{provider.name}' succeeded but returned no output URL")
+
+    # Per Replicate's docs, output file URLs require the Authorization header
+    # to fetch, unlike fal.ai's (unauthenticated) delivery URLs above.
+    video_response = requests.get(video_url, headers=headers, timeout=180)
+    video_response.raise_for_status()
+    return video_response.content
+
+
+# Registry of configured providers. The fal.ai providers use fal's queue API
+# (submit -> poll -> fetch result) via the shared `fal_queue_call`; the
+# Replicate provider uses Replicate's REST API via `replicate_call`. Every
+# provider is BYOK - the user's API key is supplied at request time in the
+# UI, never read from the server environment.
 PROVIDERS: list[ModelProvider] = [
     ModelProvider(
         name="ltx-2-fal",
@@ -209,7 +374,25 @@ PROVIDERS: list[ModelProvider] = [
             "resolution": "720p",
             "num_frames": 81,
             "frames_per_second": 16,
+            # Resolved to a concrete supported ratio (16:9 / 9:16 / 1:1) from
+            # the actual uploaded image at call time - see
+            # _closest_supported_aspect_ratio.
+            "aspect_ratio": "auto",
         },
         call=fal_queue_call,
     ),
+    ModelProvider(
+        name="happyhorse-1.1-replicate",
+        api_url="alibaba/happyhorse-1.1",
+        api_token_env="REPLICATE_API_TOKEN",
+        params={
+            "prompt": "Animate this image with natural, smooth motion.",
+            "resolution": "1080p",
+            "duration": 5,
+            # No aspect_ratio param: per the model's schema, aspect_ratio only
+            # applies to text-to-video/reference-to-video - for image-to-video
+            # (single image, our case) the image's own aspect ratio is used.
+        },
+        call=replicate_call,
+    ),
 ]

requirements.txt

@@ -1,3 +1,4 @@
 gradio==6.19.0
 requests
 python-dotenv
+Pillow

runs.py

@@ -113,7 +113,10 @@ def load_runs() -> list[Run]:
         try:
             with open(run_path, "r") as run_file:
                 entry = json.load(run_file)
-        except (FileNotFoundError, NotADirectoryError, json.JSONDecodeError, OSError) as exc:
+        except FileNotFoundError:
+            # Legacy/partial run dirs can exist without metadata; skip quietly.
+            continue
+        except (NotADirectoryError, json.JSONDecodeError, OSError) as exc:
             logger.warning("Skipping run %s: could not read %s (%s)", run_id, run_path, exc)
             continue