Use Supabase for outputs and add Python/TS API clients

API_TYPESCRIPT.md

@@ -0,0 +1,494 @@
+# InstantSplat TypeScript API Client
+
+Complete TypeScript/JavaScript client for InstantSplat API with full type safety.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @gradio/client @types/node ts-node tsx
+```
+
+### Basic Usage
+
+```typescript
+import { processImages } from "./api_client";
+
+const result = await processImages(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "your-username/InstantSplat"
+);
+
+if (result.status === "success") {
+  console.log("GLB URL:", result.glb_url);
+  console.log("PLY URL:", result.ply_url);
+}
+```
+
+## 📦 Available Functions
+
+### `processImages(imagePaths, spaceUrl?)`
+
+Submit images and get back URLs.
+
+```typescript
+async function processImages(
+  imagePaths: string[],
+  spaceUrl?: string
+): Promise<ProcessResult>
+```
+
+**Parameters:**
+- `imagePaths`: Array of local image file paths
+- `spaceUrl`: (Optional) HuggingFace Space URL or env var `INSTANTSPLAT_SPACE`
+
+**Returns:**
+```typescript
+interface ProcessResult {
+  status: "success" | "error";
+  glb_url?: string;
+  ply_url?: string;
+  video_available?: boolean;
+  error?: string;
+  message?: string;
+}
+```
+
+**Example:**
+```typescript
+const result = await processImages(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "username/InstantSplat"
+);
+
+console.log(result.glb_url); // Supabase URL to GLB file
+```
+
+### `completeWorkflow(imagePaths, outputDir, spaceUrl?)`
+
+Process images and download the GLB file.
+
+```typescript
+async function completeWorkflow(
+  imagePaths: string[],
+  outputDir?: string,
+  spaceUrl?: string
+): Promise<string | null>
+```
+
+**Parameters:**
+- `imagePaths`: Array of image paths
+- `outputDir`: Local directory for downloaded file (default: `./outputs`)
+- `spaceUrl`: (Optional) Space URL
+
+**Returns:** Local path to downloaded GLB file, or `null` on error
+
+**Example:**
+```typescript
+const localPath = await completeWorkflow(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "./my_models"
+);
+
+console.log("Model saved to:", localPath);
+// Output: Model saved to: ./my_models/model.glb
+```
+
+### `downloadFile(url, outputPath)`
+
+Download a file from URL.
+
+```typescript
+async function downloadFile(
+  url: string,
+  outputPath: string
+): Promise<void>
+```
+
+## 🛠️ CLI Usage
+
+### Using npx
+
+```bash
+npx tsx api_client.ts img1.jpg img2.jpg img3.jpg
+```
+
+### Using npm script
+
+```bash
+npm run api img1.jpg img2.jpg img3.jpg
+```
+
+### With environment variable
+
+```bash
+export INSTANTSPLAT_SPACE="username/InstantSplat"
+npx tsx api_client.ts img1.jpg img2.jpg img3.jpg
+```
+
+## 📝 Examples
+
+### Example 1: Simple Usage
+
+```typescript
+import { processImages } from "./api_client";
+
+async function main() {
+  const result = await processImages(
+    ["image1.jpg", "image2.jpg", "image3.jpg"],
+    "username/InstantSplat"
+  );
+
+  if (result.status === "success") {
+    console.log("✅ GLB URL:", result.glb_url);
+    console.log("✅ PLY URL:", result.ply_url);
+  } else {
+    console.error("❌ Error:", result.error);
+  }
+}
+
+main();
+```
+
+### Example 2: With Error Handling
+
+```typescript
+import { processImages } from "./api_client";
+
+async function processWithRetry(
+  images: string[],
+  maxRetries = 3
+): Promise<ProcessResult> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const result = await processImages(images);
+
+    if (result.status === "success") {
+      return result;
+    }
+
+    if (attempt < maxRetries) {
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  throw new Error("All retries failed");
+}
+```
+
+### Example 3: Batch Processing
+
+```typescript
+import { processImages } from "./api_client";
+
+async function batchProcess(imageSets: string[][]) {
+  const results = [];
+
+  for (let i = 0; i < imageSets.length; i++) {
+    console.log(`Processing set ${i + 1}/${imageSets.length}...`);
+    
+    const result = await processImages(imageSets[i]);
+    results.push(result);
+
+    // Rate limiting
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  }
+
+  return results;
+}
+
+const sets = [
+  ["scene1_img1.jpg", "scene1_img2.jpg"],
+  ["scene2_img1.jpg", "scene2_img2.jpg"],
+];
+
+const results = await batchProcess(sets);
+```
+
+### Example 4: Download and Use
+
+```typescript
+import { completeWorkflow } from "./api_client";
+
+async function processAndDownload() {
+  const modelPath = await completeWorkflow(
+    ["img1.jpg", "img2.jpg", "img3.jpg"],
+    "./models"
+  );
+
+  if (modelPath) {
+    console.log(`Model ready at: ${modelPath}`);
+    // Use the model file...
+  }
+}
+```
+
+## 🌐 Integration Examples
+
+### Express.js API
+
+```typescript
+import express from "express";
+import { processImages } from "./api_client";
+
+const app = express();
+app.use(express.json());
+
+app.post("/api/process", async (req, res) => {
+  const { images } = req.body;
+
+  const result = await processImages(
+    images,
+    process.env.INSTANTSPLAT_SPACE
+  );
+
+  if (result.status === "success") {
+    res.json({
+      success: true,
+      glb_url: result.glb_url,
+      ply_url: result.ply_url
+    });
+  } else {
+    res.status(500).json({
+      success: false,
+      error: result.error
+    });
+  }
+});
+
+app.listen(3000);
+```
+
+### Next.js API Route
+
+```typescript
+// pages/api/process.ts
+import type { NextApiRequest, NextApiResponse } from "next";
+import { processImages } from "../../api_client";
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "Method not allowed" });
+  }
+
+  const { images } = req.body;
+
+  const result = await processImages(
+    images,
+    process.env.INSTANTSPLAT_SPACE
+  );
+
+  if (result.status === "success") {
+    res.status(200).json(result);
+  } else {
+    res.status(500).json(result);
+  }
+}
+```
+
+### React Hook
+
+```typescript
+import { useState } from "react";
+import { processImages } from "./api_client";
+
+function useInstantSplat() {
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<ProcessResult | null>(null);
+
+  const process = async (images: string[]) => {
+    setLoading(true);
+    try {
+      const res = await processImages(images);
+      setResult(res);
+      return res;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return { process, loading, result };
+}
+
+// Usage in component:
+function MyComponent() {
+  const { process, loading, result } = useInstantSplat();
+
+  const handleSubmit = () => {
+    process(["img1.jpg", "img2.jpg", "img3.jpg"]);
+  };
+
+  return (
+    <div>
+      {loading && <p>Processing...</p>}
+      {result?.glb_url && <a href={result.glb_url}>Download Model</a>}
+    </div>
+  );
+}
+```
+
+### Vue.js Composable
+
+```typescript
+import { ref } from "vue";
+import { processImages } from "./api_client";
+
+export function useInstantSplat() {
+  const loading = ref(false);
+  const result = ref(null);
+
+  const process = async (images: string[]) => {
+    loading.value = true;
+    try {
+      result.value = await processImages(images);
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return { process, loading, result };
+}
+```
+
+## 📚 Type Definitions
+
+```typescript
+interface ProcessResult {
+  status: "success" | "error";
+  glb_url?: string;           // Supabase URL to GLB file
+  ply_url?: string;           // Supabase URL to PLY file
+  video_available?: boolean;  // Whether video was generated
+  error?: string;             // Error message if status is "error"
+  message?: string;           // Success message
+}
+
+interface InstantSplatResponse {
+  video_path: string;    // [0] Path to video
+  ply_url: string;       // [1] PLY URL
+  ply_download: string;  // [2] PLY download
+  ply_model: string;     // [3] PLY model
+  glb_model: string;     // [4] GLB model path
+  glb_url: string;       // [5] GLB URL (Supabase)
+}
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+# .env
+INSTANTSPLAT_SPACE=username/InstantSplat
+```
+
+### package.json Scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "api": "npx tsx api_client.ts",
+    "process": "npx tsx example_api_usage.ts"
+  }
+}
+```
+
+## 🔧 Troubleshooting
+
+### "Cannot find module '@gradio/client'"
+
+```bash
+npm install @gradio/client
+```
+
+### "Cannot find name 'require'"
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  }
+}
+```
+
+### TypeScript errors
+
+Make sure you have the types installed:
+
+```bash
+npm install --save-dev @types/node
+```
+
+### Import errors
+
+If using ES modules, change imports:
+
+```typescript
+// CommonJS
+const { processImages } = require("./api_client");
+
+// ES Modules
+import { processImages } from "./api_client.js";
+```
+
+## 📦 Building for Production
+
+### Compile TypeScript
+
+```bash
+npx tsc api_client.ts
+```
+
+### Bundle with esbuild
+
+```bash
+npx esbuild api_client.ts --bundle --platform=node --outfile=dist/api_client.js
+```
+
+### Use in production
+
+```typescript
+// Import the compiled version
+import { processImages } from "./dist/api_client.js";
+```
+
+## 🎯 Best Practices
+
+1. **Rate Limiting**: Add delays between batch requests
+2. **Error Handling**: Always wrap in try-catch
+3. **Retries**: Implement exponential backoff
+4. **Timeouts**: Set reasonable timeouts for large images
+5. **Validation**: Check image files exist before uploading
+
+## 📖 More Examples
+
+See `example_api_usage.ts` for complete working examples including:
+- Simple usage
+- Complete workflow with download
+- Batch processing
+- Error handling with retries
+- Express.js integration
+- React component integration
+
+## 🆘 Support
+
+- Check `API_GUIDE.md` for general API documentation
+- Check `API_QUICKSTART.md` for quick start guide
+- Review `example_api_usage.ts` for working examples
+
+## 🔗 Related Files
+
+- `api_client.ts` - Main TypeScript client
+- `api_client.py` - Python equivalent
+- `example_api_usage.ts` - Usage examples
+- `API_GUIDE.md` - Complete API documentation
+- `API_QUICKSTART.md` - Quick start guide
+

README_TS.md

@@ -0,0 +1,164 @@
+# InstantSplat TypeScript/JavaScript Client
+
+TypeScript/JavaScript clients to call InstantSplat and get back Supabase Storage URLs for GLB/PLY files.
+
+## 📦 Two Clients Available
+
+1. **`api_client.ts`** - Modern API client with Supabase URLs (Recommended)
+2. **`call_instantsplat.ts`** - Original client for direct file access
+
+## Installation
+
+```bash
+npm install
+```
+
+---
+
+## 🚀 API Client (Recommended)
+
+Get Supabase URLs for your GLB/PLY files.
+
+### Quick Start
+
+```bash
+# CLI usage
+npm run api img1.jpg img2.jpg img3.jpg
+
+# Or with tsx
+npx tsx api_client.ts img1.jpg img2.jpg img3.jpg
+```
+
+### Programmatic Usage
+
+```typescript
+import { processImages } from "./api_client";
+
+const result = await processImages(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "your-username/InstantSplat"
+);
+
+if (result.status === "success") {
+  console.log("GLB URL:", result.glb_url);
+  console.log("PLY URL:", result.ply_url);
+}
+```
+
+### Complete Workflow (Process + Download)
+
+```typescript
+import { completeWorkflow } from "./api_client";
+
+const localPath = await completeWorkflow(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "./models" // output directory
+);
+
+console.log("Model saved to:", localPath);
+```
+
+### 📚 Full TypeScript Documentation
+
+See **`API_TYPESCRIPT.md`** for:
+- Complete API reference
+- Type definitions
+- Integration examples (Express, Next.js, React, Vue)
+- Error handling patterns
+- Batch processing
+
+---
+
+## 📂 Original Client
+
+For direct file access without Supabase.
+
+### Basic Usage
+
+```bash
+npm run call <image1> <image2> [image3] ...
+```
+
+Example:
+```bash
+npm run call assets/example/sora-santorini-3-views/frame_00.jpg assets/example/sora-santorini-3-views/frame_06.jpg assets/example/sora-santorini-3-views/frame_12.jpg
+```
+
+Or using tsx directly:
+```bash
+npx tsx call_instantsplat.ts image1.jpg image2.jpg image3.jpg
+```
+
+### Using as a Module
+
+```typescript
+import { callInstantSplat } from './call_instantsplat';
+
+const result = await callInstantSplat([
+  'image1.jpg',
+  'image2.jpg',
+  'image3.jpg'
+]);
+
+console.log('Video:', result.video);
+console.log('PLY URL:', result.plyUrl);
+console.log('PLY Path:', result.plyPath);
+```
+
+### Environment Variables
+
+Optionally set `HF_TOKEN` environment variable if authentication is required:
+
+```bash
+export HF_TOKEN=your_huggingface_token
+npm run call image1.jpg image2.jpg
+```
+
+## Requirements
+
+- Node.js 18+ 
+- At least 2 input images
+- All images should have the same resolution
+
+## Output
+
+The script returns:
+- **video**: Path to the rendered video file
+- **plyUrl**: URL to download the PLY point cloud file
+- **plyPath**: Local path to the PLY file
+
+## Which Client Should I Use?
+
+| Feature | API Client | Original Client |
+|---------|-----------|----------------|
+| **Returns** | Supabase URLs | Local file paths |
+| **Best for** | Production APIs | Local testing |
+| **File access** | Via URL | Direct file |
+| **Storage** | Supabase Storage | Temporary |
+| **Sharing** | Easy (URL) | Requires hosting |
+
+**Use API Client (`api_client.ts`)** when:
+- ✅ Building web APIs
+- ✅ Need permanent URLs
+- ✅ Want to share results
+- ✅ Integrating with apps
+
+**Use Original Client (`call_instantsplat.ts`)** when:
+- ✅ Testing locally
+- ✅ Need immediate file access
+- ✅ Processing for local use only
+
+## 📖 Documentation
+
+- **`API_TYPESCRIPT.md`** - Complete TypeScript API docs
+- **`API_GUIDE.md`** - General API documentation
+- **`API_QUICKSTART.md`** - Quick start guide
+- **`example_api_usage.ts`** - Working code examples
+
+## Notes
+
+- Processing may take several minutes depending on the number of images and their resolution
+- The Hugging Face Space uses GPU resources which may have rate limits
+- Make sure all input images have the same resolution
+- For production use, we recommend the API Client with Supabase Storage
+

TYPESCRIPT_QUICKSTART.md

@@ -0,0 +1,97 @@
+# TypeScript API Client - Quick Start
+
+## ✅ Fixed and Ready to Use!
+
+The TypeScript API client is now working. Here's how to use it:
+
+## 🚀 Usage
+
+### Option 1: With Environment Variable (Recommended)
+
+```bash
+# Set your Space URL
+export INSTANTSPLAT_SPACE="your-username/InstantSplat"
+
+# Run the client
+npm run api test01/IMG_8533.jpeg test01/IMG_8534.jpeg test01/IMG_8535.jpeg
+```
+
+### Option 2: Programmatic Usage
+
+```typescript
+import { processImages } from "./api_client.js";
+
+const result = await processImages(
+  ["img1.jpg", "img2.jpg", "img3.jpg"],
+  "your-username/InstantSplat"  // Specify Space URL here
+);
+
+if (result.status === "success") {
+  console.log("GLB URL:", result.glb_url);
+  console.log("PLY URL:", result.ply_url);
+}
+```
+
+### Option 3: Local Instance
+
+If running the app locally:
+
+```bash
+# Terminal 1: Start the app
+python app.py
+
+# Terminal 2: Use the client (no Space URL needed)
+npm run api img1.jpg img2.jpg img3.jpg
+```
+
+## 🔧 What Was Fixed
+
+1. ✅ Fixed `@gradio/client` import (uses `client` function, not `Client` class)
+2. ✅ Fixed ES module compatibility (`import.meta.url` instead of `require.main`)
+3. ✅ Updated all examples and documentation
+
+## 📝 Complete Example
+
+```typescript
+import { processImages, completeWorkflow } from "./api_client.js";
+
+// Example 1: Get URLs only
+async function getURLs() {
+  const result = await processImages(
+    ["img1.jpg", "img2.jpg", "img3.jpg"],
+    "your-username/InstantSplat"
+  );
+  
+  if (result.status === "success") {
+    return {
+      glb: result.glb_url,
+      ply: result.ply_url
+    };
+  }
+}
+
+// Example 2: Process and download
+async function processAndDownload() {
+  const localPath = await completeWorkflow(
+    ["img1.jpg", "img2.jpg", "img3.jpg"],
+    "./models",
+    "your-username/InstantSplat"
+  );
+  
+  console.log("Model saved to:", localPath);
+}
+```
+
+## 🎯 Next Steps
+
+1. Deploy your Space to HuggingFace
+2. Get your Space URL (e.g., `username/InstantSplat`)
+3. Run the client with your Space URL
+4. Integrate into your TypeScript/JavaScript application
+
+## 📚 Full Documentation
+
+- `API_TYPESCRIPT.md` - Complete TypeScript API reference
+- `example_api_usage.ts` - Working examples
+- `README_TS.md` - General TypeScript client guide
+

api_client.py

@@ -16,7 +16,7 @@ import os
 from gradio_client import Client
 
 
-def process_images(image_paths, space_url=None):
+def process_images(image_paths, space_url=None, hf_token=None):
     """
     Submit images to InstantSplat and get GLB URL.
     
@@ -43,12 +43,11 @@ def process_images(image_paths, space_url=None):
     
     try:
         # Connect to Space
-        if space_url:
-            print(f"Connecting to Space: {space_url}")
-            client = Client(space_url)
-        else:
-            print("Using local Gradio instance (make sure it's running)")
-            client = Client("http://localhost:7860")
+        if not space_url:
+            space_url = "longh37/InstantSplat"
+        
+        print(f"Connecting to Space: {space_url}")
+        client = Client(space_url)
         
         print(f"Submitting {len(image_paths)} images for processing...")
         for i, img in enumerate(image_paths, 1):

api_client.ts

@@ -0,0 +1,302 @@
+#!/usr/bin/env ts-node
+/**
+ * InstantSplat API Client (TypeScript)
+ *
+ * Submit images to InstantSplat and get back the Supabase GLB URL.
+ *
+ * Usage:
+ *   npx ts-node api_client.ts image1.jpg image2.jpg image3.jpg
+ *
+ * Environment variables:
+ *   INSTANTSPLAT_SPACE - HuggingFace Space URL (default: http://localhost:7860)
+ */
+
+// Polyfill for Node.js environment (Gradio client expects browser globals)
+if (typeof window === "undefined") {
+  (global as any).window = {};
+}
+
+import { client } from "@gradio/client";
+import * as fs from "fs";
+import * as path from "path";
+
+interface ProcessResult {
+  status: "success" | "error";
+  glb_url?: string;
+  ply_url?: string;
+  video_available?: boolean;
+  error?: string;
+  message?: string;
+}
+
+interface InstantSplatResponse {
+  video_path: string;
+  ply_url: string;
+  ply_download: string;
+  ply_model: string;
+  glb_model: string;
+  glb_url: string;
+}
+
+type GradioClient = Awaited<ReturnType<typeof client>>;
+type PredictReturn = any; // Gradio client predict return type
+
+/**
+ * Submit images to InstantSplat and get GLB URL.
+ */
+export async function processImages(
+  imagePaths: string[],
+  spaceUrl?: string,
+  hfToken?: string
+): Promise<ProcessResult> {
+  // Validate inputs
+  if (imagePaths.length < 2) {
+    return {
+      status: "error",
+      error: "Need at least 2 images (3+ recommended)"
+    };
+  }
+
+  // Check if files exist
+  for (const imagePath of imagePaths) {
+    if (!fs.existsSync(imagePath)) {
+      return {
+        status: "error",
+        error: `File not found: ${imagePath}`
+      };
+    }
+  }
+
+  try {
+    // Connect to Space
+    const url =
+      spaceUrl || process.env.INSTANTSPLAT_SPACE || "longh37/InstantSplat";
+    const token = hfToken || process.env.HF_TOKEN;
+
+    console.log(`Connecting to: ${url}`);
+    if (token) {
+      console.log(`Using HF token: ${token.substring(0, 10)}...`);
+    }
+
+    const app = await client(url, { hf_token: token });
+
+    console.log(`✅ Connected to Space: ${url}`);
+    console.log(`Submitting ${imagePaths.length} images for processing...`);
+    imagePaths.forEach((img, i) => {
+      console.log(`  ${i + 1}. ${img}`);
+    });
+
+    // Check available endpoints for debugging
+    try {
+      const apiInfo = await app.view_api();
+      console.log(
+        `📋 Available endpoints: ${Object.keys(
+          apiInfo.named_endpoints || {}
+        ).join(", ")}`
+      );
+    } catch (e) {
+      console.log("   (Could not fetch API info)");
+    }
+
+    // Prepare file info for logging
+    console.log("Preparing files...");
+    imagePaths.forEach((imgPath, index) => {
+      const stats = fs.statSync(imgPath);
+      const fileSizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+      const name = path.basename(imgPath);
+      console.log(
+        `  File ${index + 1}/${imagePaths.length}: ${name} (${fileSizeMB} MB)`
+      );
+    });
+
+    const totalSizeMB =
+      imagePaths.reduce((sum, imgPath) => {
+        return sum + fs.statSync(imgPath).size;
+      }, 0) /
+      (1024 * 1024);
+    console.log(
+      `✅ All ${imagePaths.length} files ready (total: ${totalSizeMB.toFixed(
+        2
+      )} MB)`
+    );
+    console.log("📤 Uploading files and starting processing...");
+    console.log(
+      "   (The Gradio client will handle file uploads automatically)"
+    );
+    console.log(
+      "   (This may take a few minutes - processing includes 3D reconstruction)"
+    );
+
+    const startTime = Date.now();
+    let result: any;
+    try {
+      console.log("   Calling /process endpoint...");
+      // Pass file paths directly - the Gradio client will handle uploading them
+      // This matches how the Python client works
+      result = (await app.predict("/process", [imagePaths])) as any;
+      const elapsedSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+      console.log(`✅ Processing completed in ${elapsedSeconds} seconds`);
+    } catch (predictError: any) {
+      const elapsedSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+      console.error(`❌ Error after ${elapsedSeconds} seconds:`);
+      console.error("   Error type:", predictError?.constructor?.name);
+      console.error("   Error message:", predictError?.message);
+      if (predictError?.stage) {
+        console.error("   Stage:", predictError.stage);
+      }
+      throw predictError;
+    }
+
+    // Extract results
+    // result.data is an array: [video, ply_url, download, model_ply, model_glb, glb_url]
+    const resultData = result.data || result;
+    const videoPath = resultData[0];
+    const plyUrl = resultData[1];
+    const glbUrl = resultData[5];
+
+    // Check if upload succeeded
+    if (glbUrl && !glbUrl.startsWith("Error")) {
+      return {
+        status: "success",
+        glb_url: glbUrl,
+        ply_url: plyUrl,
+        video_available: videoPath !== null,
+        message: "Processing complete!"
+      };
+    } else {
+      return {
+        status: "error",
+        error: glbUrl || "Upload failed"
+      };
+    }
+  } catch (error) {
+    console.error("Full error details:", error);
+    return {
+      status: "error",
+      error:
+        error instanceof Error
+          ? error.message
+          : JSON.stringify(error, Object.getOwnPropertyNames(error))
+    };
+  }
+}
+
+/**
+ * Download a file from a URL.
+ */
+export async function downloadFile(
+  url: string,
+  outputPath: string
+): Promise<void> {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const buffer = await response.arrayBuffer();
+  fs.writeFileSync(outputPath, Buffer.from(buffer));
+}
+
+/**
+ * Complete workflow: Upload → Process → Download GLB
+ */
+export async function completeWorkflow(
+  imagePaths: string[],
+  outputDir: string = "./outputs",
+  spaceUrl?: string,
+  hfToken?: string
+): Promise<string | null> {
+  console.log("🚀 Processing images...");
+
+  const result = await processImages(imagePaths, spaceUrl, hfToken);
+
+  if (result.status === "error") {
+    console.error(`❌ Error: ${result.error}`);
+    return null;
+  }
+
+  console.log("✅ Processing complete!");
+  console.log(`   GLB URL: ${result.glb_url}`);
+  console.log(`   PLY URL: ${result.ply_url}`);
+
+  // Create output directory
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Download GLB
+  const glbPath = path.join(outputDir, "model.glb");
+  console.log(`📥 Downloading GLB to ${glbPath}...`);
+
+  try {
+    await downloadFile(result.glb_url!, glbPath);
+    console.log(`✅ Downloaded: ${glbPath}`);
+    return glbPath;
+  } catch (error) {
+    console.error(`❌ Download failed: ${error}`);
+    return null;
+  }
+}
+
+/**
+ * CLI interface
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.log(
+      "Usage: npx ts-node api_client.ts <image1> <image2> [image3 ...]"
+    );
+    console.log("\nExample:");
+    console.log("  npx ts-node api_client.ts img1.jpg img2.jpg img3.jpg");
+    console.log("\nEnvironment Variables:");
+    console.log("  INSTANTSPLAT_SPACE - HuggingFace Space URL (optional)");
+    console.log("                       e.g., your-username/InstantSplat");
+    console.log("  HF_TOKEN          - HuggingFace API token (optional)");
+    process.exit(1);
+  }
+
+  const imagePaths = args;
+  const spaceUrl = process.env.INSTANTSPLAT_SPACE;
+  const hfToken = process.env.HF_TOKEN;
+
+  console.log("=".repeat(80));
+  console.log("InstantSplat API Client (TypeScript)");
+  console.log("=".repeat(80));
+
+  const result = await processImages(imagePaths, spaceUrl, hfToken);
+
+  console.log("\n" + "=".repeat(80));
+
+  if (result.status === "success") {
+    console.log("✅ SUCCESS!");
+    console.log("-".repeat(80));
+    console.log(`GLB URL: ${result.glb_url}`);
+    console.log(`PLY URL: ${result.ply_url}`);
+    if (result.video_available) {
+      console.log("Video: Available");
+    }
+    console.log("-".repeat(80));
+    console.log("\n💡 Tip: You can now download the GLB file:");
+    console.log(`   curl -o model.glb '${result.glb_url}'`);
+    console.log("=".repeat(80));
+    process.exit(0);
+  } else {
+    console.log("❌ ERROR!");
+    console.log("-".repeat(80));
+    console.log(`Error: ${result.error}`);
+    console.log("=".repeat(80));
+    process.exit(1);
+  }
+}
+
+// Run CLI if this file is executed directly
+// Check if file is being run directly (ES module compatible)
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  main().catch(console.error);
+}

app.py

@@ -192,208 +192,236 @@ def convert_ply_to_glb(ply_path, glb_path):
 
 @spaces.GPU(duration=150)
 def process(inputfiles, input_path=None):
-
-    if input_path is not None:
-        imgs_path = './assets/example/' + input_path
-        imgs_names = sorted(os.listdir(imgs_path))
-
-        inputfiles = []
-        for imgs_name in imgs_names:
-            file_path = os.path.join(imgs_path, imgs_name)
-            print(file_path)
-            inputfiles.append(file_path)
-        print(inputfiles)
-
-    # ------ (1) Coarse Geometric Initialization ------
-    parser = get_dust3r_args_parser()
-    opt = parser.parse_args()
-
-    tmp_user_folder = str(uuid.uuid4()).replace("-", "")
-    opt.img_base_path = os.path.join(opt.base_path, tmp_user_folder)
-    img_folder_path = os.path.join(opt.img_base_path, "images")    
-
-    model = AsymmetricCroCo3DStereo.from_pretrained(opt.model_path).to(opt.device)
-    os.makedirs(img_folder_path, exist_ok=True)
-
-    opt.n_views = len(inputfiles)  
-    if opt.n_views == 1:
-        raise gr.Error("The number of input images should be greater than 1.")
-    print("Multiple images: ", inputfiles)
-
-    for image_path in inputfiles:
+    """
+    Process images and generate 3D Gaussian Splatting model.
+    Returns: (video_path, ply_url, ply_download, ply_model, glb_model, glb_url)
+    """
+    try:
         if input_path is not None:
-            shutil.copy(image_path, img_folder_path)
-        else:
-            shutil.move(image_path, img_folder_path)
-
-    train_img_list = sorted(os.listdir(img_folder_path))
-    assert len(train_img_list)==opt.n_views, f"Number of images in the folder is not equal to {opt.n_views}"
-
-    images, ori_size, imgs_resolution = load_images(img_folder_path, size=512) 
-    resolutions_are_equal = len(set(imgs_resolution)) == 1
-    if resolutions_are_equal == False:
-        raise gr.Error("The resolution of the input image should be the same.")
-    print("ori_size", ori_size)
-
-    start_time = time.time()
-
-    pairs = make_pairs(images, scene_graph='complete', prefilter=None, symmetrize=True)
-    output = inference(pairs, model, opt.device, batch_size=opt.batch_size)
-    output_colmap_path=img_folder_path.replace("images", "sparse/0")
-    os.makedirs(output_colmap_path, exist_ok=True)
-
-    scene = global_aligner(output, device=opt.device, mode=GlobalAlignerMode.PointCloudOptimizer)
-    loss = compute_global_alignment(scene=scene, init="mst", niter=opt.niter, schedule=opt.schedule, lr=opt.lr, focal_avg=opt.focal_avg)
-    scene = scene.clean_pointcloud()   
-
-    imgs = to_numpy(scene.imgs)
-    focals = scene.get_focals()
-    poses = to_numpy(scene.get_im_poses())
-    pts3d = to_numpy(scene.get_pts3d())
-    scene.min_conf_thr = float(scene.conf_trf(torch.tensor(1.0)))
-    confidence_masks = to_numpy(scene.get_masks())
-    intrinsics = to_numpy(scene.get_intrinsics())
-
-    end_time = time.time()
-    print(f"Time taken for {opt.n_views} views: {end_time-start_time} seconds")
-
-    save_colmap_cameras(ori_size, intrinsics, os.path.join(output_colmap_path, 'cameras.txt'))
-    save_colmap_images(poses, os.path.join(output_colmap_path, 'images.txt'), train_img_list)
-
-    pts_4_3dgs = np.concatenate([p[m] for p, m in zip(pts3d, confidence_masks)])
-    color_4_3dgs = np.concatenate([p[m] for p, m in zip(imgs, confidence_masks)])
-    color_4_3dgs = (color_4_3dgs * 255.0).astype(np.uint8)
-    storePly(os.path.join(output_colmap_path, "points3D.ply"), pts_4_3dgs, color_4_3dgs)
-    pts_4_3dgs_all = np.array(pts3d).reshape(-1, 3)
-    np.save(output_colmap_path + "/pts_4_3dgs_all.npy", pts_4_3dgs_all)
-    np.save(output_colmap_path + "/focal.npy", np.array(focals.cpu()))
-
-    ### save VRAM
-    del scene
-    torch.cuda.empty_cache()
-    gc.collect()
-    ##################################################################################################################################################
-
-    # ------ (2) Fast 3D-Gaussian Optimization ------
-    parser = ArgumentParser(description="Training script parameters")
-    lp = ModelParams(parser)
-    op = OptimizationParams(parser)
-    pp = PipelineParams(parser)
-    parser.add_argument('--debug_from', type=int, default=-1)
-    parser.add_argument("--test_iterations", nargs="+", type=int, default=[])
-    parser.add_argument("--save_iterations", nargs="+", type=int, default=[])
-    parser.add_argument("--checkpoint_iterations", nargs="+", type=int, default=[])
-    parser.add_argument("--start_checkpoint", type=str, default=None)
-    
-    # FIX: scene must be string, not int
-    parser.add_argument("--scene", type=str, default="demo")
-    
-    parser.add_argument("--n_views", type=int, default=3)
-    parser.add_argument("--get_video", action="store_true")
-    parser.add_argument("--optim_pose", type=bool, default=True)
-    parser.add_argument("--skip_train", action="store_true")
-    parser.add_argument("--skip_test", action="store_true")
-    
-    # FIX: do NOT parse system argv
-    args, _ = parser.parse_known_args([])
-    args.save_iterations.append(args.iterations)
-    args.model_path = opt.img_base_path + '/output/'    
-    args.source_path = opt.img_base_path
-    args.iteration = 1000
-    os.makedirs(args.model_path, exist_ok=True)
-
-    training(lp.extract(args), op.extract(args), pp.extract(args), args.test_iterations, args.save_iterations, args.checkpoint_iterations, args.start_checkpoint, args.debug_from, args)
-
-    ##################################################################################################################################################
-
-    # ------ (3) Render video by interpolation ------
-    parser = ArgumentParser(description="Testing script parameters")
-    model = ModelParams(parser, sentinel=True)
-    pipeline = PipelineParams(parser)
-    args.eval = True
-    args.get_video = True
-    args.n_views = opt.n_views
-
-    render_sets(
-        model.extract(args),
-        args.iteration,
-        pipeline.extract(args),
-        args.skip_train,
-        args.skip_test,
-        args,
-    )
-
-    output_ply_path = opt.img_base_path + f'/output/point_cloud/iteration_{args.iteration}/point_cloud.ply'
-    output_video_path = opt.img_base_path + f'/output/demo_{opt.n_views}_view.mp4'
-
-    # sanity checks
-    if not os.path.exists(output_ply_path):
-        print("PLY not found at:", output_ply_path)
-        raise gr.Error(f"PLY file not found at {output_ply_path}")
-
-    if not os.path.exists(output_video_path):
-        print("Video not found at:", output_video_path)
-        raise gr.Error(f"Video file not found at {output_video_path}")
-
-    # Convert PLY to GLB for visualization
-    output_glb_path = output_ply_path.replace('.ply', '.glb')
-    if not convert_ply_to_glb(output_ply_path, output_glb_path):
-        output_glb_path = None
-
-    # ------ (4) upload .ply and .glb to Supabase Storage ------
-    ply_url = None
-    glb_url = None
-    rel_remote_path_ply = f"{tmp_user_folder}_point_cloud.ply"
-    rel_remote_path_glb = f"{tmp_user_folder}_point_cloud.glb"
-    
-    supabase_url = os.environ.get("SUPABASE_URL")
-    supabase_key = os.environ.get("SUPABASE_KEY")
-    supabase_bucket = os.environ.get("SUPABASE_BUCKET", "outputs")
-    
-    if supabase_url and supabase_key:
-        try:
-            # Upload PLY
-            ply_url = upload_to_supabase_storage(
-                file_path=output_ply_path,
-                remote_path=rel_remote_path_ply,
-                supabase_url=supabase_url,
-                supabase_key=supabase_key,
-                bucket_name=supabase_bucket,
-                content_type='application/octet-stream'
-            )
-            
-            if ply_url is None:
-                ply_url = "Error uploading PLY file"
-            
-            # Upload GLB if it exists
-            if output_glb_path and os.path.exists(output_glb_path):
-                glb_url = upload_to_supabase_storage(
-                    file_path=output_glb_path,
-                    remote_path=rel_remote_path_glb,
+            imgs_path = './assets/example/' + input_path
+            imgs_names = sorted(os.listdir(imgs_path))
+
+            inputfiles = []
+            for imgs_name in imgs_names:
+                file_path = os.path.join(imgs_path, imgs_name)
+                print(file_path)
+                inputfiles.append(file_path)
+            print(inputfiles)
+
+        # ------ (1) Coarse Geometric Initialization ------
+        parser = get_dust3r_args_parser()
+        opt = parser.parse_args()
+
+        tmp_user_folder = str(uuid.uuid4()).replace("-", "")
+        opt.img_base_path = os.path.join(opt.base_path, tmp_user_folder)
+        img_folder_path = os.path.join(opt.img_base_path, "images")    
+
+        model = AsymmetricCroCo3DStereo.from_pretrained(opt.model_path).to(opt.device)
+        os.makedirs(img_folder_path, exist_ok=True)
+
+        opt.n_views = len(inputfiles)  
+        if opt.n_views == 1:
+            raise gr.Error("The number of input images should be greater than 1.")
+        print("Multiple images: ", inputfiles)
+
+        for image_path in inputfiles:
+            if input_path is not None:
+                shutil.copy(image_path, img_folder_path)
+            else:
+                shutil.move(image_path, img_folder_path)
+
+        train_img_list = sorted(os.listdir(img_folder_path))
+        assert len(train_img_list)==opt.n_views, f"Number of images in the folder is not equal to {opt.n_views}"
+
+        images, ori_size, imgs_resolution = load_images(img_folder_path, size=512) 
+        resolutions_are_equal = len(set(imgs_resolution)) == 1
+        if resolutions_are_equal == False:
+            raise gr.Error("The resolution of the input image should be the same.")
+        print("ori_size", ori_size)
+
+        start_time = time.time()
+
+        pairs = make_pairs(images, scene_graph='complete', prefilter=None, symmetrize=True)
+        output = inference(pairs, model, opt.device, batch_size=opt.batch_size)
+        output_colmap_path=img_folder_path.replace("images", "sparse/0")
+        os.makedirs(output_colmap_path, exist_ok=True)
+
+        scene = global_aligner(output, device=opt.device, mode=GlobalAlignerMode.PointCloudOptimizer)
+        loss = compute_global_alignment(scene=scene, init="mst", niter=opt.niter, schedule=opt.schedule, lr=opt.lr, focal_avg=opt.focal_avg)
+        scene = scene.clean_pointcloud()   
+
+        imgs = to_numpy(scene.imgs)
+        focals = scene.get_focals()
+        poses = to_numpy(scene.get_im_poses())
+        pts3d = to_numpy(scene.get_pts3d())
+        scene.min_conf_thr = float(scene.conf_trf(torch.tensor(1.0)))
+        confidence_masks = to_numpy(scene.get_masks())
+        intrinsics = to_numpy(scene.get_intrinsics())
+
+        end_time = time.time()
+        print(f"Time taken for {opt.n_views} views: {end_time-start_time} seconds")
+
+        save_colmap_cameras(ori_size, intrinsics, os.path.join(output_colmap_path, 'cameras.txt'))
+        save_colmap_images(poses, os.path.join(output_colmap_path, 'images.txt'), train_img_list)
+
+        pts_4_3dgs = np.concatenate([p[m] for p, m in zip(pts3d, confidence_masks)])
+        color_4_3dgs = np.concatenate([p[m] for p, m in zip(imgs, confidence_masks)])
+        color_4_3dgs = (color_4_3dgs * 255.0).astype(np.uint8)
+        storePly(os.path.join(output_colmap_path, "points3D.ply"), pts_4_3dgs, color_4_3dgs)
+        pts_4_3dgs_all = np.array(pts3d).reshape(-1, 3)
+        np.save(output_colmap_path + "/pts_4_3dgs_all.npy", pts_4_3dgs_all)
+        np.save(output_colmap_path + "/focal.npy", np.array(focals.cpu()))
+
+        ### save VRAM
+        del scene
+        torch.cuda.empty_cache()
+        gc.collect()
+        ##################################################################################################################################################
+
+        # ------ (2) Fast 3D-Gaussian Optimization ------
+        parser = ArgumentParser(description="Training script parameters")
+        lp = ModelParams(parser)
+        op = OptimizationParams(parser)
+        pp = PipelineParams(parser)
+        parser.add_argument('--debug_from', type=int, default=-1)
+        parser.add_argument("--test_iterations", nargs="+", type=int, default=[])
+        parser.add_argument("--save_iterations", nargs="+", type=int, default=[])
+        parser.add_argument("--checkpoint_iterations", nargs="+", type=int, default=[])
+        parser.add_argument("--start_checkpoint", type=str, default=None)
+        
+        # FIX: scene must be string, not int
+        parser.add_argument("--scene", type=str, default="demo")
+        
+        parser.add_argument("--n_views", type=int, default=3)
+        parser.add_argument("--get_video", action="store_true")
+        parser.add_argument("--optim_pose", type=bool, default=True)
+        parser.add_argument("--skip_train", action="store_true")
+        parser.add_argument("--skip_test", action="store_true")
+        
+        # FIX: do NOT parse system argv
+        args, _ = parser.parse_known_args([])
+        args.save_iterations.append(args.iterations)
+        args.model_path = opt.img_base_path + '/output/'    
+        args.source_path = opt.img_base_path
+        args.iteration = 1000
+        os.makedirs(args.model_path, exist_ok=True)
+
+        training(lp.extract(args), op.extract(args), pp.extract(args), args.test_iterations, args.save_iterations, args.checkpoint_iterations, args.start_checkpoint, args.debug_from, args)
+
+        ##################################################################################################################################################
+
+        # ------ (3) Render video by interpolation ------
+        parser = ArgumentParser(description="Testing script parameters")
+        model = ModelParams(parser, sentinel=True)
+        pipeline = PipelineParams(parser)
+        args.eval = True
+        args.get_video = True
+        args.n_views = opt.n_views
+
+        render_sets(
+            model.extract(args),
+            args.iteration,
+            pipeline.extract(args),
+            args.skip_train,
+            args.skip_test,
+            args,
+        )
+
+        output_ply_path = opt.img_base_path + f'/output/point_cloud/iteration_{args.iteration}/point_cloud.ply'
+        output_video_path = opt.img_base_path + f'/output/demo_{opt.n_views}_view.mp4'
+
+        # sanity checks
+        if not os.path.exists(output_ply_path):
+            print("PLY not found at:", output_ply_path)
+            raise gr.Error(f"PLY file not found at {output_ply_path}")
+
+        if not os.path.exists(output_video_path):
+            print("Video not found at:", output_video_path)
+            raise gr.Error(f"Video file not found at {output_video_path}")
+
+        # Convert PLY to GLB for visualization
+        output_glb_path = output_ply_path.replace('.ply', '.glb')
+        if not convert_ply_to_glb(output_ply_path, output_glb_path):
+            output_glb_path = None
+
+        # ------ (4) upload .ply and .glb to Supabase Storage ------
+        ply_url = None
+        glb_url = None
+        rel_remote_path_ply = f"{tmp_user_folder}_point_cloud.ply"
+        rel_remote_path_glb = f"{tmp_user_folder}_point_cloud.glb"
+        
+        supabase_url = os.environ.get("SUPABASE_URL")
+        supabase_key = os.environ.get("SUPABASE_KEY")
+        supabase_bucket = os.environ.get("SUPABASE_BUCKET", "outputs")
+        
+        if supabase_url and supabase_key:
+            try:
+                # Upload PLY
+                ply_url = upload_to_supabase_storage(
+                    file_path=output_ply_path,
+                    remote_path=rel_remote_path_ply,
                     supabase_url=supabase_url,
                     supabase_key=supabase_key,
                     bucket_name=supabase_bucket,
-                    content_type='model/gltf-binary'
+                    content_type='application/octet-stream'
                 )
                 
-                if glb_url is None:
-                    glb_url = "Error uploading GLB file"
+                if ply_url is None:
+                    ply_url = "Error uploading PLY file"
                 
-        except Exception as e:
-            print("Failed to upload files to Supabase Storage:", e)
-            ply_url = f"Error uploading: {e}"
-    else:
-        print("SUPABASE_URL or SUPABASE_KEY not found, skipping upload.")
-        ply_url = "Supabase credentials not set"
-
-    # return:
-    #  1) video path (for gr.Video)
-    #  2) ply URL (for API + textbox)
-    #  3) ply file path (for gr.File download)
-    #  4) ply file path (for gr.Model3D viewer)
-    #  5) glb file path (for gr.Model3D viewer)
-    #  6) glb URL (for API)
-    return output_video_path, ply_url, output_ply_path, output_ply_path, output_glb_path, glb_url
+                # Upload GLB if it exists
+                if output_glb_path and os.path.exists(output_glb_path):
+                    glb_url = upload_to_supabase_storage(
+                        file_path=output_glb_path,
+                        remote_path=rel_remote_path_glb,
+                        supabase_url=supabase_url,
+                        supabase_key=supabase_key,
+                        bucket_name=supabase_bucket,
+                        content_type='model/gltf-binary'
+                    )
+                    
+                    if glb_url is None:
+                        glb_url = "Error uploading GLB file"
+                    
+            except Exception as e:
+                print("Failed to upload files to Supabase Storage:", e)
+                ply_url = f"Error uploading: {e}"
+        else:
+            print("SUPABASE_URL or SUPABASE_KEY not found, skipping upload.")
+            ply_url = "Supabase credentials not set"
+
+        # return:
+        #  1) video path (for gr.Video)
+        #  2) ply URL (for API + textbox)
+        #  3) ply file path (for gr.File download)
+        #  4) ply file path (for gr.Model3D viewer)
+        #  5) glb file path (for gr.Model3D viewer)
+        #  6) glb URL (for API)
+        return output_video_path, ply_url, output_ply_path, output_ply_path, output_glb_path, glb_url
+    
+    except Exception as e:
+        # Catch all errors and return them in the API response
+        error_msg = f"Error: {str(e)}"
+        error_traceback = f"Traceback:\n{__import__('traceback').format_exc()}"
+        full_error = f"{error_msg}\n\n{error_traceback}"
+        
+        print("=" * 80)
+        print("ERROR IN PROCESS FUNCTION:")
+        print("=" * 80)
+        print(full_error)
+        print("=" * 80)
+        
+        # Return error messages in the same format as successful returns
+        # This allows API clients to see the exact error
+        error_prefix = "ERROR: "
+        return (
+            None,  # video path
+            f"{error_prefix}{error_msg}",  # ply_url
+            None,  # ply_download
+            None,  # ply_model
+            None,  # glb_model
+            f"{error_prefix}{error_msg}"  # glb_url
+        )
     ##################################################################################################################################################
 
 
@@ -410,12 +438,19 @@ def process_api(inputfiles):
     """
     result = process(inputfiles, input_path=None)
     video_path, ply_url, _, _, glb_path, glb_url = result
-    
+
+    # Detect error responses by prefix
+    is_error = False
+    for v in (glb_url, ply_url):
+        if isinstance(v, str) and v.startswith("ERROR:"):
+            is_error = True
+            break
+
     return {
         "glb_url": glb_url if glb_url else "Upload failed",
         "ply_url": ply_url if ply_url else "Upload failed",
         "video_available": video_path is not None,
-        "status": "success" if glb_url else "error"
+        "status": "error" if is_error else ("success" if glb_url else "error"),
     }
 
 
@@ -566,7 +601,7 @@ with block:
         inputs=[input_path],
         outputs=[output_video, output_file, output_download, output_model_ply, output_model_glb, output_glb_url],
         fn=lambda x: process(inputfiles=None, input_path=x),
-        cache_examples=True,
+        cache_examples=False,  # Disabled for faster startup
         label='Sparse-view Examples'
     )
 

example_api_usage.ts

@@ -0,0 +1,259 @@
+/**
+ * Example usage of the InstantSplat TypeScript API client
+ * 
+ * Run with: npx tsx example_api_usage.ts
+ */
+
+import { processImages, completeWorkflow } from "./api_client.js";
+
+// Example 1: Simple usage - Get GLB URL
+async function example1() {
+  console.log("\n=== Example 1: Get GLB URL ===\n");
+  
+  const result = await processImages(
+    ["test01/IMG_8533.jpeg", "test01/IMG_8534.jpeg", "test01/IMG_8535.jpeg"],
+    "your-username/InstantSplat" // or use env var
+  );
+
+  if (result.status === "success") {
+    console.log("✅ Success!");
+    console.log("GLB URL:", result.glb_url);
+    console.log("PLY URL:", result.ply_url);
+  } else {
+    console.error("❌ Error:", result.error);
+  }
+}
+
+// Example 2: Complete workflow - Process and download
+async function example2() {
+  console.log("\n=== Example 2: Complete Workflow ===\n");
+  
+  const localPath = await completeWorkflow(
+    ["test01/IMG_8533.jpeg", "test01/IMG_8534.jpeg", "test01/IMG_8535.jpeg"],
+    "./my_models", // output directory
+    "your-username/InstantSplat"
+  );
+
+  if (localPath) {
+    console.log("🎉 Model saved to:", localPath);
+  } else {
+    console.error("Failed to process or download model");
+  }
+}
+
+// Example 3: Batch processing multiple scenes
+async function example3() {
+  console.log("\n=== Example 3: Batch Processing ===\n");
+  
+  const scenes = [
+    ["scene1_img1.jpg", "scene1_img2.jpg", "scene1_img3.jpg"],
+    ["scene2_img1.jpg", "scene2_img2.jpg", "scene2_img3.jpg"],
+  ];
+
+  const results = [];
+
+  for (let i = 0; i < scenes.length; i++) {
+    console.log(`\nProcessing scene ${i + 1}/${scenes.length}...`);
+    
+    const result = await processImages(
+      scenes[i],
+      "your-username/InstantSplat"
+    );
+    
+    results.push({
+      scene: i + 1,
+      ...result
+    });
+
+    // Rate limiting - be nice to the server
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  }
+
+  // Summary
+  console.log("\n=== Batch Processing Summary ===\n");
+  results.forEach(r => {
+    if (r.status === "success") {
+      console.log(`Scene ${r.scene}: ✅ ${r.glb_url}`);
+    } else {
+      console.log(`Scene ${r.scene}: ❌ ${r.error}`);
+    }
+  });
+}
+
+// Example 4: With error handling and retries
+async function example4() {
+  console.log("\n=== Example 4: With Retries ===\n");
+  
+  async function processWithRetry(
+    images: string[], 
+    maxRetries: number = 3
+  ) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      console.log(`Attempt ${attempt}/${maxRetries}...`);
+      
+      const result = await processImages(
+        images,
+        "your-username/InstantSplat"
+      );
+
+      if (result.status === "success") {
+        return result;
+      }
+
+      console.log(`Failed: ${result.error}`);
+      
+      if (attempt < maxRetries) {
+        const delay = Math.pow(2, attempt) * 1000; // exponential backoff
+        console.log(`Retrying in ${delay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+
+    throw new Error("All retry attempts failed");
+  }
+
+  try {
+    const result = await processWithRetry([
+      "test01/IMG_8533.jpeg",
+      "test01/IMG_8534.jpeg", 
+      "test01/IMG_8535.jpeg"
+    ]);
+    
+    console.log("✅ Success after retry!");
+    console.log("GLB URL:", result.glb_url);
+  } catch (error) {
+    console.error("❌ Failed after all retries:", error);
+  }
+}
+
+// Example 5: Integration with Express.js API
+function example5Code() {
+  return `
+// Express.js API endpoint example
+import express from 'express';
+import { processImages } from './api_client';
+
+const app = express();
+
+app.post('/api/process-images', async (req, res) => {
+  try {
+    const { images } = req.body; // Array of image paths or URLs
+    
+    const result = await processImages(
+      images,
+      process.env.INSTANTSPLAT_SPACE
+    );
+
+    if (result.status === 'success') {
+      res.json({
+        success: true,
+        glb_url: result.glb_url,
+        ply_url: result.ply_url
+      });
+    } else {
+      res.status(500).json({
+        success: false,
+        error: result.error
+      });
+    }
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: String(error)
+    });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('API running on http://localhost:3000');
+});
+`;
+}
+
+// Example 6: React component integration
+function example6Code() {
+  return `
+// React component example
+import { useState } from 'react';
+import { processImages } from './api_client';
+
+function InstantSplatUploader() {
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState(null);
+
+  const handleSubmit = async (files: File[]) => {
+    setLoading(true);
+    
+    try {
+      // Convert files to paths or upload them first
+      const imagePaths = files.map(f => f.path);
+      
+      const result = await processImages(
+        imagePaths,
+        process.env.NEXT_PUBLIC_INSTANTSPLAT_SPACE
+      );
+      
+      setResult(result);
+    } catch (error) {
+      console.error(error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      {loading && <p>Processing...</p>}
+      
+      {result?.status === 'success' && (
+        <div>
+          <h3>Your 3D Model:</h3>
+          <a href={result.glb_url}>Download GLB</a>
+          <a href={result.ply_url}>Download PLY</a>
+        </div>
+      )}
+      
+      {result?.status === 'error' && (
+        <p>Error: {result.error}</p>
+      )}
+    </div>
+  );
+}
+`;
+}
+
+// Run examples
+async function main() {
+  console.log("InstantSplat API - TypeScript Examples");
+  console.log("=" .repeat(80));
+
+  // Uncomment the examples you want to run:
+  
+  // await example1(); // Simple usage
+  // await example2(); // Complete workflow
+  // await example3(); // Batch processing
+  // await example4(); // With retries
+
+  // Code examples (not executable):
+  console.log("\n=== Example 5: Express.js Integration ===");
+  console.log(example5Code());
+
+  console.log("\n=== Example 6: React Component ===");
+  console.log(example6Code());
+
+  console.log("\n💡 Uncomment the examples in main() to run them!");
+}
+
+// Run if this file is executed directly (ES module compatible)
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  main().catch(console.error);
+}
+
+export {
+  example1,
+  example2,
+  example3,
+  example4
+};
+