docs: add sample outputs (images) and fetch script; README references

- examples/sample_outputs/: sunset_istanbul, cat_astronaut, cappadocia_balloons (nice prompts)
- fetch_sample_outputs.py: generate + download images and optional video
- README and examples/README: Sample outputs section with table and images
- sample_outputs/README: prompt list and regenerate instructions

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

Author: uzunenes

README.md

@@ -216,6 +216,22 @@ See the [`examples/`](examples/) directory for tested scripts covering every SDK
 VISGATE_API_KEY=vg-... python examples/run_all_capabilities.py
 ```
 
+### Sample outputs (image & video)
+
+Example results from the API with curated prompts are under [`examples/sample_outputs/`](examples/sample_outputs/). You can regenerate them with:
+
+```bash
+cd examples && python fetch_sample_outputs.py
+```
+
+| Prompt | Output |
+|--------|--------|
+| Golden hour sunset over Istanbul Bosphorus... | ![Sunset Istanbul](examples/sample_outputs/sunset_istanbul.jpg) |
+| A fluffy orange cat astronaut in space... | ![Cat astronaut](examples/sample_outputs/cat_astronaut.jpg) |
+| Cappadocia hot air balloons at dawn... | ![Cappadocia](examples/sample_outputs/cappadocia_balloons.jpg) |
+
+Video (async): run `fetch_sample_outputs.py` to generate a short beach-waves clip; the script saves it to `sample_outputs/beach_waves.mp4` when the URL is ready.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

examples/README.md

@@ -45,3 +45,14 @@ The first two steps run without an API key. `VISGATE_API_KEY` is required from s
 - **Exact cache:** Same model + prompt + size. Second request returns from cache; response includes `cache_hit=True` and `provider_cost_avoided_micro` (cost saved in micro-USD). Run `python examples/07_cache_demo.py`.
 - **Semantic cache:** Similar but different wording; API matches via Vertex AI embedding + Firestore. Second request may return `cache_hit=True` and `provider_cost_avoided_micro`. Run `python examples/08_semantic_cache_demo.py`.
 - Cache is org-scoped by default; see API docs for `VISGATE_CACHE_SCOPE` and TTL.
+
+## Sample outputs
+
+Generated image (and optional video) samples with nice prompts are saved in [`sample_outputs/`](sample_outputs/). To regenerate them:
+
+```bash
+cd examples
+python fetch_sample_outputs.py
+```
+
+Requires `VISGATE_API_KEY` and optionally `VISGATE_FAL_API_KEY`. Outputs: `sunset_istanbul.jpg`, `cat_astronaut.jpg`, `cappadocia_balloons.jpg`, and optionally `beach_waves.mp4` (video may be async).

examples/fetch_sample_outputs.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Generate sample images (and optionally video) with nice prompts and save to
+examples/sample_outputs/. Run with VISGATE_API_KEY and optionally VISGATE_FAL_API_KEY.
+
+  cd examples && python fetch_sample_outputs.py
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+# Add parent for _common
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _common import create_client
+
+OUTPUT_DIR = Path(__file__).resolve().parent / "sample_outputs"
+
+IMAGE_PROMPTS = [
+    ("sunset_istanbul", "Golden hour sunset over Istanbul Bosphorus, minarets and seagulls, cinematic, detailed, 8k"),
+    ("cat_astronaut", "A fluffy orange cat astronaut floating in space, Earth in the background, photorealistic, whimsical"),
+    ("cappadocia_balloons", "Cinematic drone shot of Cappadocia hot air balloons at dawn, soft light, detailed landscape"),
+]
+
+VIDEO_PROMPT = ("beach_waves", "Waves crashing on a quiet beach at sunset, cinematic, 4k", 4.0)
+
+
+def download_url(url: str, path: Path, timeout: float = 60.0) -> None:
+    with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        r = client.get(url)
+        r.raise_for_status()
+        path.write_bytes(r.content)
+
+
+def main() -> int:
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    with create_client() as client:
+        # Images
+        for name, prompt in IMAGE_PROMPTS:
+            print(f"Generating image: {name} ...")
+            result = client.images.generate(
+                model="fal-ai/flux/schnell",
+                prompt=prompt,
+                width=1024,
+                height=1024,
+                num_images=1,
+            )
+            if not result.images:
+                print(f"  No image URL for {name}", file=sys.stderr)
+                continue
+            url = result.images[0]
+            ext = ".png" if ".png" in url.split("?")[0].lower() else ".jpg"
+            path = OUTPUT_DIR / f"{name}{ext}"
+            download_url(url, path)
+            print(f"  Saved {path}")
+
+        # Video (one short clip)
+        vname, vprompt, vdur = VIDEO_PROMPT
+        print(f"Generating video: {vname} ...")
+        try:
+            vresult = client.videos.generate(
+                model="fal-ai/flux-pro/video",
+                prompt=vprompt,
+                duration_seconds=vdur,
+            )
+            if vresult.video_url:
+                vpath = OUTPUT_DIR / f"{vname}.mp4"
+                download_url(vresult.video_url, vpath, timeout=120.0)
+                print(f"  Saved {vpath}")
+            else:
+                print("  Video URL not ready (async); skip download")
+        except Exception as e:
+            print(f"  Video skipped: {e}")
+
+    print(f"\nSample outputs in {OUTPUT_DIR}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/sample_outputs/README.md

@@ -0,0 +1,12 @@
+# Sample outputs
+
+Example images (and optionally video) generated with the Visgate API via `fetch_sample_outputs.py`.
+
+| File | Prompt |
+|------|--------|
+| `sunset_istanbul.jpg` | Golden hour sunset over Istanbul Bosphorus, minarets and seagulls, cinematic, detailed, 8k |
+| `cat_astronaut.jpg` | A fluffy orange cat astronaut floating in space, Earth in the background, photorealistic, whimsical |
+| `cappadocia_balloons.jpg` | Cinematic drone shot of Cappadocia hot air balloons at dawn, soft light, detailed landscape |
+| `beach_waves.mp4` | Waves crashing on a quiet beach at sunset (async; run the script to generate when ready) |
+
+Regenerate: from `examples/`, run `python fetch_sample_outputs.py` (requires `VISGATE_API_KEY`).