sideload-avatar-generator

# Sideload Avatar Generator

Generate 3D avatars from text prompts or reference images using [Sideload.gg](https://sideload.gg). Pay-per-use via the [x402 protocol](https://x402.org) — $2 USDC per generation on Base.

**Works with any x402 wallet.** Bring your own wallet and private key — no proprietary wallet required.

## What You Get

Each generation produces four formats:

| Format | File | Use Case |
|--------|------|----------|
| **GLB** | `.glb` | Universal 3D — Three.js, Unity, Unreal, web viewers |
| **VRM** | `.vrm` | Avatar standard — VRChat, VTubing, social apps |
| **MML** | URL | Metaverse Markup Language — for [MML-compatible](https://mml.io) worlds |
| **PNG** | `.png` | Processed reference image used for generation |

## 🎭 Rendering Avatars with @pixiv/three-vrm

The VRM output is designed to work with [@pixiv/three-vrm](https://github.com/pixiv/three-vrm) — the standard Three.js library for loading, displaying, and animating VRM avatars. If you're already building with Three.js, generated avatars plug right in with full skeleton support:

```javascript
import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
import { VRMLoaderPlugin } from '@pixiv/three-vrm';

const loader = new GLTFLoader();
loader.register((parser) => new VRMLoaderPlugin(parser));

loader.load('https://aiml.sideload.gg/models/avt-xxx.vrm', (gltf) => {
  const vrm = gltf.userData.vrm;
  scene.add(vrm.scene);

  // Animate bone transforms, look-at, etc.
});
```

This makes it easy to generate an avatar with Sideload and immediately use it in any Three.js scene — games, social apps, virtual worlds, VTubing, and more.

For more on building interactive 3D experiences in the metaverse, see [awesome-mml](https://github.com/DirectiveCreator/awesome-mml) — a curated list of MML (Metaverse Markup Language) resources.

## Prerequisites

- **Node.js 18+**
- **An x402 payment token** — sign a payment with your own wallet/signer and pass it via `--x4...

# 🎭 Sideload Avatar Generator

Generate 3D avatars from text prompts or reference images using [Sideload.gg](https://sideload.gg).

**$2 per avatar. Pay-per-use. No API key. No subscription.**

Payment is handled via the [x402 protocol](https://x402.org) — an open standard by Coinbase for HTTP-native payments using USDC on Base. Works with any x402-compatible wallet.

## Output Formats

Every generation produces:
- **GLB** — Universal 3D model (Three.js, Unity, Unreal, web)
- **VRM** — Avatar standard (VRChat, VTubing, [@pixiv/three-vrm](https://github.com/pixiv/three-vrm))
- **MML** — [Metaverse Markup Language](https://mml.io) document for virtual worlds
- **PNG** — Processed reference image

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/DirectiveCreator/sideload-avatar-generator.git
cd sideload-avatar-generator
npm install

# 2. Check the cost
node scripts/generate.js --probe

# 3. Sign an x402 payment with your wallet, then generate!
node scripts/generate.js --prompt "A cyberpunk samurai with glowing red armor" --x402-token <token>
```

## Usage

### From text
```bash
node scripts/generate.js --prompt "An anime sorceress with silver hair and a golden staff" --x402-token <token>
```

### From image
```bash
node scripts/generate.js --image https://example.com/character.png --x402-token <token>
node scripts/generate.js --image ./my-photo.jpg --x402-token <token>
```

### Check cost
```bash
node scripts/generate.js --probe
```

### Check a job
```bash
node scripts/status.js avt-a1b2c3d4
```

### Options

| Flag | Description |
|------|-------------|
| `--prompt "text"` | Text description of the avatar |
| `--image <url-or-path>` | Reference image (URL or local file) |
| `--output <name>` | Custom filename for downloads |
| `--no-download` | Skip downloading result files |
| `--x402-token <token>` | x402 payment token (required for generation) |
| `--probe` | Check cost without generating |

## Rendering with Three.js

Generated VRM ava...