npm package: @stablestudio/sdk
Description: TypeScript SDK for StableStudio AI API with x402 payments
Author: StableStudio
Latest version: 0.2.1
Deprecated: Use x402scan-mcp instead

# StableStudio SDK

TypeScript SDK for StableStudio AI API with x402 micropayments.

## Features

- 🔐 Automatic x402 payment signing
- 🎨 Type-safe `Job<ImageResult>` and `Job<VideoResult>`
- ⚡ Automatic polling with `await job.poll()`
- 💰 Model-specific cost estimation
- 📤 File uploads with x402 payments ($0.01/upload)
- 💾 Download helpers
- 🔄 Job listing with SIWE authentication

## Installation

```bash
pnpm add @stablestudio/sdk viem
```

## Quick Start

```typescript
import { StableStudioClient } from '@stablestudio/sdk';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

// Create wallet
const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY),
  chain: base,
  transport: http(),
});

// Initialize SDK
const studio = new StableStudioClient({
  wallet,
  network: 'base', // or 'base-sepolia' for testing
});

// Generate image
const imageJob = await studio.images.nanoBanana.generate({
  prompt: 'A robot in a neon city',
  aspectRatio: '16:9',
});

const { result } = await imageJob.poll();
console.log(result.imageUrl); // TypeScript knows this is ImageResult!

// Generate video with progress
const videoJob = await studio.videos.wan25.textToVideo({
  prompt: 'Ocean waves',
  duration: '5',
  size: '1280*720',
});

const { result: video } = await videoJob.poll({
  onProgress: (p) => console.log(`${p}%`),
});

console.log(video.videoUrl);
```

## API Reference

### Images

**Nano Banana (Gemini 2.5 Flash)** - $0.039/image
```typescript
studio.images.nanoBanana.generate({ prompt, aspectRatio })
studio.images.nanoBanana.edit({ prompt, images, aspectRatio })
studio.images.nanoBanana.estimate({ prompt, aspectRatio })
```

**Nano Banana Pro (Gemini 3 Pro)** - $0.134-$0.24/image
```typescript
studio.images.nanoBananaPro.generate({ prompt, imageSize, aspectRatio })
studio.images.nanoBananaPro.edit({ prompt, images, imageSize })
studio.images.nanoBananaPro.estimate({ prompt, imageSize })
```

**GPT-1 (GPT-4)** - $0.01-$0.17/image
```typescript
studio.images.gpt1.generate({ prompt, quality, size })
studio.images.gpt1.edit({ prompt, images, quality })
studio.images.gpt1.estimate({ prompt, quality })
```

### Videos

**Wan 2.5** - $0.068-$0.102/sec (most cost-effective)
```typescript
studio.videos.wan25.textToVideo({ prompt, duration, size })
studio.videos.wan25.imageToVideo({ image, prompt, duration, resolution })
studio.videos.wan25.estimateT2V({ prompt, duration })
studio.videos.wan25.estimateI2V({ image, prompt, duration })
```

**Sora (OpenAI)** - $0.10-$0.50/sec
```typescript
// Text-to-video
studio.videos.sora.generate({ prompt, seconds, size })

// Image-to-video (optional)
studio.videos.sora.generate({ prompt, seconds, size, input_reference })

studio.videos.sora.estimate({ prompt, seconds })
```

**Veo (Google)** - $0.40/sec
```typescript
// Text-to-video
studio.videos.veo.generate({ prompt, durationSeconds, resolution })

// Image-to-video (optional image, lastFrame, referenceImages)
studio.videos.veo.generate({ prompt, durationSeconds, image, imageMode: 'first-frame' })

studio.videos.veo.estimate({ prompt, durationSeconds })
```

### Uploads

**Upload Images** - $0.01/upload (up to 10MB)
```typescript
// Upload a local image file
const upload = await studio.uploads.uploadFile('./photo.jpg');
console.log(upload.url); // Use in image editing operations

// Use uploaded image in editing
const editJob = await studio.images.nanoBanana.edit({
  prompt: 'Make it blue',
  images: [upload.url],
  aspectRatio: '16:9',
});
```

**Supported formats:** JPEG, PNG, GIF, WebP

### Jobs (Queries - No Payment)

```typescript
// Get job status
const job = await studio.jobs.getStatus('job-id');

// List jobs with pagination
const { items, nextCursor } = await studio.jobs.list({
  status: 'complete',
  limit: 50,
});
```

### Utilities

```typescript
// Check USDC balance
const balance = await studio.getBalance(); // Returns number (e.g., 2.50 for $2.50)

// Download generated files
import { downloadFile } from '@stablestudio/sdk';
await downloadFile(result.imageUrl, './image.png');
```

## Job Class

All generation methods return `Job<TResult>` with automatic polling:

```typescript
const job = await studio.images.nanoBanana.generate({ prompt: 'A sunset' });

// Poll until complete (automatic)
const { result } = await job.poll();
console.log(result.imageUrl);

// Job properties
job.id          // Job ID
job.status      // 'pending' | 'loading' | 'complete' | 'failed'
job.progress    // 0-100
job.cost        // Cost in USD
job.txHash      // Payment transaction
job.result      // Typed result (ImageResult or VideoResult)
```

## Error Handling

```typescript
import { PaymentError, JobError } from '@stablestudio/sdk';

try {
  const job = await studio.images.nanoBanana.generate({ prompt: 'Test' });
  const { result } = await job.poll();
} catch (error) {
  if (error instanceof PaymentError) {
    console.error('Payment failed:', error.message);
  } else if (error instanceof JobError) {
    console.error('Job failed:', error.message);
  }
}
```

## Configuration

```typescript
new StableStudioClient({
  wallet,                    // Required: viem WalletClient
  apiUrl?: string,          // Default: 'https://stablestudio.io'
  network?: NetworkName,    // Default: 'base-sepolia'
  payTo?: `0x${string}`,    // Default: StableStudio wallet
  timeout?: number,         // Default: 20 minutes
});
```

## Network Support

**Base Mainnet:** Chain 8453, USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
**Base Sepolia:** Chain 84532, USDC `0x036CbD53842c5426634e7929541eC2318f3dCF7e`

## License

MIT