README_TS.md

# 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