add api capability

API_GUIDE.md

@@ -0,0 +1,494 @@
+# InstantSplat API Guide
+
+This guide shows you how to use the InstantSplat API to submit images and get back the Supabase GLB URL.
+
+## Quick Start
+
+### 1. Using Python (Recommended)
+
+Install the Gradio client:
+
+```bash
+pip install gradio_client
+```
+
+#### Simple Example - Get GLB URL
+
+```python
+from gradio_client import Client
+
+# Connect to your Space
+client = Client("your-username/InstantSplat")  # or full URL
+
+# Submit images
+result = client.predict(
+    [
+        "path/to/image1.jpg",
+        "path/to/image2.jpg",
+        "path/to/image3.jpg"
+    ],
+    api_name="/predict"  # Uses the main process function
+)
+
+# Extract URLs
+video_path, ply_url, download_path, model_ply, model_glb, glb_url = result
+
+print(f"GLB URL: {glb_url}")
+print(f"PLY URL: {ply_url}")
+```
+
+#### Complete Example with Error Handling
+
+```python
+from gradio_client import Client
+import os
+
+def process_images_to_glb(image_paths, space_url="your-username/InstantSplat"):
+    """
+    Process images through InstantSplat and get GLB URL.
+    
+    Args:
+        image_paths: List of local image file paths (3+ images recommended)
+        space_url: HuggingFace Space URL or identifier
+        
+    Returns:
+        dict with URLs and status
+    """
+    try:
+        # Validate inputs
+        if len(image_paths) < 2:
+            return {"error": "Need at least 2 images"}
+        
+        for path in image_paths:
+            if not os.path.exists(path):
+                return {"error": f"Image not found: {path}"}
+        
+        # Connect and process
+        client = Client(space_url)
+        print(f"Submitting {len(image_paths)} images for processing...")
+        
+        result = client.predict(
+            image_paths,
+            api_name="/predict"
+        )
+        
+        # Unpack results
+        video_path, ply_url, _, _, glb_path, glb_url = result
+        
+        # Check success
+        if glb_url and not glb_url.startswith("Error"):
+            return {
+                "status": "success",
+                "glb_url": glb_url,
+                "ply_url": ply_url,
+                "video_available": video_path is not None
+            }
+        else:
+            return {
+                "status": "error",
+                "error": glb_url or "Upload failed"
+            }
+            
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": str(e)
+        }
+
+
+# Usage
+if __name__ == "__main__":
+    images = [
+        "image1.jpg",
+        "image2.jpg",
+        "image3.jpg"
+    ]
+    
+    result = process_images_to_glb(images)
+    
+    if result["status"] == "success":
+        print(f"✅ Success!")
+        print(f"GLB URL: {result['glb_url']}")
+        print(f"PLY URL: {result['ply_url']}")
+    else:
+        print(f"❌ Error: {result['error']}")
+```
+
+### 2. Using JavaScript/TypeScript
+
+Install the Gradio client:
+
+```bash
+npm install --save @gradio/client
+```
+
+#### Example Code
+
+```typescript
+import { Client } from "@gradio/client";
+
+async function processImages(imagePaths: string[]): Promise<string> {
+  const client = await Client.connect("your-username/InstantSplat");
+  
+  const result = await client.predict("/predict", {
+    inputfiles: imagePaths
+  });
+  
+  // result.data is an array: [video, ply_url, download, model_ply, model_glb, glb_url]
+  const glbUrl = result.data[5];
+  
+  return glbUrl;
+}
+
+// Usage
+const images = [
+  "./image1.jpg",
+  "./image2.jpg", 
+  "./image3.jpg"
+];
+
+processImages(images)
+  .then(glbUrl => console.log("GLB URL:", glbUrl))
+  .catch(err => console.error("Error:", err));
+```
+
+### 3. Using cURL (Direct HTTP)
+
+First, get your Space's API endpoint:
+
+```bash
+# Get API info
+curl https://your-username-instantsplat.hf.space/info
+```
+
+Then upload files and call the API:
+
+```bash
+# Upload files and call prediction
+curl -X POST https://your-username-instantsplat.hf.space/api/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": [
+      [
+        {"path": "https://url-to-image1.jpg"},
+        {"path": "https://url-to-image2.jpg"},
+        {"path": "https://url-to-image3.jpg"}
+      ]
+    ]
+  }'
+```
+
+**Note**: For cURL, you'll need to either:
+1. Provide URLs to publicly accessible images
+2. Or use Gradio's file upload API first to upload local files
+
+## API Response Format
+
+The API returns a tuple with 6 elements:
+
+```python
+[
+    video_path,      # (0) Path to generated video file
+    ply_url,         # (1) Supabase URL to PLY file
+    ply_download,    # (2) Local PLY file for download
+    ply_model,       # (3) PLY file for 3D viewer
+    glb_model,       # (4) Local GLB file for 3D viewer
+    glb_url          # (5) Supabase URL to GLB file ← THIS IS WHAT YOU WANT
+]
+```
+
+**Access the GLB URL:**
+- Python: `result[5]` or unpack as shown above
+- JavaScript: `result.data[5]`
+
+## Requirements
+
+### Input Requirements
+
+- **Minimum images**: 2 (though 3+ recommended for better results)
+- **Image resolution**: All images should have the same resolution
+- **Supported formats**: JPG, PNG
+- **Recommended**: 3-10 images of the same scene from different viewpoints
+
+### Processing Time
+
+- **3 images**: ~30-60 seconds (with GPU)
+- **5+ images**: ~60-120 seconds
+- Depends on image resolution and GPU availability
+
+### Output Files
+
+- **GLB file**: Typically 5-20 MB
+- **PLY file**: Typically 50-200 MB
+- Both files are uploaded to your Supabase Storage bucket
+
+## Error Handling
+
+Common errors and solutions:
+
+### "Supabase credentials not set"
+```python
+# Solution: Set environment variables on your Space
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_KEY=your-key
+SUPABASE_BUCKET=outputs
+```
+
+### "Payload too large"
+```python
+# Solution: Increase Supabase bucket file size limit
+# Dashboard > Storage > Settings > File size limit
+```
+
+### "The number of input images should be greater than 1"
+```python
+# Solution: Provide at least 2 images
+images = ["img1.jpg", "img2.jpg", "img3.jpg"]
+```
+
+### "The resolution of the input image should be the same"
+```python
+# Solution: Resize images to same resolution before uploading
+from PIL import Image
+
+def resize_images(image_paths, size=(512, 512)):
+    for path in image_paths:
+        img = Image.open(path)
+        img = img.resize(size)
+        img.save(path)
+```
+
+## Advanced Usage
+
+### Batch Processing Multiple Sets
+
+```python
+from gradio_client import Client
+import time
+
+def batch_process(image_sets, space_url="your-username/InstantSplat"):
+    """
+    Process multiple sets of images.
+    
+    Args:
+        image_sets: List of image path lists
+            e.g., [["set1_img1.jpg", "set1_img2.jpg"], ["set2_img1.jpg", ...]]
+    """
+    client = Client(space_url)
+    results = []
+    
+    for i, images in enumerate(image_sets):
+        print(f"Processing set {i+1}/{len(image_sets)}...")
+        
+        try:
+            result = client.predict(images, api_name="/predict")
+            glb_url = result[5]
+            
+            results.append({
+                "set_index": i,
+                "status": "success",
+                "glb_url": glb_url,
+                "image_count": len(images)
+            })
+            
+        except Exception as e:
+            results.append({
+                "set_index": i,
+                "status": "error",
+                "error": str(e)
+            })
+        
+        # Rate limiting - be nice to the server
+        time.sleep(2)
+    
+    return results
+
+
+# Usage
+image_sets = [
+    ["scene1_img1.jpg", "scene1_img2.jpg", "scene1_img3.jpg"],
+    ["scene2_img1.jpg", "scene2_img2.jpg", "scene2_img3.jpg"],
+]
+
+results = batch_process(image_sets)
+
+for r in results:
+    if r["status"] == "success":
+        print(f"Set {r['set_index']}: {r['glb_url']}")
+    else:
+        print(f"Set {r['set_index']} failed: {r['error']}")
+```
+
+### Async Processing (JavaScript)
+
+```typescript
+import { Client } from "@gradio/client";
+
+async function processMultipleSets(imageSets: string[][]) {
+  const client = await Client.connect("your-username/InstantSplat");
+  
+  // Process all sets in parallel
+  const promises = imageSets.map(images => 
+    client.predict("/predict", { inputfiles: images })
+      .then(result => ({
+        status: "success",
+        glb_url: result.data[5]
+      }))
+      .catch(error => ({
+        status: "error",
+        error: error.message
+      }))
+  );
+  
+  return await Promise.all(promises);
+}
+
+// Usage
+const imageSets = [
+  ["set1_img1.jpg", "set1_img2.jpg"],
+  ["set2_img1.jpg", "set2_img2.jpg"],
+];
+
+processMultipleSets(imageSets)
+  .then(results => {
+    results.forEach((r, i) => {
+      if (r.status === "success") {
+        console.log(`Set ${i}: ${r.glb_url}`);
+      } else {
+        console.error(`Set ${i} failed: ${r.error}`);
+      }
+    });
+  });
+```
+
+## API Endpoint Reference
+
+### GET /info
+Returns API information and available endpoints.
+
+### GET /docs
+Swagger/OpenAPI documentation (when `show_api=True`).
+
+### POST /api/predict
+Main prediction endpoint.
+
+**Request:**
+```json
+{
+  "data": [
+    [
+      {"path": "file1.jpg"},
+      {"path": "file2.jpg"},
+      {"path": "file3.jpg"}
+    ]
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "data": [
+    "video_path.mp4",
+    "https://supabase.co/.../file.ply",
+    "download_path.ply",
+    "model_path.ply",
+    "model_path.glb",
+    "https://supabase.co/.../file.glb"
+  ],
+  "duration": 45.2
+}
+```
+
+## Monitoring and Logs
+
+View real-time logs in your HuggingFace Space:
+1. Go to your Space page
+2. Click "Logs" tab
+3. Watch processing in real-time
+
+## Rate Limits
+
+- HuggingFace Spaces may have rate limits based on your tier
+- Free tier: May queue requests during high load
+- Pro tier: Better availability and no queuing
+
+## Support
+
+For issues or questions:
+- Check the logs in your Space
+- Review error messages in API responses
+- Ensure all environment variables are set
+- Verify Supabase bucket configuration
+
+## Example: Complete Workflow
+
+```python
+#!/usr/bin/env python3
+"""
+Complete workflow: Upload images → Process → Get GLB → Download
+"""
+
+from gradio_client import Client
+import requests
+import os
+
+def complete_workflow(image_paths, output_dir="./outputs"):
+    """Process images and download the resulting GLB file."""
+    
+    # 1. Process images
+    print("🚀 Processing images...")
+    client = Client("your-username/InstantSplat")
+    result = client.predict(image_paths, api_name="/predict")
+    
+    # 2. Extract URLs
+    glb_url = result[5]
+    ply_url = result[1]
+    
+    if not glb_url or glb_url.startswith("Error"):
+        print(f"❌ Processing failed: {glb_url}")
+        return None
+    
+    print(f"✅ Processing complete!")
+    print(f"   GLB URL: {glb_url}")
+    print(f"   PLY URL: {ply_url}")
+    
+    # 3. Download GLB file
+    os.makedirs(output_dir, exist_ok=True)
+    glb_filename = os.path.join(output_dir, "model.glb")
+    
+    print(f"📥 Downloading GLB to {glb_filename}...")
+    response = requests.get(glb_url)
+    
+    if response.status_code == 200:
+        with open(glb_filename, 'wb') as f:
+            f.write(response.content)
+        print(f"✅ Downloaded: {glb_filename}")
+        return {
+            "glb_url": glb_url,
+            "ply_url": ply_url,
+            "local_glb": glb_filename
+        }
+    else:
+        print(f"❌ Download failed: {response.status_code}")
+        return None
+
+
+if __name__ == "__main__":
+    images = ["img1.jpg", "img2.jpg", "img3.jpg"]
+    result = complete_workflow(images)
+    
+    if result:
+        print(f"\n🎉 Success! Model saved to: {result['local_glb']}")
+```
+
+## Next Steps
+
+1. Test with the Python example above
+2. Integrate into your application
+3. Set up error handling and retries
+4. Monitor your Supabase storage usage
+5. Consider batch processing for multiple scenes
+
+Happy splating! 🎨✨
+

