API_TYPESCRIPT.md

# InstantSplat TypeScript API Client

Complete TypeScript/JavaScript client for InstantSplat API with full type safety.

## 🚀 Quick Start

### Installation

```bash
npm install @gradio/client @types/node ts-node tsx
```

### Basic 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);
}
```

## 📦 Available Functions

### `processImages(imagePaths, spaceUrl?)`

Submit images and get back URLs.

```typescript
async function processImages(
  imagePaths: string[],
  spaceUrl?: string
): Promise<ProcessResult>
```

**Parameters:**
- `imagePaths`: Array of local image file paths
- `spaceUrl`: (Optional) HuggingFace Space URL or env var `INSTANTSPLAT_SPACE`

**Returns:**
```typescript
interface ProcessResult {
  status: "success" | "error";
  glb_url?: string;
  ply_url?: string;
  video_available?: boolean;
  error?: string;
  message?: string;
}
```

**Example:**
```typescript
const result = await processImages(
  ["img1.jpg", "img2.jpg", "img3.jpg"],
  "username/InstantSplat"
);

console.log(result.glb_url); // Supabase URL to GLB file
```

### `completeWorkflow(imagePaths, outputDir, spaceUrl?)`

Process images and download the GLB file.

```typescript
async function completeWorkflow(
  imagePaths: string[],
  outputDir?: string,
  spaceUrl?: string
): Promise<string | null>
```

**Parameters:**
- `imagePaths`: Array of image paths
- `outputDir`: Local directory for downloaded file (default: `./outputs`)
- `spaceUrl`: (Optional) Space URL

**Returns:** Local path to downloaded GLB file, or `null` on error

**Example:**
```typescript
const localPath = await completeWorkflow(
  ["img1.jpg", "img2.jpg", "img3.jpg"],
  "./my_models"
);

console.log("Model saved to:", localPath);
// Output: Model saved to: ./my_models/model.glb
```

### `downloadFile(url, outputPath)`

Download a file from URL.

```typescript
async function downloadFile(
  url: string,
  outputPath: string
): Promise<void>
```

## 🛠️ CLI Usage

### Using npx

```bash
npx tsx api_client.ts img1.jpg img2.jpg img3.jpg
```

### Using npm script

```bash
npm run api img1.jpg img2.jpg img3.jpg
```

### With environment variable

```bash
export INSTANTSPLAT_SPACE="username/InstantSplat"
npx tsx api_client.ts img1.jpg img2.jpg img3.jpg
```

## 📝 Examples

### Example 1: Simple Usage

```typescript
import { processImages } from "./api_client";

async function main() {
  const result = await processImages(
    ["image1.jpg", "image2.jpg", "image3.jpg"],
    "username/InstantSplat"
  );

  if (result.status === "success") {
    console.log("✅ GLB URL:", result.glb_url);
    console.log("✅ PLY URL:", result.ply_url);
  } else {
    console.error("❌ Error:", result.error);
  }
}

main();
```

### Example 2: With Error Handling

```typescript
import { processImages } from "./api_client";

async function processWithRetry(
  images: string[],
  maxRetries = 3
): Promise<ProcessResult> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await processImages(images);

    if (result.status === "success") {
      return result;
    }

    if (attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw new Error("All retries failed");
}
```

### Example 3: Batch Processing

```typescript
import { processImages } from "./api_client";

async function batchProcess(imageSets: string[][]) {
  const results = [];

  for (let i = 0; i < imageSets.length; i++) {
    console.log(`Processing set ${i + 1}/${imageSets.length}...`);
    
    const result = await processImages(imageSets[i]);
    results.push(result);

    // Rate limiting
    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  return results;
}

const sets = [
  ["scene1_img1.jpg", "scene1_img2.jpg"],
  ["scene2_img1.jpg", "scene2_img2.jpg"],
];

const results = await batchProcess(sets);
```

### Example 4: Download and Use

```typescript
import { completeWorkflow } from "./api_client";

async function processAndDownload() {
  const modelPath = await completeWorkflow(
    ["img1.jpg", "img2.jpg", "img3.jpg"],
    "./models"
  );

  if (modelPath) {
    console.log(`Model ready at: ${modelPath}`);
    // Use the model file...
  }
}
```

## 🌐 Integration Examples

### Express.js API

```typescript
import express from "express";
import { processImages } from "./api_client";

const app = express();
app.use(express.json());

app.post("/api/process", async (req, res) => {
  const { images } = req.body;

  const result = await processImages(
    images,
    process.env.INSTANTSPLAT_SPACE
  );

  if (result.status === "success") {
    res.json({
      success: true,
      glb_url: result.glb_url,
      ply_url: result.ply_url
    });
  } else {
    res.status(500).json({
      success: false,
      error: result.error
    });
  }
});

app.listen(3000);
```

### Next.js API Route

```typescript
// pages/api/process.ts
import type { NextApiRequest, NextApiResponse } from "next";
import { processImages } from "../../api_client";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  const { images } = req.body;

  const result = await processImages(
    images,
    process.env.INSTANTSPLAT_SPACE
  );

  if (result.status === "success") {
    res.status(200).json(result);
  } else {
    res.status(500).json(result);
  }
}
```

### React Hook

```typescript
import { useState } from "react";
import { processImages } from "./api_client";

