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

npm install

---

🚀 API Client (Recommended)

Get Supabase URLs for your GLB/PLY files.

Quick Start

# 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

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)

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

npm run call <image1> <image2> [image3] ...

Example:

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:

npx tsx call_instantsplat.ts image1.jpg image2.jpg image3.jpg

Using as a Module

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:

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