feat: Istanbul theme for all examples; video/GIF as istanbul; API.md and README updated

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

Author: uzunenes

README.md

@@ -92,10 +92,10 @@ result = client.images.generate(
 ```python
 result = client.videos.generate(
     model="fal-ai/flux-pro/video",
-    prompt="waves crashing on a beach",
+    prompt="Cinematic drone over Istanbul at golden hour, Bosphorus and minarets",
     duration_seconds=5.0,
 )
-print(result.video_url)
+print(result.video_url)  # Convert to GIF for previews: examples/make_video_and_gif.py --mp4 path
 ```
 
 ### Model Discovery
@@ -223,10 +223,11 @@ VISGATE_API_KEY=vg-... python examples/run_all_capabilities.py
 cd examples && python capture_all_outputs.py
 ```
 
-Sample outputs (images, video, and text proofs) are under [`examples/sample_outputs/`](examples/sample_outputs/). Regenerate images/video:
+Sample outputs use an **Istanbul theme** (Bosphorus, minarets, golden hour). They are under [`examples/sample_outputs/`](examples/sample_outputs/) (images, `istanbul.mp4`, `istanbul.gif`, and text proofs). Regenerate:
 
 ```bash
-cd examples && python fetch_sample_outputs.py
+cd examples && python fetch_sample_outputs.py   # images + video
+cd examples && python make_video_and_gif.py    # video + GIF
 ```
 
 ## Contributing

docs/API.md

@@ -4,7 +4,7 @@ Short reference. Full OpenAPI spec: your API base URL + `/docs`.
 
 ## Testing against the live API
 
-Use the **visgate-python** SDK and examples to hit the live API:
+Use the **visgate-python** SDK and examples to hit the live API. Sample outputs (images and video) use an **Istanbul theme** for a consistent look.
 
 ```bash
 pip install visgate-sdk
@@ -19,10 +19,19 @@ python examples/07_cache_demo.py
 # Semantic cache: similar prompts; second may = cache hit (Vertex AI + Firestore)
 python examples/08_semantic_cache_demo.py
 
-# Run all capability examples
+# Run all capability examples (images, video, usage, providers, etc.)
 python examples/run_all_capabilities.py
 ```
 
+**Regenerate sample outputs (Istanbul-themed images + video + GIF):**
+
+```bash
+cd examples
+python fetch_sample_outputs.py              # images + video (waits for video when async)
+python make_video_and_gif.py                # video + GIF (or use --mp4 path to convert only)
+python create_placeholder_video.py          # placeholder istanbul.mp4 + .gif without API
+```
+
 Base URL defaults to `https://visgateai.com/api/v1`. Override with `VISGATE_BASE_URL` for staging or local.
 
 ## Installation
@@ -224,7 +233,7 @@ result = await client.videos.generate(
 - `latency_ms` (int | None): Request latency in milliseconds
 - `created_at` (datetime): Creation timestamp
 
-**Note:** Video generation may be asynchronous. Check `video_url` to see if the video is ready.
+**Note:** Video generation may be asynchronous. Check `video_url` to see if the video is ready. You can convert the downloaded MP4 to a GIF for previews (e.g. `examples/make_video_and_gif.py` or `--mp4 path/to/video.mp4`).
 
 ## Usage Resource
 
@@ -420,8 +429,12 @@ client.close()
 
 API traffic is over HTTPS. Provider keys (BYOK) are encrypted at rest; account and usage data are stored on Google Cloud with encryption at rest.
 
+## Sample outputs (Istanbul theme)
+
+All example scripts use Istanbul-themed prompts (Bosphorus, minarets, golden hour, Galata Tower, etc.). Generated assets are under `examples/sample_outputs/`: images (e.g. `generate_unified.jpg`, `sunset_istanbul.jpg`, `galata_tower.jpg`, `bosphorus_night.jpg`), cache demos, and video `istanbul.mp4` plus `istanbul.gif` (video converted to GIF for previews).
+
 ## Additional Resources
 
 - SDK README: [README.md](../README.md)
-- Examples: [examples/](../examples/)
+- Examples (step-by-step): [examples/README.md](../examples/README.md)
 - API OpenAPI Spec: https://visgateai.com/api/v1/docs

examples/07_cache_demo.py

@@ -12,7 +12,7 @@
 
 
 def main() -> int:
-    prompt = "a red apple on a wooden table, studio lighting"
+    prompt = "Istanbul Bosphorus at golden hour, minarets visible, cinematic"
     model = "fal-ai/flux/schnell"
     width, height = 1024, 1024
 

examples/08_semantic_cache_demo.py

@@ -17,8 +17,8 @@
 
 
 def main() -> int:
-    prompt1 = "a red apple on a wooden table, studio lighting"
-    prompt2 = "red apple on wooden table with studio lights"
+    prompt1 = "Istanbul Bosphorus at golden hour, minarets visible, cinematic"
+    prompt2 = "Bosphorus Istanbul golden hour with minarets, cinematic"
     model = "fal-ai/flux/schnell"
     width, height = 1024, 1024
 

examples/README.md

@@ -99,7 +99,7 @@ Requires the SDK to be installed; `VISGATE_API_KEY` is required for auth steps.
 - **Purpose:** Video generation; may return async job; optional wait and download.
 - **API/SDK:** `POST /videos/generate`.
 - **Command:** `python examples/04_videos_all_providers.py`
-- **Output:** [out_04_videos_all_providers.txt](sample_outputs/out_04_videos_all_providers.txt) · Video: [beach_waves.mp4](sample_outputs/beach_waves.mp4) · GIF: ![beach_waves](sample_outputs/beach_waves.gif) (generate with `make_video_and_gif.py`)
+- **Output:** [out_04_videos_all_providers.txt](sample_outputs/out_04_videos_all_providers.txt) · Video: [istanbul.mp4](sample_outputs/istanbul.mp4) · GIF: ![istanbul](sample_outputs/istanbul.gif) (generate with `make_video_and_gif.py`)
 
 ---
 
@@ -175,8 +175,8 @@ Requires the SDK to be installed; `VISGATE_API_KEY` is required for auth steps.
 | 00_auth_identity | [out_00_auth_identity.txt](sample_outputs/out_00_auth_identity.txt) | — |
 | 01_models_catalog | [out_01_models_catalog.txt](sample_outputs/out_01_models_catalog.txt) | — |
 | 02 generate_unified | [out_02_generate_unified.txt](sample_outputs/out_02_generate_unified.txt) | ![generate_unified](sample_outputs/generate_unified.jpg) |
-| 03 images | [out_03_images_all_providers.txt](sample_outputs/out_03_images_all_providers.txt) | ![sunset](sample_outputs/sunset_istanbul.jpg) ![cat](sample_outputs/cat_astronaut.jpg) ![cappadocia](sample_outputs/cappadocia_balloons.jpg) |
-| 04 videos | [out_04_videos_all_providers.txt](sample_outputs/out_04_videos_all_providers.txt) | [beach_waves.mp4](sample_outputs/beach_waves.mp4) · ![beach_waves](sample_outputs/beach_waves.gif) |
+| 03 images | [out_03_images_all_providers.txt](sample_outputs/out_03_images_all_providers.txt) | ![sunset](sample_outputs/sunset_istanbul.jpg) ![galata](sample_outputs/galata_tower.jpg) ![bosphorus](sample_outputs/bosphorus_night.jpg) |
+| 04 videos | [out_04_videos_all_providers.txt](sample_outputs/out_04_videos_all_providers.txt) | [istanbul.mp4](sample_outputs/istanbul.mp4) · ![istanbul](sample_outputs/istanbul.gif) |
 | 05 usage | [out_05_usage_history_verify.txt](sample_outputs/out_05_usage_history_verify.txt) | — |
 | 06 provider_balances | [out_06_provider_balances.txt](sample_outputs/out_06_provider_balances.txt) | — |
 | 07 cache_demo | [out_07_cache_demo.txt](sample_outputs/out_07_cache_demo.txt) | ![cache_demo](sample_outputs/cache_demo.jpg) |
@@ -196,7 +196,7 @@ python fetch_sample_outputs.py
 
 Requires `VISGATE_API_KEY`. The script waits for video when the API returns async (no skip).
 
-### Video and GIF (beach_waves)
+### Video and GIF (Istanbul)
 
 To generate the sample video and a GIF preview:
 
@@ -205,7 +205,7 @@ cd examples
 VISGATE_API_KEY=vg-... python make_video_and_gif.py
 ```
 
-This produces `sample_outputs/beach_waves.mp4` and `sample_outputs/beach_waves.gif`. GIF conversion uses `ffmpeg` if available, or `pip install imageio imageio-ffmpeg` as fallback. To convert an existing MP4 only: `python make_video_and_gif.py --mp4 sample_outputs/beach_waves.mp4`.  
+This produces `sample_outputs/istanbul.mp4` and `sample_outputs/istanbul.gif`. GIF conversion uses `ffmpeg` if available, or `pip install imageio imageio-ffmpeg` as fallback. To convert an existing MP4 only: `python make_video_and_gif.py --mp4 sample_outputs/istanbul.mp4`.  
 If the API does not return a video URL, you can generate placeholder assets (no API) with: `python create_placeholder_video.py`.
 
 ## Cache behavior

examples/create_placeholder_video.py

@@ -1,14 +1,14 @@
 #!/usr/bin/env python3
-"""Create a minimal placeholder MP4 (beach-like) and convert to GIF.
-No API call. Run when you need sample_outputs/beach_waves.mp4 and .gif without the API.
+"""Create a minimal placeholder MP4 (Istanbul-themed) and convert to GIF.
+No API call. Run when you need sample_outputs/istanbul.mp4 and .gif without the API.
 """
 from __future__ import annotations
 
 import sys
 from pathlib import Path
 
 OUTPUT_DIR = Path(__file__).resolve().parent / "sample_outputs"
-VIDEO_NAME = "beach_waves"
+VIDEO_NAME = "istanbul"
 FPS = 8
 DURATION_SEC = 4.0
 W, H = 320, 180

examples/fetch_sample_outputs.py

@@ -21,22 +21,22 @@
 # 02_generate_unified
 GENERATE_PROMPT = "Istanbul skyline at sunset, realistic photo"
 
-# 03_images_all_providers style
+# 03_images_all_providers — all Istanbul themed
 IMAGE_PROMPTS = [
     ("sunset_istanbul", "Golden hour sunset over Istanbul Bosphorus, minarets and seagulls, cinematic, 8k"),
-    ("cat_astronaut", "A fluffy orange cat astronaut in space, Earth in background, photorealistic, whimsical"),
-    ("cappadocia_balloons", "Cappadocia hot air balloons at dawn, cinematic drone, soft light"),
+    ("galata_tower", "Galata Tower Istanbul at dusk, city lights and Bosphorus, cinematic, 8k"),
+    ("bosphorus_night", "Bosphorus Strait Istanbul at night, bridges and minarets, cinematic, 8k"),
 ]
 
-# 07_cache_demo
-CACHE_PROMPT = "A red apple on a wooden table, studio lighting"
+# 07_cache_demo — Istanbul
+CACHE_PROMPT = "Istanbul Bosphorus at golden hour, minarets visible, cinematic"
 
-# 08_semantic_cache_demo
-SEMANTIC_PROMPT_1 = "A red apple on a wooden table, studio lighting"
-SEMANTIC_PROMPT_2 = "Red apple on wooden table with studio lights"
+# 08_semantic_cache_demo — Istanbul (similar phrasing)
+SEMANTIC_PROMPT_1 = "Istanbul Bosphorus at golden hour, minarets visible, cinematic"
+SEMANTIC_PROMPT_2 = "Bosphorus Istanbul golden hour with minarets, cinematic"
 
-# 04_videos
-VIDEO_PROMPT = ("beach_waves", "Waves crashing on a quiet beach at sunset, cinematic, 4k", 4.0)
+# 04_videos — Istanbul
+VIDEO_PROMPT = ("istanbul", "Cinematic drone over Istanbul at golden hour, Bosphorus and minarets, 4k", 4.0)
 VIDEO_POLL_SLEEP = 25
 VIDEO_POLL_ATTEMPTS = 6
 
@@ -143,7 +143,7 @@ def main() -> int:
                     duration_seconds=vdur,
                 )
                 if vresult.video_url:
-                    vpath = OUTPUT_DIR / f"{vname}.mp4"
+                    vpath = OUTPUT_DIR / f"{vname}.mp4"  # istanbul.mp4
                     download_url(vresult.video_url, vpath, timeout=120.0)
                     print(f"  Saved {vpath}")
                     break

examples/make_video_and_gif.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
-Generate one sample video (beach_waves) and convert it to GIF.
-Saves to examples/sample_outputs/beach_waves.mp4 and beach_waves.gif.
+Generate one sample video (Istanbul) and convert it to GIF.
+Saves to examples/sample_outputs/istanbul.mp4 and istanbul.gif.
 
 Requires: VISGATE_API_KEY. For GIF: ffmpeg (preferred) or pip install imageio imageio-ffmpeg.
 
@@ -25,8 +25,8 @@
 VIDEO_REQUEST_TIMEOUT = 360.0
 
 OUTPUT_DIR = Path(__file__).resolve().parent / "sample_outputs"
-VIDEO_NAME = "beach_waves"
-VIDEO_PROMPT = "Waves crashing on a quiet beach at sunset, cinematic, 4k"
+VIDEO_NAME = "istanbul"
+VIDEO_PROMPT = "Cinematic drone over Istanbul at golden hour, Bosphorus and minarets, 4k"
 VIDEO_DURATION = 4.0
 POLL_SLEEP = 25
 POLL_ATTEMPTS = 6
@@ -86,7 +86,7 @@ def convert_imageio(mp4_path: Path, gif_path: Path) -> bool:
 
 def main() -> int:
     import argparse
-    parser = argparse.ArgumentParser(description="Generate beach_waves video + GIF or convert existing MP4 to GIF")
+    parser = argparse.ArgumentParser(description="Generate Istanbul video + GIF or convert existing MP4 to GIF")
     parser.add_argument("--mp4", type=Path, help="Existing MP4 path; if set, only convert to GIF (no API call)")
     args = parser.parse_args()