feat: add set_provider_headers for BYOK switching, include 12_veo in run_all

- Client.set_provider_headers(): update BYOK keys (fal/replicate/runway) for subsequent requests
- _common.set_provider_headers(): wrapper for examples
- run_all_capabilities: add 12_veo_from_catalog.py (SDK→API→Fal flow)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: uzunenes

examples/12_veo_from_catalog.py

@@ -0,0 +1,89 @@
+"""
+Step 12: Video with Veo from catalog.
+
+Flow:
+  1. get_models(provider="fal", model_type="video") from API (database).
+  2. Filter models whose id/name contains "veo".
+  3. Pick the newest by first_seen_at.
+  4. Call videos.generate with that model; write result to sample_outputs.
+
+Requires: VISGATE_API_KEY. Optional: VISGATE_FAL_API_KEY for BYOK.
+  cd examples && python 12_veo_from_catalog.py
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+from _common import create_client
+
+OUTPUT_DIR = Path(__file__).resolve().parent / "sample_outputs"
+OUTPUT_VIDEO = OUTPUT_DIR / "istanbul.mp4"
+PROMPT = "Cinematic drone over Istanbul at golden hour, Bosphorus and minarets, 4k"
+DURATION = 6.0
+FALLBACK_MODEL = "fal-ai/veo3"
+
+
+def pick_newest_veo(models_response):
+    """Filter models containing 'veo' in id/name, sort by first_seen_at (newest first), return first."""
+    veo = [
+        m
+        for m in models_response.models
+        if m
+        and ("veo" in (m.id or "").lower() or "veo" in (m.name or "").lower())
+    ]
+    if not veo:
+        return None
+    # Newest first (first_seen_at desc; None last)
+    veo.sort(key=lambda m: m.first_seen_at or "", reverse=True)
+    return veo[0].id
+
+
+def download_url(url: str, path: Path, timeout: float = 120.0) -> None:
+    with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        r = client.get(url)
+        r.raise_for_status()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(r.content)
+
+
+def main() -> None:
+    client = create_client()
+
+    # 1. Get video models from API (database), newest first
+    resp = client.models.list(
+        provider="fal",
+        model_type="video",
+        sort="newest",
+        limit=100,
+    )
+    model_id = pick_newest_veo(resp)
+    if not model_id:
+        model_id = FALLBACK_MODEL
+        print(f"  No Veo in catalog; using fallback {model_id}")
+    else:
+        print(f"  Using newest Veo from catalog: {model_id}")
+
+    # 2. Generate video via Visgate API
+    print(f"  Generating video (prompt={PROMPT[:50]}...) ...")
+    # Note: Veo expects duration as "4s"/"6s"/"8s". Visgate API should convert
+    # duration_seconds to that format. If validation fails, try another provider.
+    result = client.videos.generate(
+        model=model_id,
+        prompt=PROMPT,
+        duration_seconds=6.0,
+    )
+    if not result.video_url:
+        print("  No video_url in response.")
+        return
+    print(f"  Got video_url")
+
+    # 3. Write to sample_outputs
+    download_url(result.video_url, OUTPUT_VIDEO)
+    print(f"  Written {OUTPUT_VIDEO}")
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

examples/_common.py

@@ -36,6 +36,21 @@ def create_client() -> Client:
     )
 
 
+def set_provider_headers(
+    client: Client,
+    *,
+    fal_key: Optional[str] = None,
+    replicate_key: Optional[str] = None,
+    runway_key: Optional[str] = None,
+) -> None:
+    """Update client BYOK headers. Omit args for managed mode (no BYOK)."""
+    client.set_provider_headers(
+        fal_key=fal_key,
+        replicate_key=replicate_key,
+        runway_key=runway_key,
+    )
+
+
 def provider_key(provider: str) -> Optional[str]:
     """Resolve a BYOK provider key from environment."""
     env_map = {

examples/run_all_capabilities.py

@@ -25,6 +25,7 @@
     "09_provider_keys.py",     # provider keys list + validate
     "10_api_keys.py",          # GET /api-keys
     "11_billing_readonly.py",  # GET billing/stats, info, pricing
+    "12_veo_from_catalog.py",  # Veo from catalog (SDK→API→Fal)
 ]
 
 

src/visgate_sdk/client.py

@@ -158,6 +158,9 @@ def __init__(
         self.api_key = _resolve_api_key(api_key)
         self.base_url = base_url.rstrip("/")
         self.max_retries = max_retries
+        self._fal_key = fal_key
+        self._replicate_key = replicate_key
+        self._runway_key = runway_key
 
         self._client = httpx.Client(
             base_url=self.base_url,
@@ -203,6 +206,33 @@ def generate(
         """
         return self._generate(prompt=prompt, model=model, params=params)
 
+    def set_provider_headers(
+        self,
+        *,
+        fal_key: Optional[str] = None,
+        replicate_key: Optional[str] = None,
+        runway_key: Optional[str] = None,
+    ) -> None:
+        """Update BYOK provider keys for subsequent requests.
+
+        Omitted keys are set to None (managed mode). Pass a key to use BYOK for that provider.
+        """
+        self._fal_key = fal_key or None
+        self._replicate_key = replicate_key or None
+        self._runway_key = runway_key or None
+        # Rebuild the underlying httpx client with new headers
+        self._client.close()
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=httpx.Timeout(DEFAULT_TIMEOUT),
+            headers=_build_headers(
+                self.api_key,
+                fal_key=self._fal_key,
+                replicate_key=self._replicate_key,
+                runway_key=self._runway_key,
+            ),
+        )
+
     def health(self) -> Dict[str, Any]:
         """Check API health status.