docs(video-generation): Update docs for video generation feature

Author: Rahul-2903-juspay

README.md

@@ -37,9 +37,25 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 | Feature                            | Version | Description                                                                                                                                    | Guide                                                        |
 | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| **Video Generation with Veo**      | v8.32.0 | Video generation using Veo 3.1 (`veo-3.1`). Realistic video generation with many parameter options                                             | [Video Generation Guide](docs/features/video-generation.md)  |
 | **Image Generation with Gemini**   | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI. | [Image Generation Guide](docs/image-generation-streaming.md) |
 | **HTTP/Streamable HTTP Transport** | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.  | [HTTP Transport Guide](docs/mcp-http-transport.md)           |
 
+- **Video Generation** – Transform images into 8-second videos with synchronized audio using Google Veo 3.1 via Vertex AI. Supports 720p/1080p resolutions, portrait/landscape aspect ratios. → [Video Generation Guide](docs/features/video-generation.md)
+- **Image Generation** – Generate images from text prompts using Gemini models via Vertex AI or Google AI Studio. Supports streaming mode with automatic file saving. → [Image Generation Guide](docs/IMAGE-GENERATION-STREAMING.md)
+- **HTTP/Streamable HTTP Transport for MCP** – Connect to remote MCP servers via HTTP with authentication headers, retry logic, and rate limiting. → [HTTP Transport Guide](docs/MCP-HTTP-TRANSPORT.md)
+- 🧠 **Gemini 3 Preview Support** - Full support for gemini-3-flash-preview and gemini-3-pro-preview with extended thinking capabilities
+- **Structured Output with Zod Schemas** – Type-safe JSON generation with automatic validation using `schema` + `output.format: "json"` in `generate()`. → [Structured Output Guide](docs/features/structured-output.md)
+- **CSV File Support** – Attach CSV files to prompts for AI-powered data analysis with auto-detection. → [CSV Guide](docs/features/multimodal-chat.md#csv-file-support)
+- **PDF File Support** – Process PDF documents with native visual analysis for Vertex AI, Anthropic, Bedrock, AI Studio. → [PDF Guide](docs/features/pdf-support.md)
+- **LiteLLM Integration** – Access 100+ AI models from all major providers through unified interface. → [Setup Guide](docs/LITELLM-INTEGRATION.md)
+- **SageMaker Integration** – Deploy and use custom trained models on AWS infrastructure. → [Setup Guide](docs/SAGEMAKER-INTEGRATION.md)
+- **OpenRouter Integration** – Access 300+ models from OpenAI, Anthropic, Google, Meta, and more through a single unified API. → [Setup Guide](docs/getting-started/providers/openrouter.md)
+- **Human-in-the-loop workflows** – Pause generation for user approval/input before tool execution. → [HITL Guide](docs/features/hitl.md)
+- **Guardrails middleware** – Block PII, profanity, and unsafe content with built-in filtering. → [Guardrails Guide](docs/features/guardrails.md)
+- **Context summarization** – Automatic conversation compression for long-running sessions. → [Summarization Guide](docs/CONTEXT-SUMMARIZATION.md)
+- **Redis conversation export** – Export full session history as JSON for analytics and debugging. → [History Guide](docs/features/conversation-history.md)
+
 ```typescript
 // Image Generation with Gemini (v8.31.0)
 const image = await neurolink.generateImage({

docs/cli-guide.md

@@ -124,6 +124,16 @@ npx @juspay/neurolink gen "Analyze this problem" --provider google-ai --model ge
 - `--context <json>` - JSON context object for custom data (e.g., '{"userId":"123","project":"api-design"}')
 - `--disableTools` - Disable MCP tool integration (tools enabled by default)
 
+**Video Generation Options (Veo 3.1):**
+
+- `--outputMode <mode>` - Output mode: 'text' (default) or 'video'
+- `--image <path>` - Path to input image file for image-based video generation (required for video mode, e.g., ./input.jpg)
+- `--videoOutput <path>` - Path to save generated video file (e.g., ./output.mp4)
+- `--videoResolution <res>` - Video resolution: '720p' or '1080p' (default: 720p)
+- `--videoLength <seconds>` - Video duration: 4, 6, or 8 seconds (default: 6)
+- `--videoAspectRatio <ratio>` - Aspect ratio: '9:16' (portrait) or '16:9' (landscape, default: 16:9)
+- `--videoAudio <bool>` - Include synchronized audio (default: true)
+
 **Output Example:**
 
 ```
@@ -1130,15 +1140,15 @@ npx @juspay/neurolink status
 
 ## When to Use CLI vs SDK
 
-### Use the CLI when:
+### Use the CLI when
 
 - 🔧 **Prototyping**: Quick testing of prompts and providers
 - 📜 **Scripting**: Shell scripts and automation workflows
 - 🔍 **Debugging**: Checking provider status and testing connectivity
 - 📊 **Batch Processing**: Processing multiple prompts from files
 - 🎯 **One-off Tasks**: Generating content without writing code
 
-### Use the SDK when:
+### Use the SDK when
 
 - 🏗️ **Application Development**: Building web apps, APIs, or services
 - 🔄 **Real-time Integration**: Chat interfaces, streaming responses

docs/cli-reference.md

@@ -66,6 +66,18 @@ npx @juspay/neurolink gen "Write code" --provider openai
 | ----------------- | ------- | ------- | ------------------------------------------------------- |
 | `--disable-tools` | boolean | `false` | Disable MCP tool integration (tools enabled by default) |
 
+### Video Generation (Veo 3.1)
+
+| Flag                   | Type    | Default | Description                                                               |
+| ---------------------- | ------- | ------- | ------------------------------------------------------------------------- |
+| `--outputMode`         | string  | `text`  | Output mode: 'text' or 'video'                                            |
+| `--image`              | string  | none    | Path to an input image to base the generated video on (e.g., ./input.png) |
+| `--videoOutput`, `-vo` | string  | none    | Path to save generated video (e.g., ./output.mp4)                         |
+| `--videoResolution`    | string  | `720p`  | Video resolution: '720p' or '1080p'                                       |
+| `--videoLength`        | number  | `6`     | Video duration in seconds: 4, 6, or 8                                     |
+| `--videoAspectRatio`   | string  | `16:9`  | Aspect ratio: '9:16' (portrait) or '16:9' (landscape)                     |
+| `--videoAudio`         | boolean | `true`  | Include synchronized audio                                                |
+
 ## Usage Examples
 
 ### Basic Text Generation
@@ -264,6 +276,39 @@ Artificial Intelligence (AI) refers to...
 4. **Debug Efficiently**: Use `--debug` only when troubleshooting to avoid verbose output
 5. **Context Size**: Keep `--context` objects small to minimize token usage
 
+## Video Generation Examples
+
+Generate videos from images using Veo 3.1 via Vertex AI:
+
+```bash
+# Basic video generation
+npx @juspay/neurolink generate "Product showcase with smooth camera movement" \
+  --image ./product.jpg \
+  --outputMode video \
+  --videoOutput ./output.mp4
+
+# Full options
+npx @juspay/neurolink generate "Cinematic reveal with dramatic lighting" \
+  --image ./hero-image.png \
+  --provider vertex \
+  --model veo-3.1 \
+  --outputMode video \
+  --videoResolution 1080p \
+  --videoLength 8 \
+  --videoAspectRatio 16:9 \
+  --videoOutput ./cinematic.mp4
+
+# Portrait video for social media
+npx @juspay/neurolink generate "Vertical scroll animation" \
+  --image ./mobile-screenshot.jpg \
+  --outputMode video \
+  --videoResolution 720p \
+  --videoAspectRatio 9:16 \
+  --videoOutput ./story.mp4
+```
+
+> **Note:** Video generation requires Vertex AI credentials. See [Video Generation Guide](./features/video-generation.md).
+
 ## Environment Variables
 
 See the [Environment Variables](./getting-started/environment-variables.md) documentation for complete configuration options.

docs/cli/commands.md

@@ -58,6 +58,18 @@ Key flags:
 - `--debug` – verbose logging and full JSON payloads.
 - `--quiet` – suppress spinners.
 
+**Video Generation (Veo 3.1):**
+
+- `--outputMode` – output mode: `text` (default) or `video`.
+- `--image` – path to input image file (required for video generation, e.g., ./input.jpg).
+- `--videoOutput`, `-vo` – path to save generated video file.
+- `--videoResolution` – `720p` or `1080p` (default `720p`).
+- `--videoLength` – duration: `4`, `6`, or `8` seconds (default `6`).
+- `--videoAspectRatio` – `9:16` (portrait) or `16:9` (landscape, default `16:9`).
+- `--videoAudio` – include synchronized audio (default `true`).
+
+**Note:** Video generation requires Vertex AI provider (`vertex`) and Veo 3.1 model (`veo-3.1`). The provider auto-switches to Vertex when `--outputMode video` is specified. Supported image formats: PNG, JPEG, WebP (max 20MB).
+
 `gen` is a short alias with the same options.
 
 ### `stream <input>` {#stream}

docs/configuration.md

@@ -194,6 +194,26 @@ export MEM0_VECTOR_STORE="qdrant"
 
 Consult [`docs/mem0-integration.md`](mem0-integration.md) for vector store specifics and SDK examples.
 
+### **Video Generation (Veo 3.1)**
+
+Configure Vertex AI credentials to enable video generation with Veo 3.1. Choose **one** of the following credential options:
+
+```bash
+# Option 1: Service account file (recommended for production)
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
+export GOOGLE_VERTEX_PROJECT="your-project-id"
+export GOOGLE_VERTEX_LOCATION="us-central1"
+
+# Option 2: Environment variables (alternative to service account file)
+# GOOGLE_CLOUD_* variables are equivalent to GOOGLE_VERTEX_* for project/location configuration
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_CLOUD_LOCATION="us-central1"
+```
+
+**Note:** These are alternative approaches—you only need one. `GOOGLE_VERTEX_PROJECT` and `GOOGLE_CLOUD_PROJECT` map to the same project configuration; similarly, `GOOGLE_VERTEX_LOCATION` and `GOOGLE_CLOUD_LOCATION` specify the same region.
+
+See [Video Generation Guide](features/video-generation.md) for complete setup and usage.
+
 ### **Regional Routing**
 
 Set region-specific variables to control latency and compliance.

docs/dynamic-models.md

@@ -11,6 +11,7 @@ The dynamic model system enables:
 - **Smart model resolution** with fuzzy matching and aliases
 - **Capability-based search** to find models with specific features
 - **Cost optimization** by automatically selecting cheapest models for tasks
+- **Video generation** support via Veo 3.1 model on Vertex AI
 
 ## 🏗️ Architecture
 

docs/error-handling.md

@@ -22,6 +22,17 @@ This document covers error handling strategies in NeuroLink.
 - Memory allocation issues
 - Timeout errors
 
+### Video Generation Errors
+
+Video generation via Veo 3.1 on Vertex AI may encounter specific error conditions:
+
+- **VIDEO_GENERATION_FAILED** - Video generation process failed
+- **PROVIDER_NOT_CONFIGURED** - Vertex AI credentials not configured
+- **VIDEO_POLL_TIMEOUT** - Video generation timed out (exceeds 3 minutes)
+- **VIDEO_INVALID_INPUT** - Invalid image format or parameters
+- **VIDEO_QUOTA_EXCEEDED** - Vertex AI quota or rate limit exceeded
+- **VIDEO_REGION_UNAVAILABLE** - Veo 3.1 not available in specified region
+
 ## Error Recovery
 
 ### Automatic Retry
@@ -36,6 +47,77 @@ Configure fallback providers to handle primary provider failures.
 
 System continues to operate with reduced functionality when errors occur.
 
+### Video Generation Error Handling
+
+**Example: Handling video generation errors**
+
+```typescript
+import { NeuroLink } from "@juspay/neurolink";
+import { readFile, writeFile } from "fs/promises";
+
+const neurolink = new NeuroLink();
+
+try {
+  const result = await neurolink.generate({
+    input: {
+      text: "Product showcase video",
+      images: [await readFile("./product.jpg")],
+    },
+    provider: "vertex",
+    model: "veo-3.1",
+    output: {
+      mode: "video",
+      video: {
+        resolution: "1080p",
+        length: 8,
+        aspectRatio: "16:9",
+      },
+    },
+    timeout: 180, // 3 minutes for video generation
+  });
+
+  if (result.video) {
+    await writeFile("output.mp4", result.video.data);
+  }
+} catch (error) {
+  // Use your logger for production: logger.error('Video generation failed', { code: error.code, error })
+  if (error.code === "PROVIDER_NOT_CONFIGURED") {
+    console.error(
+      "Vertex AI credentials not configured. Set GOOGLE_APPLICATION_CREDENTIALS.",
+    );
+  } else if (error.code === "VIDEO_POLL_TIMEOUT") {
+    console.error(
+      "Video generation timed out. Try again or reduce video length.",
+    );
+  } else if (error.code === "VIDEO_INVALID_INPUT") {
+    console.error(
+      "Invalid image format. Ensure PNG, JPEG, or WebP under 20MB.",
+    );
+  } else if (error.code === "VIDEO_QUOTA_EXCEEDED") {
+    console.error("Vertex AI quota exceeded. Check your billing and quotas.");
+  } else {
+    console.error("Video generation failed:", error.message);
+  }
+}
+```
+
+**CLI Error Handling:**
+
+```bash
+# Video generation with error handling
+npx @juspay/neurolink generate "Product video" \
+  --image ./product.jpg \
+  --outputMode video \
+  --videoOutput ./output.mp4 \
+  --timeout 180
+
+# Check exit code for automation
+if [ $? -ne 0 ]; then
+  echo "Video generation failed"
+  exit 1
+fi
+```
+
 ## Monitoring and Logging
 
 ### Error Logging