API_QUICKSTART.md

# 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! 🚀