function useInstantSplat() {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<ProcessResult | null>(null);

  const process = async (images: string[]) => {
    setLoading(true);
    try {
      const res = await processImages(images);
      setResult(res);
      return res;
    } finally {
      setLoading(false);
    }
  };

  return { process, loading, result };
}

// Usage in component:
function MyComponent() {
  const { process, loading, result } = useInstantSplat();

  const handleSubmit = () => {
    process(["img1.jpg", "img2.jpg", "img3.jpg"]);
  };

  return (
    <div>
      {loading && <p>Processing...</p>}
      {result?.glb_url && <a href={result.glb_url}>Download Model</a>}
    </div>
  );
}
```

### Vue.js Composable

```typescript
import { ref } from "vue";
import { processImages } from "./api_client";

export function useInstantSplat() {
  const loading = ref(false);
  const result = ref(null);

  const process = async (images: string[]) => {
    loading.value = true;
    try {
      result.value = await processImages(images);
    } finally {
      loading.value = false;
    }
  };

  return { process, loading, result };
}
```

## 📚 Type Definitions

```typescript
interface ProcessResult {
  status: "success" | "error";
  glb_url?: string;           // Supabase URL to GLB file
  ply_url?: string;           // Supabase URL to PLY file
  video_available?: boolean;  // Whether video was generated
  error?: string;             // Error message if status is "error"
  message?: string;           // Success message
}

interface InstantSplatResponse {
  video_path: string;    // [0] Path to video
  ply_url: string;       // [1] PLY URL
  ply_download: string;  // [2] PLY download
  ply_model: string;     // [3] PLY model
  glb_model: string;     // [4] GLB model path
  glb_url: string;       // [5] GLB URL (Supabase)
}
```

## ⚙️ Configuration

### Environment Variables

```bash
# .env
INSTANTSPLAT_SPACE=username/InstantSplat
```

### package.json Scripts

Add to your `package.json`:

```json
{
  "scripts": {
    "api": "npx tsx api_client.ts",
    "process": "npx tsx example_api_usage.ts"
  }
}
```

## 🔧 Troubleshooting

### "Cannot find module '@gradio/client'"

```bash
npm install @gradio/client
```

### "Cannot find name 'require'"

Add to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}
```

### TypeScript errors

Make sure you have the types installed:

```bash
npm install --save-dev @types/node
```

### Import errors

If using ES modules, change imports:

```typescript
// CommonJS
const { processImages } = require("./api_client");

// ES Modules
import { processImages } from "./api_client.js";
```

## 📦 Building for Production

### Compile TypeScript

```bash
npx tsc api_client.ts
```

### Bundle with esbuild

```bash
npx esbuild api_client.ts --bundle --platform=node --outfile=dist/api_client.js
```

### Use in production

```typescript
// Import the compiled version
import { processImages } from "./dist/api_client.js";
```

## 🎯 Best Practices

1. **Rate Limiting**: Add delays between batch requests
2. **Error Handling**: Always wrap in try-catch
3. **Retries**: Implement exponential backoff
4. **Timeouts**: Set reasonable timeouts for large images
5. **Validation**: Check image files exist before uploading

## 📖 More Examples

See `example_api_usage.ts` for complete working examples including:
- Simple usage
- Complete workflow with download
- Batch processing
- Error handling with retries
- Express.js integration
- React component integration

## 🆘 Support

- Check `API_GUIDE.md` for general API documentation
- Check `API_QUICKSTART.md` for quick start guide
- Review `example_api_usage.ts` for working examples

## 🔗 Related Files

- `api_client.ts` - Main TypeScript client
- `api_client.py` - Python equivalent
- `example_api_usage.ts` - Usage examples
- `API_GUIDE.md` - Complete API documentation
- `API_QUICKSTART.md` - Quick start guide