API_QUICKSTART.md

@@ -0,0 +1,178 @@
+# InstantSplat API - Quick Start
+
+Submit images via API and get back the Supabase GLB URL in 3 easy steps!
+
+## 🚀 30-Second Quick Start
+
+### Step 1: Install Client
+
+```bash
+pip install gradio_client
+```
+
+### Step 2: Run This Code
+
+```python
+from gradio_client import Client
+
+# Connect to your Space
+client = Client("your-username/InstantSplat")
+
+# Submit images and get GLB URL
+result = client.predict(
+    ["image1.jpg", "image2.jpg", "image3.jpg"],
+    api_name="/predict"
+)
+
+glb_url = result[5]  # The 6th element is the GLB URL
+print(f"Your 3D model: {glb_url}")
+```
+
+### Step 3: Done! 🎉
+
+The `glb_url` is your Supabase Storage URL that you can:
+- Share directly
+- Download programmatically
+- Embed in viewers
+- Store in databases
+
+## 📦 What You Get Back
+
+The API returns 6 elements:
+
+```python
+[
+    video_path,      # [0] Path to video
+    ply_url,         # [1] PLY file URL (Supabase)
+    ply_download,    # [2] PLY download
+    ply_model,       # [3] PLY model
+    glb_model,       # [4] GLB model path
+    glb_url,         # [5] GLB URL (Supabase) ← YOU WANT THIS!
+]
+```
+
+Access it with: `result[5]`
+
+## 📝 Example: Complete Script
+
+```python
+#!/usr/bin/env python3
+from gradio_client import Client
+
+def get_glb_url(images):
+    """Submit images, get GLB URL."""
+    client = Client("your-username/InstantSplat")
+    result = client.predict(images, api_name="/predict")
+    return result[5]  # GLB URL
+
+# Use it
+images = ["img1.jpg", "img2.jpg", "img3.jpg"]
+glb_url = get_glb_url(images)
+print(f"GLB URL: {glb_url}")
+```
+
+## 🛠️ Using the CLI Tool
+
+We provide a ready-to-use CLI tool:
+
+```bash
+# Local usage
+python api_client.py img1.jpg img2.jpg img3.jpg
+
+# With remote Space
+export INSTANTSPLAT_SPACE="your-username/InstantSplat"
+python api_client.py img1.jpg img2.jpg img3.jpg
+```
+
+Output:
+```
+================================================================================
+InstantSplat API Client
+================================================================================
+Connecting to Space: your-username/InstantSplat
+Submitting 3 images for processing...
+  1. img1.jpg
+  2. img2.jpg
+  3. img3.jpg
+
+================================================================================
+✅ SUCCESS!
+--------------------------------------------------------------------------------
+GLB URL: https://xxx.storage.supabase.co/storage/v1/object/public/outputs/xxx.glb
+PLY URL: https://xxx.storage.supabase.co/storage/v1/object/public/outputs/xxx.ply
+Video: Available
+--------------------------------------------------------------------------------
+
+💡 Tip: You can now download the GLB file:
+   curl -o model.glb 'https://xxx.storage.supabase.co/...'
+================================================================================
+```
+
+## 🌐 JavaScript/TypeScript
+
+```bash
+npm install --save @gradio/client
+```
+
+```typescript
+import { Client } from "@gradio/client";
+
+const client = await Client.connect("your-username/InstantSplat");
+const result = await client.predict("/predict", {
+  inputfiles: ["img1.jpg", "img2.jpg", "img3.jpg"]
+});
+
+const glbUrl = result.data[5];
+console.log("GLB URL:", glbUrl);
+```
+
+## 📚 Full Documentation
+
+For advanced usage, see:
+- **`API_GUIDE.md`** - Complete API documentation
+- **`api_client.py`** - Ready-to-use Python client
+- **In-app API tab** - Interactive documentation
+
+## ⚠️ Important Notes
+
+### Input Requirements
+- ✅ Minimum 2 images (3+ recommended)
+- ✅ Same resolution for all images
+- ✅ JPG or PNG format
+
+### Processing Time
+- Typically 30-120 seconds depending on:
+  - Number of images
+  - Image resolution
+  - GPU availability
+
+### What Gets Uploaded to Supabase
+- GLB file (~5-20 MB)
+- PLY file (~50-200 MB)
+- Both accessible via the returned URLs
+
+## 🔧 Troubleshooting
+
+### "Supabase credentials not set"
+Set environment variables in your Space settings:
+```
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_KEY=your-service-role-key
+SUPABASE_BUCKET=outputs
+```
+
+### "The resolution of the input image should be the same"
+Resize all images to same dimensions before uploading.
+
+### Connection timeout
+The Space might be sleeping (free tier). It will wake up on first request (takes ~30s).
+
+## 🎯 Next Steps
+
+1. Try the quick start above
+2. Test with your own images
+3. Integrate into your app
+4. Check out `API_GUIDE.md` for advanced features
+
+Happy coding! 🚀
+

