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

pip install gradio_client

Step 2: Run This Code

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:

[
    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

#!/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:

# 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

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