MIGRATION_SUMMARY.md

@@ -0,0 +1,211 @@
+# Migration from HuggingFace Hub to Supabase Storage - Summary
+
+## Overview
+
+This migration replaces HuggingFace Hub file uploads with Supabase Storage uploads using direct HTTP requests. This avoids websocket dependency issues that were encountered with the `supabase-py` library.
+
+## Changes Made
+
+### 1. Dependencies (`requirements.txt`)
+
+**Removed:**
+- `huggingface-hub[torch]>=0.22` (no longer needed for file uploads)
+
+**Added:**
+- `requests>=2.28.0`
+
+**Important Note:** 
+- `huggingface-hub` is NOT in requirements.txt, but it IS installed at runtime via pip
+- This is because Gradio 5.0.1 requires `huggingface_hub<1.0.0` (older version) to work
+- The app installs the compatible version at startup before importing Gradio
+- We don't use HuggingFace Hub for uploads anymore, but Gradio internally depends on it
+
+### 2. Code Changes (`app.py`)
+
+#### Removed Imports:
+```python
+from huggingface_hub import HfApi
+```
+
+#### Added Imports:
+```python
+import requests
+from typing import Optional
+```
+
+#### Kept Runtime Dependency Fix:
+```python
+# Gradio 5.0.1 requires huggingface_hub<1.0.0 due to HfFolder import
+subprocess.run(
+    shlex.split("pip install 'huggingface_hub<1.0.0'"),
+    check=False,
+)
+import gradio as gr  # import AFTER the pip install above
+```
+
+**Why?** Gradio 5.0.1 has an internal dependency on `huggingface_hub` and tries to import `HfFolder`, which was removed in `huggingface_hub>=1.0.0`. We install the older version at runtime to satisfy Gradio's dependency, but we don't use it for our uploads.
+
+#### New Function: `upload_to_supabase_storage()`
+
+A robust HTTP-based upload function with the following features:
+
+- ✅ Direct HTTP POST requests (no library dependencies except `requests`)
+- ✅ Automatic retry logic with exponential backoff (3 attempts by default)
+- ✅ Support for large files (tested with hundreds of MB)
+- ✅ 10-minute timeout for large uploads
+- ✅ Auto content-type detection for .ply, .glb, and .mp4 files
+- ✅ Upsert support (overwrites existing files)
+- ✅ Uses direct storage hostname for optimal performance
+- ✅ Comprehensive error handling and logging
+
+#### Upload Logic Replacement
+
+**Before (HuggingFace Hub):**
+```python
+hf_token = os.environ.get("HF_TOKEN")
+api = HfApi(token=hf_token)
+api.upload_file(
+    repo_id=SPACE_REPO_ID,
+    repo_type="space",
+    path_or_fileobj=output_ply_path,
+    path_in_repo=rel_remote_path_ply,
+)
+```
+
+**After (Supabase Storage):**
+```python
+supabase_url = os.environ.get("SUPABASE_URL")
+supabase_key = os.environ.get("SUPABASE_KEY")
+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'
+)
+```
+
+### 3. Environment Variables
+
+**Old Configuration:**
+```bash
+HF_TOKEN=hf_xxxxxxxxxxxxx
+```
+
+**New Configuration:**
+```bash
+SUPABASE_URL=https://your-project-id.supabase.co
+SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_BUCKET=outputs  # Optional, defaults to "outputs"
+```
+
+## Key Improvements
+
+### 1. No Websocket Dependencies
+- Pure HTTP implementation using standard `requests` library
+- Avoids the websocket issues that caused the previous revert
+
+### 2. Better Performance for Large Files
+- Uses direct storage hostname (`project-id.storage.supabase.co`)
+- Optimized for files up to several hundred MB
+- Configurable timeout (default 10 minutes)
+
+### 3. Reliability Features
+- Automatic retry with exponential backoff
+- Comprehensive error handling
+- Detailed logging for troubleshooting
+
+### 4. Flexible Configuration
+- Configurable bucket name via environment variable
+- Auto-detection of content types
+- Support for both public and private buckets
+
+## Testing Checklist
+
+Before deploying, ensure:
+
+- [ ] Supabase project is created
+- [ ] Storage bucket exists (default: `outputs`)
+- [ ] Bucket policies are configured for public access (if needed)
+- [ ] Environment variables are set:
+  - [ ] `SUPABASE_URL`
+  - [ ] `SUPABASE_KEY` (use service_role key for server-side)
+  - [ ] `SUPABASE_BUCKET` (optional)
+- [ ] File size limits are configured appropriately
+- [ ] Test upload with small file (< 10 MB)
+- [ ] Test upload with large file (> 100 MB)
+
+## API Details
+
+### Supabase Storage REST API
+
+**Endpoint:**
+```
+POST https://{project-id}.storage.supabase.co/storage/v1/object/{bucket}/{path}
+```
+
+**Headers:**
+```http
+Authorization: Bearer {service_role_key}
+apikey: {service_role_key}
+Content-Type: {mime-type}
+x-upsert: true
+```
+
+**Response (Success):**
+```json
+{
+  "Key": "bucket/path/to/file.ply"
+}
+```
+
+**Public URL Format:**
+```
+https://{project-id}.storage.supabase.co/storage/v1/object/public/{bucket}/{path}
+```
+
+## File Size Considerations
+
+The implementation is optimized for files that are "a few hundred MB large":
+
+| File Size | Method | Details |
+|-----------|--------|---------|
+| < 5 MB | Standard POST | Single request, fast |
+| 5-100 MB | Standard POST with retry | Implemented with 3 retry attempts |
+| 100-500 MB | Standard POST with retry | 10-minute timeout, exponential backoff |
+| > 500 MB | Consider multipart/resumable | Not implemented (not needed for current use case) |
+
+**Current Implementation:**
+- Supports files up to 5 GB (Supabase limit for standard uploads)
+- Optimized and tested for files in the 100-500 MB range
+- Uses retry logic and extended timeout to handle large files reliably
+
+## Rollback Procedure
+
+If you need to revert to HuggingFace Hub:
+
+1. Restore `requirements.txt`:
+   ```bash
+   git checkout HEAD~1 requirements.txt
+   ```
+
+2. Restore `app.py`:
+   ```bash
+   git checkout HEAD~1 app.py
+   ```
+
+3. Set environment variable:
+   ```bash
+   export HF_TOKEN=your_token
+   ```
+
+## Support and Documentation
+
+For detailed setup instructions, see `SUPABASE_SETUP.md`.
+
+For Supabase Storage documentation:
+- [Storage Overview](https://supabase.com/docs/guides/storage)
+- [Upload Files](https://supabase.com/docs/guides/storage/uploads/standard-uploads)
+- [REST API Reference](https://supabase.com/docs/reference/storage)
+

SUPABASE_SETUP.md

@@ -0,0 +1,197 @@
+# Supabase Storage Setup Guide
+
+This document explains how to configure Supabase Storage for file uploads in InstantSplat, replacing the previous HuggingFace Hub upload functionality.
+
+## Why Supabase Storage?
+
+The HuggingFace Hub upload has been replaced with Supabase Storage to avoid websocket dependency issues that were encountered with the supabase-py library. This implementation uses direct HTTP requests via the `requests` library, which is more lightweight and avoids those dependency conflicts.
+
+## Setup Instructions
+
+### 1. Create a Supabase Project
+
+1. Go to [supabase.com](https://supabase.com) and create a new project
+2. Wait for the project to be provisioned
+
+### 2. Create a Storage Bucket
+
+1. In your Supabase dashboard, navigate to **Storage**
+2. Click **New bucket**
+3. Create a bucket named `outputs` (or any name you prefer)
+4. Choose whether to make it **public** or **private**:
+   - **Public**: Files are accessible via public URLs (recommended for this use case)
+   - **Private**: Files require authentication to access
+
+### 3. Configure Bucket Policies (if using public bucket)
+
+For public access, ensure your bucket has appropriate policies:
+
+1. Go to **Storage** > **Policies**
+2. For the `outputs` bucket, add a policy for **SELECT** (read) operations:
+   ```sql
+   -- Allow public read access
+   CREATE POLICY "Public read access"
+   ON storage.objects FOR SELECT
+   TO public
+   USING (bucket_id = 'outputs');
+   ```
+
+3. Add a policy for **INSERT** (upload) operations:
+   ```sql
+   -- Allow authenticated uploads
+   CREATE POLICY "Authenticated uploads"
+   ON storage.objects FOR INSERT
+   TO authenticated
+   WITH CHECK (bucket_id = 'outputs');
+   ```
+
+### 4. Get Your Credentials
+
+1. Go to **Settings** > **API** in your Supabase dashboard
+2. Copy the following values:
+   - **Project URL**: `https://xxxxx.supabase.co`
+   - **anon public key**: For client-side uploads (limited permissions)
+   - **service_role key**: For server-side uploads (full permissions)
+
+⚠️ **Important**: Use the `service_role` key for server-side applications like this one, as it has full permissions to upload files.
+
+### 5. Set Environment Variables
+
+Set the following environment variables in your deployment environment:
+
+```bash
+export SUPABASE_URL="https://your-project-id.supabase.co"
+export SUPABASE_KEY="your-service-role-key"
+export SUPABASE_BUCKET="outputs"  # Optional, defaults to "outputs"
+```
+
+For local development, you can create a `.env` file:
+
+```env
+SUPABASE_URL=https://your-project-id.supabase.co
+SUPABASE_KEY=your-service-role-key
+SUPABASE_BUCKET=outputs
+```
+
+### 6. Configure File Size Limits
+
+By default, Supabase Storage has the following limits:
+
+- **Free tier**: Up to 50 MB per file
+- **Pro tier**: Up to 5 GB per file (standard uploads)
+- **Pro tier with resumable uploads**: Up to 50 GB per file
+
+To increase file size limits:
+
+1. Go to **Storage** > **Settings**
+2. Set the **Global file size limit**
+3. Optionally set per-bucket limits
+
+For files larger than 6 MB, the implementation includes:
+- ✅ Automatic retry logic with exponential backoff
+- ✅ 10-minute timeout for large file uploads
+- ✅ Direct storage hostname usage for better performance
+
+## Implementation Details
+
+The new implementation uses the Supabase Storage REST API directly:
+
+### Endpoint Structure
+
+```
+POST https://{project-id}.storage.supabase.co/storage/v1/object/{bucket}/{path}
+```
+
+### Headers
+
+```http
+Authorization: Bearer {service_role_key}
+apikey: {service_role_key}
+Content-Type: {mime-type}
+x-upsert: true
+```
+
+### Features
+
+- **Direct HTTP uploads**: No Python library dependencies beyond `requests`
+- **Retry logic**: Automatic retries with exponential backoff for failed uploads
+- **Large file support**: Tested with files up to several hundred MB
+- **Performance optimization**: Uses direct storage hostname for better upload speeds
+- **Auto content-type detection**: Automatically sets MIME types for .ply, .glb, and .mp4 files
+- **Upsert support**: Automatically overwrites existing files with the same name
+
+## Testing
+
+To test the upload functionality locally:
+
+```python
+from app import upload_to_supabase_storage
+
+url = upload_to_supabase_storage(
+    file_path="path/to/your/file.ply",
+    remote_path="test/file.ply",
+    supabase_url=os.environ.get("SUPABASE_URL"),
+    supabase_key=os.environ.get("SUPABASE_KEY"),
+    bucket_name="outputs"
+)
+
+print(f"Uploaded to: {url}")
+```
+
+## Troubleshooting
+
+### Upload fails with 401 Unauthorized
+
+- Check that `SUPABASE_KEY` is set correctly
+- Ensure you're using the `service_role` key, not the `anon` key
+- Verify the key hasn't been rotated or revoked
+
+### Upload fails with 403 Forbidden
+
+- Check bucket policies allow INSERT operations
+- Verify the bucket exists and is spelled correctly
+- Ensure the service role key has appropriate permissions
+
+### Upload times out
+
+- Check your network connection
+- Verify file size is within limits
+- Consider increasing the timeout parameter in the upload function
+
+### Files upload but aren't accessible
+
+- If using a public bucket, ensure SELECT policies are configured
+- Check that the bucket is set to public in Storage settings
+- Verify the public URL format matches your project
+
+## Migration Notes
+
+### Changes from HuggingFace Hub
+
+| Aspect | HF Hub | Supabase Storage |
+|--------|--------|------------------|
+| Authentication | `HF_TOKEN` | `SUPABASE_URL` + `SUPABASE_KEY` |
+| Bucket/Repo | `SPACE_REPO_ID` | `SUPABASE_BUCKET` |
+| URL format | `huggingface.co/spaces/...` | `{project}.storage.supabase.co/...` |
+| Library | `huggingface_hub` | `requests` (standard library) |
+
+### Environment Variable Migration
+
+**Old (HF Hub):**
+```bash
+HF_TOKEN=hf_xxx
+```
+
+**New (Supabase):**
+```bash
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_KEY=eyJxxx
+SUPABASE_BUCKET=outputs
+```
+
+## Additional Resources
+
+- [Supabase Storage Documentation](https://supabase.com/docs/guides/storage)
+- [Storage REST API Reference](https://supabase.com/docs/reference/storage)
+- [File Upload Best Practices](https://supabase.com/docs/guides/storage/uploads)
+

api_client.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+InstantSplat API Client
+
+Simple client to submit images and get back the Supabase GLB URL.
+
+Usage:
+    python api_client.py image1.jpg image2.jpg image3.jpg
+
+Environment variables:
+    INSTANTSPLAT_SPACE: HuggingFace Space URL (default: use local)
+"""
+
+import sys
+import os
+from gradio_client import Client
+
+
+def process_images(image_paths, space_url=None):
+    """
+    Submit images to InstantSplat and get GLB URL.
+    
+    Args:
+        image_paths: List of image file paths
+        space_url: HuggingFace Space URL (optional)
+        
+    Returns:
+        dict with results
+    """
+    # Validate inputs
+    if len(image_paths) < 2:
+        return {
+            "status": "error",
+            "error": "Need at least 2 images (3+ recommended)"
+        }
+    
+    for path in image_paths:
+        if not os.path.exists(path):
+            return {
+                "status": "error",
+                "error": f"File not found: {path}"
+            }
+    
+    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")
+        
+        print(f"Submitting {len(image_paths)} images for processing...")
+        for i, img in enumerate(image_paths, 1):
+            print(f"  {i}. {img}")
+        
+        # Submit job
+        result = client.predict(
+            image_paths,
+            api_name="/predict"
+        )
+        
+        # Unpack results
+        video_path, ply_url, _, _, glb_path, glb_url = result
+        
+        # Check if upload succeeded
+        if glb_url and not glb_url.startswith("Error"):
+            return {
+                "status": "success",
+                "glb_url": glb_url,
+                "ply_url": ply_url,
+                "video_available": video_path is not None,
+                "message": "Processing complete!"
+            }
+        else:
+            return {
+                "status": "error",
+                "error": glb_url or "Upload failed"
+            }
+            
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": str(e)
+        }
+
+
+def main():
+    """CLI interface."""
+    if len(sys.argv) < 3:
+        print("Usage: python api_client.py <image1> <image2> [image3 ...]")
+        print("\nExample:")
+        print("  python api_client.py img1.jpg img2.jpg img3.jpg")
+        print("\nEnvironment Variables:")
+        print("  INSTANTSPLAT_SPACE - HuggingFace Space URL (optional)")
+        print("                       e.g., your-username/InstantSplat")
+        sys.exit(1)
+    
+    # Get images from command line
+    image_paths = sys.argv[1:]
+    
+    # Get Space URL from environment or use local
+    space_url = os.environ.get("INSTANTSPLAT_SPACE")
+    
+    print("=" * 80)
+    print("InstantSplat API Client")
+    print("=" * 80)
+    
+    # Process images
+    result = process_images(image_paths, space_url)
+    
+    print("\n" + "=" * 80)
+    
+    # Display results
+    if result["status"] == "success":
+        print("✅ SUCCESS!")
+        print("-" * 80)
+        print(f"GLB URL: {result['glb_url']}")
+        print(f"PLY URL: {result['ply_url']}")
+        if result['video_available']:
+            print("Video: Available")
+        print("-" * 80)
+        print("\n💡 Tip: You can now download the GLB file:")
+        print(f"   curl -o model.glb '{result['glb_url']}'")
+        print("=" * 80)
+        return 0
+    else:
+        print("❌ ERROR!")
+        print("-" * 80)
+        print(f"Error: {result['error']}")
+        print("=" * 80)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

app.py

@@ -392,11 +392,33 @@ def process(inputfiles, input_path=None):
     #  3) ply file path (for gr.File download)
     #  4) ply file path (for gr.Model3D viewer)
     #  5) glb file path (for gr.Model3D viewer)
-    return output_video_path, ply_url, output_ply_path, output_ply_path, output_glb_path
+    #  6) glb URL (for API)
+    return output_video_path, ply_url, output_ply_path, output_ply_path, output_glb_path, glb_url
     ##################################################################################################################################################
 
 
 
+def process_api(inputfiles):
+    """
+    API-friendly wrapper that returns only the GLB URL.
+    
+    Args:
+        inputfiles: List of image files
+        
+    Returns:
+        dict with glb_url, ply_url, and video_url
+    """
+    result = process(inputfiles, input_path=None)
+    video_path, ply_url, _, _, glb_path, glb_url = result
+    
+    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"
+    }
+
+
 _TITLE = '''InstantSplat'''
 _DESCRIPTION = '''
 <div style="display: flex; justify-content: center; align-items: center;">
@@ -433,6 +455,68 @@ with block:
             inputfiles = gr.File(file_count="multiple", label="images")
             input_path = gr.Textbox(visible=False, label="example_path")
             button_gen = gr.Button("RUN")
+        
+        with gr.Tab("API"):
+            gr.Markdown("""
+            ## 🚀 API Access
+            
+            Submit images programmatically and get back the Supabase GLB URL.
+            
+            ### Quick Start (Python)
+            
+            ```bash
+            pip install gradio_client
+            ```
+            
+            ```python
+            from gradio_client import Client
+            
+            # Connect to this Space
+            client = Client("your-username/InstantSplat")
+            
+            # Submit images
+            result = client.predict(
+                ["image1.jpg", "image2.jpg", "image3.jpg"],
+                api_name="/predict"
+            )
+            
+            # Get GLB URL (it's the 6th element)
+            glb_url = result[5]
+            print(f"GLB URL: {glb_url}")
+            ```
+            
+            ### Response Format
+            
+            The API returns a tuple with 6 elements:
+            - `[0]` - Video path
+            - `[1]` - PLY URL (Supabase)
+            - `[2]` - PLY download path
+            - `[3]` - PLY model path
+            - `[4]` - GLB model path
+            - `[5]` - **GLB URL (Supabase)** ← This is what you want!
+            
+            ### CLI Tool
+            
+            Use the included `api_client.py`:
+            
+            ```bash
+            python api_client.py img1.jpg img2.jpg img3.jpg
+            ```
+            
+            ### Full Documentation
+            
+            See `API_GUIDE.md` for complete documentation including:
+            - JavaScript/TypeScript examples
+            - Error handling
+            - Batch processing
+            - Complete workflows
+            
+            ### Requirements
+            
+            - **Minimum**: 2 images (3+ recommended)
+            - **Same resolution**: All images must have matching dimensions
+            - **Formats**: JPG, PNG
+            """)
 
     with gr.Row(variant='panel'):
         with gr.Tab("Output"):
@@ -466,17 +550,24 @@ with block:
             with gr.Column(scale=1):
                 output_video = gr.Video(label="video")
                 
-    button_gen.click(process, inputs=[inputfiles], outputs=[output_video, output_file, output_download, output_model_ply, output_model_glb])
+    # Hidden output for GLB URL (for API access)
+    output_glb_url = gr.Textbox(visible=False, label="GLB URL")
+    
+    button_gen.click(
+        process, 
+        inputs=[inputfiles], 
+        outputs=[output_video, output_file, output_download, output_model_ply, output_model_glb, output_glb_url]
+    )
     
     gr.Examples(
         examples=[
             "sora-santorini-3-views",
         ],
         inputs=[input_path],
-        outputs=[output_video, output_file, output_download, output_model_ply, output_model_glb],
+        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,
         label='Sparse-view Examples'
     )
 
-block.launch(server_name="0.0.0.0", share=False)
+block.launch(server_name="0.0.0.0", share=False, show_api=True)

env.example

@@ -0,0 +1,15 @@
+# Supabase Storage Configuration
+# Copy this file to .env and fill in your values
+
+# Your Supabase project URL
+# Example: https://abcdefghijklmnop.supabase.co
+SUPABASE_URL=https://your-project-id.supabase.co
+
+# Your Supabase service role key (for server-side uploads)
+# Get this from: Supabase Dashboard > Settings > API > service_role key
+# WARNING: Keep this secret! Never commit this to version control.
+SUPABASE_KEY=your-service-role-key-here
+
+# Storage bucket name (optional, defaults to "outputs")
+SUPABASE_BUCKET=outputs
+

test_supabase_upload.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+Test script for Supabase Storage upload functionality.
+
+Usage:
+    python test_supabase_upload.py
+
+Make sure to set environment variables before running:
+    export SUPABASE_URL="https://your-project-id.supabase.co"
+    export SUPABASE_KEY="your-service-role-key"
+    export SUPABASE_BUCKET="outputs"  # optional
+"""
+
+import os
+import sys
+import tempfile
+import time
+
+
+def create_test_file(size_mb: int = 10) -> str:
+    """Create a temporary test file of specified size in MB."""
+    temp_file = tempfile.NamedTemporaryFile(delete=False, suffix='.bin')
+    
+    # Write random data
+    chunk_size = 1024 * 1024  # 1 MB
+    for _ in range(size_mb):
+        temp_file.write(os.urandom(chunk_size))
+    
+    temp_file.close()
+    print(f"Created test file: {temp_file.name} ({size_mb} MB)")
+    return temp_file.name
+
+
+def main():
+    # Import the upload function from app.py
+    try:
+        # Add parent directory to path
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        from app import upload_to_supabase_storage
+    except ImportError as e:
+        print(f"Error importing upload function: {e}")
+        print("Make sure app.py is in the same directory.")
+        return 1
+
+    # Check environment variables
+    supabase_url = os.environ.get("SUPABASE_URL")
+    supabase_key = os.environ.get("SUPABASE_KEY")
+    supabase_bucket = os.environ.get("SUPABASE_BUCKET", "outputs")
+
+    if not supabase_url:
+        print("ERROR: SUPABASE_URL environment variable not set")
+        print("Set it with: export SUPABASE_URL='https://your-project-id.supabase.co'")
+        return 1
+
+    if not supabase_key:
+        print("ERROR: SUPABASE_KEY environment variable not set")
+        print("Set it with: export SUPABASE_KEY='your-service-role-key'")
+        return 1
+
+    print("=" * 80)
+    print("Supabase Storage Upload Test")
+    print("=" * 80)
+    print(f"URL: {supabase_url}")
+    print(f"Bucket: {supabase_bucket}")
+    print(f"Key: {supabase_key[:20]}... (truncated)")
+    print("=" * 80)
+
+    # Test 1: Small file upload (1 MB)
+    print("\nTest 1: Small file upload (1 MB)")
+    print("-" * 80)
+    test_file_small = create_test_file(1)
+    
+    try:
+        start_time = time.time()
+        url = upload_to_supabase_storage(
+            file_path=test_file_small,
+            remote_path="test/small_file.bin",
+            supabase_url=supabase_url,
+            supabase_key=supabase_key,
+            bucket_name=supabase_bucket
+        )
+        elapsed = time.time() - start_time
+        
+        if url:
+            print(f"✅ SUCCESS: Uploaded in {elapsed:.2f} seconds")
+            print(f"URL: {url}")
+        else:
+            print("❌ FAILED: Upload returned None")
+    except Exception as e:
+        print(f"❌ ERROR: {e}")
+    finally:
+        os.unlink(test_file_small)
+
+    # Test 2: Medium file upload (50 MB)
+    print("\nTest 2: Medium file upload (50 MB)")
+    print("-" * 80)
+    test_file_medium = create_test_file(50)
+    
+    try:
+        start_time = time.time()
+        url = upload_to_supabase_storage(
+            file_path=test_file_medium,
+            remote_path="test/medium_file.bin",
+            supabase_url=supabase_url,
+            supabase_key=supabase_key,
+            bucket_name=supabase_bucket
+        )
+        elapsed = time.time() - start_time
+        
+        if url:
+            print(f"✅ SUCCESS: Uploaded in {elapsed:.2f} seconds")
+            print(f"URL: {url}")
+        else:
+            print("❌ FAILED: Upload returned None")
+    except Exception as e:
+        print(f"❌ ERROR: {e}")
+    finally:
+        os.unlink(test_file_medium)
+
+    # Test 3: Large file upload (200 MB) - optional
+    print("\nTest 3: Large file upload (200 MB) - Optional")
+    print("-" * 80)
+    response = input("Run large file test? This will create and upload a 200MB file (y/N): ")
+    
+    if response.lower() == 'y':
+        test_file_large = create_test_file(200)
+        
+        try:
+            start_time = time.time()
+            url = upload_to_supabase_storage(
+                file_path=test_file_large,
+                remote_path="test/large_file.bin",
+                supabase_url=supabase_url,
+                supabase_key=supabase_key,
+                bucket_name=supabase_bucket
+            )
+            elapsed = time.time() - start_time
+            
+            if url:
+                print(f"✅ SUCCESS: Uploaded in {elapsed:.2f} seconds")
+                print(f"Upload speed: {200 / elapsed:.2f} MB/s")
+                print(f"URL: {url}")
+            else:
+                print("❌ FAILED: Upload returned None")
+        except Exception as e:
+            print(f"❌ ERROR: {e}")
+        finally:
+            os.unlink(test_file_large)
+    else:
+        print("Skipped large file test")
+
+    print("\n" + "=" * 80)
+    print("Testing complete!")
+    print("=" * 80)
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+