# Weyl - Complete Documentation

> Weyl is purpose-built inference infrastructure for generative media. Sub-100ms latency for diffusion models on NVIDIA Blackwell with FP4 precision.

Weyl AI is a Fleek research lab building next-generation AI infrastructure. We specialize in low-latency generative media APIs, Nix-based GPU compute infrastructure, and developer tooling for AI-native workflows.

---

## Table of Contents

1. [About Weyl](#about-weyl)
2. [API Documentation](#api-documentation)
3. [AI Workflows](#ai-workflows)
4. [Weyl Standard](#weyl-standard)
5. [Blog Posts](#blog-posts)
6. [Open Source](#open-source)
7. [Research Papers](#research-papers)

---

## About Weyl

Weyl provides:

- **Sub-100ms Latency**: Optimized CUDA kernels on NVIDIA Blackwell architecture
- **FP4 Quantization**: 4x throughput improvement with maintained quality
- **Dual Tiers**: Sync for real-time applications, Async for cost optimization
- **Advanced Models**: FLUX.2, FLUX.1, Z-Image Turbo, WAN 2.2 Video

### Key Capabilities

| Feature | Description |
|---------|-------------|
| Image Generation | FLUX.2 Kontext, FLUX.1 dev/schnell, Z-Image Turbo |
| Video Generation | WAN 2.2 video synthesis |
| Real-time API | WebSocket and REST endpoints |
| AI Workflow Integration | Cursor, Claude, v0, Lovable, Bolt.new |

---

## API Documentation

### API Reference

#### API Overview

**URL**: https://weyl.ai/api/
**Description**: Weyl Render API - Generative media at the speed of thought

> // the street finds its own uses for things

Generative media at the speed of thought. Images and video from the edge, served hot off Blackwell tensor cores.

## Quick Example

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"cyberpunk street at night, neon rain"}' \
  -o output.webp
```

You POST. You get bytes. The `Content-Location` header points to the CDN.

## Service Tiers

### sync.render.weyl.ai

**Dedicated bare metal, SLA-backed.**

- POST, receive bytes immediately
- No queue, no polling
- 503 if capacity exhausted
- WebSocket available for streaming frames

**Use when:** Real-time preview, interactive tools, live generation

### async.render.weyl.ai

**Queue-backed, CDN-arbitraged pricing.**

- POST returns 202 with job ID
- Poll, SSE, or WebSocket for progress
- Equal quality, lower cost, higher latency

**Use when:** Batch workflows, cost optimization, non-critical timing

### cdn.render.weyl.ai

**Immutable asset delivery.**

- Every generated asset gets a permanent URL
- Cache-forever semantics
- Global CDN distribution

## Next Steps

- [Authentication](/api/authentication/) - Set up your API keys
- [Sync Tier](/api/sync/) - Real-time generation
- [Async Tier](/api/async/) - Queue-based workflows

---

#### Detail Enhancement

**URL**: https://weyl.ai/api/advanced/detail/
**Description**: Upscaling and detail recovery

Upscale and enhance generated images post-processing.

## Basic Upscaling

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "portrait",
    "upscale": 2
  }' \
  -o output.webp
```

**Scales:** 1.5×, 2×, 4×

## Latent Upscaling

Generate at higher resolution by upscaling latents before final decode.

```
{
  "prompt": "detailed landscape",
  "format": "1024",
  "latent_upscale": 1.5
}
```

**Output:** 1536×1536 (1024 × 1.5)

## Detail Recovery

Add fine details after generation:

```
{
  "prompt": "portrait",
  "detail_enhance": true,
  "detail_strength": 0.5
}
```

**Strength range:** 0.0 - 1.0
- `0.3` - Subtle sharpening
- `0.5` - Balanced (default)
- `0.8` - Strong detail

## Performance Impact

| Operation        | Latency Increase |
|------------------|------------------|
| 1.5× upscale     | +20%             |
| 2× upscale       | +40%             |
| 4× upscale       | +150%            |
| Detail enhance   | +15%             |

---

#### Guidance Tuning

**URL**: https://weyl.ai/api/advanced/guidance/
**Description**: CFG scale optimization

Control prompt adherence with classifier-free guidance (CFG).

## Understanding Guidance

**Low guidance (1.0-2.0):** Loose interpretation, more creative  
**Medium guidance (2.5-4.0):** Balanced  
**High guidance (4.5-10.0):** Strict adherence, can over-saturate

## FLUX Family

### FLUX Dev2
**Range:** 1.0 - 5.0  
**Sweet spots:**
- Short prompts: `3.5` - strong adherence
- Medium prompts: `2.5` - balanced
- Detailed prompts: `1.5` - let model breathe
- Very detailed: `1.0` - maximum freedom

```
# Detailed prompt with low guidance
curl -X POST "..." \
  -d '{
    "prompt": "portrait, 35mm, natural light, golden hour, ...",
    "guidance": 1.5
  }'
```

### FLUX Dev
**Range:** 2.0 - 5.0  
**Default:** `3.5`  
**Recommendation:** Stay at 3.5 for consistency

### FLUX Schnell
**Fixed:** `3.5`  
Cannot be changed (distilled for this value).

## Z-Image

**Fixed:** `1.0` (internally)  
The `guidance` parameter is ignored. Z-Image uses fixed CFG.

## WAN Video

**Range:** 6.0 - 8.0  
**Default:** `7.0`  
**Recommendation:**
- Subtle motion: `6.0`
- Normal: `7.0`
- Strong motion: `8.0`

---

#### LoRA Adapters

**URL**: https://weyl.ai/api/advanced/loras/
**Description**: Fine-tuned model adapters

Load Low-Rank Adaptation (LoRA) weights to customize model behavior.

## Basic Usage

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a portrait in the style of artgerm",
    "loras": [
      {
        "url": "https://example.com/artgerm_lora.safetensors",
        "weight": 0.8
      }
    ]
  }' \
  -o output.webp
```

## Multiple LoRAs

Stack multiple adapters:

```
{
  "prompt": "cyberpunk portrait",
  "loras": [
    {
      "url": "https://cdn.render.weyl.ai/loras/cyberpunk.safetensors",
      "weight": 0.7
    },
    {
      "url": "https://cdn.render.weyl.ai/loras/cinematic.safetensors",
      "weight": 0.5
    }
  ]
}
```

## Weight Tuning

**Range:** 0.0 - 1.5

- `0.3-0.5` - Subtle influence
- `0.6-0.9` - Moderate influence (recommended)
- `1.0-1.2` - Strong influence
- `1.3+` - Maximum (may overfit)

## Compatibility

**Supported:**
- FLUX Dev ✓
- FLUX Dev2 ✓ (FLUX.1 LoRAs work)

**Not Supported:**
- FLUX Schnell (distilled)
- Z-Image (different architecture)

## LoRA Sources

- Hugging Face Hub
- CivitAI
- Custom trained

---

#### Samplers

**URL**: https://weyl.ai/api/advanced/samplers/
**Description**: Available sampling methods

Control the generation sampling algorithm.

## Available Samplers

| Sampler     | Family        | Speed    | Quality  | Notes                 |
|-------------|---------------|----------|----------|-----------------------|
| `euler`     | FLUX, Z-Image | Fast     | Good     | Default for most      |
| `euler_a`   | FLUX          | Fast     | Good     | Ancestral (random)    |
| `dpmpp_2m`  | FLUX          | Medium   | Better   | 2M solver             |
| `heun`      | FLUX          | Slow     | Best     | High quality          |

## Usage

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "portrait",
    "sampler": "dpmpp_2m",
    "steps": 25
  }' \
  -o output.webp
```

## Recommendations

### FLUX Schnell
**Use:** `euler` (only)  
**Steps:** 4 (fixed)  
Schnell is distilled for euler at 4 steps. Other samplers won't work.

### FLUX Dev / Dev2
**Fast:** `euler` - 20-25 steps  
**Quality:** `dpmpp_2m` - 25-30 steps  
**Best:** `heun` - 30-40 steps

### Z-Image
**Use:** `euler` (only)  
Z-Image uses custom scheduling. Other samplers ignored.

---

#### Schedulers

**URL**: https://weyl.ai/api/advanced/schedulers/
**Description**: Noise scheduling strategies

Control how noise is scheduled during denoising.

## Available Schedulers

| Scheduler  | Family | Characteristics           |
|------------|--------|---------------------------|
| `simple`   | FLUX   | Default, fast, consistent |
| `normal`   | FLUX   | Beta schedule variant     |
| `sgm`      | FLUX   | Stable diffusion style    |

## Usage

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "portrait",
    "scheduler": "simple",
    "steps": 25
  }' \
  -o output.webp
```

## Scheduler Guide

### `simple` (Default)
**Best for:** Most use cases  
**Characteristics:**
- Linear noise schedule
- Predictable behavior
- Fast convergence

**Recommended steps:** 20-30

### `normal`
**Best for:** Alternative beta scheduling  
**Characteristics:**
- Beta-based schedule
- Slightly different aesthetic

**Recommended steps:** 25-35

### `sgm`
**Best for:** Stable Diffusion compatibility  
**Characteristics:**
- Matches SD-style scheduling
- Useful for LoRA trained on SD

**Recommended steps:** 30-40

## Model Defaults

- **FLUX Dev2/Dev:** `simple`
- **FLUX Schnell:** `simple` (fixed)
- **Z-Image:** Custom (not configurable)

---

#### Async Tier Overview

**URL**: https://weyl.ai/api/async/
**Description**: Queue-based generation

**Base URL:** `https://async.render.weyl.ai`

Queue-backed generation with CDN-arbitraged pricing.

## How It Works

```
1. POST /queue → 202 Accepted + job ID
2. Poll /jobs/{id} OR subscribe to SSE
3. GET /jobs/{id} → 303 redirect to CDN when complete
```

## Submit Job

```
curl -X POST "https://async.render.weyl.ai/queue" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "image",
    "family": "flux",
    "model": "schnell",
    "task": "t2i",
    "format": "1024",
    "prompt": "cyberpunk cityscape"
  }'
```

## Check Status

```
curl "https://async.render.weyl.ai/jobs/j_abc123" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

When complete, returns 303 redirect to the CDN URL.

---

#### Job Management

**URL**: https://weyl.ai/api/async/jobs/
**Description**: Check status and retrieve outputs

Manage async jobs: check status, cancel, retrieve outputs.

## Get Job Status

**Endpoint:** `GET /jobs/{id}`

```
curl "https://async.render.weyl.ai/jobs/j_abc123" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

### States

**Queued:**
```
{
  "id": "j_abc123",
  "status": "queued",
  "position": 3,
  "eta_seconds": 45
}
```

**Running:**
```
{
  "id": "j_abc123",
  "status": "running",
  "progress": 0.65,
  "eta_seconds": 8
}
```

**Complete (303 Redirect):**
```
HTTP/1.1 303 See Other
Location: https://cdn.render.weyl.ai/i/abc123.webp
```

## Cancel Job

**Endpoint:** `DELETE /jobs/{id}`

```
curl -X DELETE "https://async.render.weyl.ai/jobs/j_abc123" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

---

#### Queue Submission

**URL**: https://weyl.ai/api/async/queue/
**Description**: Submit jobs to the async queue

**Endpoint:** `POST /queue`

Submit generation jobs to the async queue.

## Request Format

```
curl -X POST "https://async.render.weyl.ai/queue" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "image",
    "family": "flux",
    "model": "schnell",
    "task": "t2i",
    "format": "1024",
    "prompt": "portrait in natural lighting"
  }'
```

## Response (202)

```
{
  "id": "j_abc123",
  "status": "queued",
  "position": 5,
  "eta_seconds": 75
}
```

## Queue Options

### Priority

```
{
  "priority": "normal",  // low, normal, high
  "prompt": "..."
}
```

### Webhook

```
{
  "webhook": "https://myapp.com/callback",
  "prompt": "..."
}
```

### Idempotency

```
{
  "idempotency_key": "unique_key_123",
  "prompt": "..."
}
```

---

#### Server-Sent Events (SSE)

**URL**: https://weyl.ai/api/async/sse/
**Description**: Real-time job progress via SSE streaming

**Endpoint:** `GET /jobs/{id}/events`

Subscribe to job progress via Server-Sent Events.

## Basic Usage

```
curl -N "https://async.render.weyl.ai/jobs/j_abc123/events" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

## Event Stream

```
event: position
data: {"position": 3, "eta_seconds": 45}

event: started
data: {}

event: progress
data: {"progress": 0.65, "step": 20}

event: complete
data: {"output": "https://cdn.render.weyl.ai/i/xyz.webp"}
```

## Python Client

```

def stream_job_events(job_id: str):
    url = f"https://async.render.weyl.ai/jobs/{job_id}/events"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    
    with requests.get(url, headers=headers, stream=True) as resp:
        for line in resp.iter_lines(decode_unicode=True):
            if line.startswith('data:'):
                data = json.loads(line[6:])
                print(data)
```

---

#### Authentication

**URL**: https://weyl.ai/api/authentication/
**Description**: API key management and security

All API requests require authentication using Bearer tokens.

## Getting API Keys

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a>
2. Fill out the access request form with your project details
3. Receive your API key via email within 24 hours
4. Store securely (keep the email safe for future reference)

## Using API Keys

Include your key in the `Authorization` header:

```
Authorization: Bearer wyl_sk_1234567890abcdef
```

## Security Best Practices

### Environment Variables

**Never hardcode API keys.** Use environment variables:

```
# .env.local
WEYL_API_KEY=wyl_sk_prod_1234567890abcdef
```

## Rate Limits

Rate limits are enforced per API key. Check response headers for current limits.

---

#### Core Concepts

**URL**: https://weyl.ai/api/concepts/
**Description**: Understanding Weyl API fundamentals

## Model Families

Each family is a distinct transformer backbone with its own characteristics.

| Family   | Modality | Default Backend | Status       |
|----------|----------|-----------------|--------------|
| `flux`   | image    | nunchaku        | **active**   |
| `zimage` | image    | nunchaku        | **active**   |
| `wan`    | video    | torch           | coming soon  |

## Backends

Three inference backends, each with different tradeoffs:

| Backend    | Stack                | Notes                        |
|------------|----------------------|------------------------------|
| `nunchaku` | NVFP4 on Blackwell   | Fastest, 4-bit quantized     |
| `torch`    | diffusers + CUDA     | Flexible, full precision     |
| `tensorrt` | TRT-LLM + ModelOpt   | NVIDIA-optimized, production |

## Formats

### Image Formats

| Format           | Dimensions | Aspect |
|------------------|------------|--------|
| `1024`           | 1024×1024  | 1:1    |
| `512`            | 512×512    | 1:1    |
| `portrait`       | 768×1024   | 3:4    |
| `landscape`      | 1024×768   | 4:3    |

### Video Formats

| Format          | Dimensions | Aspect |
|-----------------|------------|--------|
| `720p`          | 1280×720   | 16:9   |
| `480p`          | 832×480    | ~16:9  |
| `square`        | 640×640    | 1:1    |

## Tasks

| Task   | Requires            | Produces | Description                |
|--------|---------------------|----------|----------------------------|
| `t2v`  | prompt              | video    | text to video              |
| `i2v`  | prompt + image      | video    | animate a still            |
| `t2i`  | prompt              | image    | text to image              |
| `i2i`  | prompt + image      | image    | transform / style transfer |
| `edit` | prompt + image + mask | image  | inpaint / outpaint         |

---

#### Model Aliases

**URL**: https://weyl.ai/api/infrastructure/aliases/
**Description**: Stable model references

Use stable aliases instead of version-specific model names.

## Why Aliases?

Model names like `dev2`, `dev`, `schnell` are version-specific. Aliases provide stable references that automatically point to recommended versions.

## Available Aliases

| Alias       | Current Target | Description              |
|-------------|----------------|--------------------------|
| `latest`    | `dev2`         | Newest FLUX model        |
| `default`   | `dev`          | Balanced quality/speed   |
| `fast`      | `schnell`      | Fastest generation       |
| `turbo`     | `turbo`        | Z-Image fast model       |

## Usage

### Using Alias

```
curl -X POST "https://sync.render.weyl.ai/image/flux/latest/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -d '{"prompt": "portrait"}'
```

### Using Specific Version

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev2/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -d '{"prompt": "portrait"}'
```

## When to Use

### Use Aliases When:
- Building for long-term stability
- Want automatic upgrades to better models
- Prototyping / experimentation

### Use Specific Versions When:
- Need reproducible results
- Production systems with change control
- Benchmarking

## Alias Stability

**Aliases are stable references.** They may point to different underlying models over time as we release improvements, but:

- Output quality will improve or stay the same
- API interface remains compatible
- Performance will improve or stay the same

**Notice:** We announce alias updates 7 days in advance.

## Query Current Mapping

```
curl "https://api.render.weyl.ai/models/aliases" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

Response:

```
{
  "aliases": {
    "latest": "dev2",
    "default": "dev",
    "fast": "schnell",
    "turbo": "turbo"
  },
  "updated_at": "2024-01-15T00:00:00Z"
}
```

---

#### Model Discovery

**URL**: https://weyl.ai/api/infrastructure/discovery/
**Description**: List available models

Query available models and their capabilities.

## List Models

**Endpoint:** `GET /models`

```
curl "https://api.render.weyl.ai/models" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

## Response

```
{
  "models": [
    {
      "family": "flux",
      "model": "dev2",
      "modality": "image",
      "tasks": ["t2i", "i2i"],
      "backends": ["nunchaku", "torch"],
      "default_backend": "nunchaku",
      "formats": ["1024", "512", "portrait", "landscape"],
      "status": "active",
      "info": {
        "parameters": "32B",
        "default_steps": 25,
        "guidance_range": [1.0, 5.0]
      }
    },
    {
      "family": "flux",
      "model": "schnell",
      "modality": "image",
      "tasks": ["t2i"],
      "backends": ["nunchaku", "torch", "tensorrt"],
      "default_backend": "nunchaku",
      "formats": ["1024", "512", "portrait", "landscape"],
      "status": "active",
      "info": {
        "parameters": "12B",
        "fixed_steps": 4
      }
    }
  ]
}
```

## Filter by Family

```
curl "https://api.render.weyl.ai/models?family=flux" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

## Filter by Modality

```
curl "https://api.render.weyl.ai/models?modality=video" \
  -H "Authorization: Bearer $WEYL_API_KEY"
```

## Model Status

| Status      | Meaning                        |
|-------------|--------------------------------|
| `active`    | Available for use              |
| `beta`      | Testing phase                  |
| `coming_soon` | Announced, not yet available |
| `deprecated` | Being phased out              |

## Use Cases

### Dynamic Model Selection

```

def get_fastest_image_model():
    resp = requests.get(
        'https://api.render.weyl.ai/models?modality=image',
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    
    models = resp.json()['models']
    # Filter for schnell/turbo variants
    fast_models = [
        m for m in models 
        if 'schnell' in m['model'] or 'turbo' in m['model']
    ]
    
    return fast_models[0] if fast_models else models[0]
```

---

#### Image Uploads

**URL**: https://weyl.ai/api/infrastructure/uploads/
**Description**: Upload images for i2i and i2v tasks

Upload images for image-to-image and image-to-video tasks.

## Methods

### 1. Direct URL

Reference any publicly accessible image:

```
{
  "prompt": "convert to watercolor",
  "image": "https://example.com/photo.jpg"
}
```

### 2. Data URI

Embed image data directly:

```
{
  "prompt": "convert to watercolor",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
```

### 3. Upload Endpoint

**Endpoint:** `POST /uploads`

Upload to Weyl CDN first, then reference:

```
# 1. Upload
curl -X POST "https://api.render.weyl.ai/uploads" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -F "file=@portrait.jpg"

# Response:
# { "url": "https://cdn.render.weyl.ai/u/xyz.jpg" }

# 2. Use in generation
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/i2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -d '{
    "prompt": "watercolor style",
    "image": "https://cdn.render.weyl.ai/u/xyz.jpg"
  }'
```

## Image Requirements

### Formats
- **Supported:** JPEG, PNG, WebP
- **Max size:** 20 MB
- **Max dimensions:** 4096×4096

### Recommendations
- Use WebP for best compression
- Keep under 2048×2048 for faster upload
- Ensure proper aspect ratio for target format

## Upload Limits

- **Max file size:** 20 MB
- **Rate limit:** 100 uploads/min
- **Retention:** 24 hours (use in generation within 24h)

## Python Example

```

# Upload image
with open('portrait.jpg', 'rb') as f:
    resp = requests.post(
        'https://api.render.weyl.ai/uploads',
        headers={'Authorization': f'Bearer {API_KEY}'},
        files={'file': f}
    )
    image_url = resp.json()['url']

# Use in generation
resp = requests.post(
    'https://sync.render.weyl.ai/image/flux/dev/i2i?format=1024',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'prompt': 'watercolor style',
        'image': image_url
    }
)
```

---

#### Models Overview

**URL**: https://weyl.ai/api/models/
**Description**: Available models and capabilities

Weyl supports multiple model families for image and video generation.

## Active Models

| Family   | Modality | Models           | Best For                    |
|----------|----------|------------------|-----------------------------|
| `flux`   | image    | dev2, dev, schnell | General purpose, quality  |
| `zimage` | image    | turbo            | Speed, iteration             |

## FLUX Family

**Black Forest Labs - State of the art image generation**

- **dev2** - FLUX.2 Dev (32B parameters) - Best quality
- **dev** - FLUX.1 Dev (12B parameters) - Balanced
- **schnell** - FLUX.1 Schnell (12B, 4 steps) - Fastest

### Example

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "portrait, natural lighting"}' \
  -o output.webp
```

## Z-Image Family

**Alibaba Tongyi Lab - Ultra-fast generation**

- **turbo** - Z-Image Turbo (6B parameters) - Sub-second generation

### Example

```
curl -X POST "https://sync.render.weyl.ai/image/zimage/turbo/t2i?format=512" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "portrait"}' \
  -o output.webp
```

---

#### Backend Comparison

**URL**: https://weyl.ai/api/models/backends/
**Description**: Nunchaku vs Torch vs TensorRT

Weyl supports three inference backends with different characteristics.

## Overview

| Backend    | Precision | Speed      | Models              |
|------------|-----------|------------|---------------------|
| `nunchaku` | FP4       | ⚡⚡⚡       | FLUX, Z-Image       |
| `torch`    | FP16      | ⚡⚡         | FLUX, WAN           |
| `tensorrt` | Mixed     | ⚡⚡⚡       | FLUX Dev/Schnell    |

## Nunchaku

**NVIDIA FP4 quantization on Blackwell GB200**

- **Precision:** FP4 (4-bit floating point)
- **Speed:** Fastest (3-4× faster than FP16)
- **Quality:** Minimal loss vs FP16

**Supported Models:**
- FLUX Dev2 ✓
- FLUX Dev ✓
- FLUX Schnell ✓
- Z-Image Turbo ✓

## Torch

**PyTorch diffusers with CUDA**

- **Precision:** FP16 (half precision)
- **Framework:** diffusers + transformers
- **Flexibility:** Maximum flexibility

**Supported Models:**
- FLUX Dev2 ✓
- FLUX Dev ✓
- FLUX Schnell ✓
- WAN ✓

## TensorRT

**NVIDIA TensorRT-LLM with ModelOpt**

- **Precision:** Mixed (INT8 + FP16)
- **Optimization:** Ahead-of-time compilation

**Supported Models:**
- FLUX Dev ✓
- FLUX Schnell ✓

## Performance

**FLUX @ 1024×1024:**

| Model   | Backend    | Latency |
|---------|------------|---------|
| schnell | nunchaku   | 450ms   |
| schnell | tensorrt   | 380ms   |
| dev     | nunchaku   | 1.8s    |
| dev     | tensorrt   | 1.5s    |

---

#### FLUX Models

**URL**: https://weyl.ai/api/models/flux/
**Description**: FLUX.2 Dev, FLUX.1 Dev, FLUX.1 Schnell guide

**Family:** `flux`  
**Creator:** Black Forest Labs  
**Modality:** Image generation

State-of-the-art text-to-image models from the creators of Stable Diffusion.

## Model Variants

### FLUX.2 Dev (dev2)

**32B parameter model with Mistral-3 24B text encoder**

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev2/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "portrait in natural light",
    "guidance": 3.5,
    "steps": 25
  }' \
  -o output.webp
```

**Characteristics:**
- Best prompt understanding
- Excellent fine detail
- ~2.4s @ 1024px on nunchaku

**Guidance Tuning:**
- Short prompts: `guidance: 3.5`
- Detailed prompts: `guidance: 1.5`

### FLUX.1 Dev (dev)

**12B parameter model with T5-XXL encoder**

**Characteristics:**
- Excellent quality/speed balance
- Strong baseline model
- ~1.8s @ 1024px on nunchaku

**Guidance:** Standard `guidance: 3.5`

### FLUX.1 Schnell (schnell)

**12B distilled model, optimized for 4 steps**

**Characteristics:**
- Fastest FLUX variant
- Fixed 4 steps
- ~450ms @ 1024px on nunchaku
- Apache-2.0 license

**Fixed Parameters:**
- Steps: `4` (always)
- Guidance: `3.5` (fixed)

---

#### Formats Reference

**URL**: https://weyl.ai/api/models/formats/
**Description**: Video and image format specifications

Complete reference for video and image output formats.

## Image Formats

All image models support these formats via `?format=` parameter.

| Format           | Dimensions | Aspect | Use Case            |
|------------------|------------|--------|---------------------|
| `1024`           | 1024×1024  | 1:1    | High-res square     |
| `512`            | 512×512    | 1:1    | Fast iteration      |
| `portrait`       | 768×1024   | 3:4    | Standard portrait   |
| `portrait-wide`  | 576×1024   | 9:16   | TikTok, Stories     |
| `landscape`      | 1024×768   | 4:3    | Standard landscape  |
| `landscape-wide` | 1024×576   | 16:9   | Widescreen          |

## Video Formats

Video models (WAN) support these formats.

| Format          | Dimensions | Aspect | Use Case         |
|-----------------|------------|--------|------------------|
| `720p`          | 1280×720   | 16:9   | HD landscape     |
| `720p-portrait` | 720×1280   | 9:16   | TikTok, Reels    |
| `480p`          | 832×480    | ~16:9  | Faster gen       |
| `480p-portrait` | 480×832    | ~9:16  | Mobile portrait  |
| `square`        | 640×640    | 1:1    | Social square    |

## Output Specifications

### Image Output
- **Format:** WebP
- **Quality:** 90
- **Color Space:** sRGB
- **Bit Depth:** 8-bit

### Video Output
- **Container:** MP4
- **Codec:** H.264
- **FPS:** 24
- **Bitrate:** ~8 Mbps (720p), ~4 Mbps (480p)

---

#### WAN Video Models

**URL**: https://weyl.ai/api/models/wan/
**Description**: Video generation (coming soon)

**Family:** `wan`  
**Model:** `default` (WAN 2.2)  
**Modality:** Video generation  
**Status:** Coming Soon

Image-to-video generation with high motion coherence.

## Basic Usage (When Available)

```
curl -X POST "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "she turns to face camera",
    "image": "https://example.com/portrait.jpg",
    "duration": 3,
    "cfg": 7.0
  }' \
  -o output.mp4
```

## Parameters

**Required:**
- `prompt` - Motion description
- `image` - Source image

**Optional:**
- `duration` - 0.5-10 seconds
- `cfg` - 6-8 recommended
- `steps` - inference steps
- `seed` - random seed

## Format Support

| Format          | Dimensions | Aspect |
|-----------------|------------|--------|
| `720p`          | 1280×720   | 16:9   |
| `480p`          | 832×480    | ~16:9  |
| `square`        | 640×640    | 1:1    |

---

#### Z-Image Turbo

**URL**: https://weyl.ai/api/models/zimage/
**Description**: Ultra-fast image generation

**Family:** `zimage`  
**Model:** `turbo`  
**Creator:** Alibaba Tongyi Lab  
**License:** Apache-2.0

Ultra-fast image generation optimized for iteration.

## Overview

Z-Image Turbo is a 6B parameter model delivering sub-second generation at 1024×1024.

## Basic Usage

```
curl -X POST "https://sync.render.weyl.ai/image/zimage/turbo/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "portrait, natural lighting"
  }' \
  -o output.webp
```

## Performance

| Resolution | Steps | Latency (p50) |
|------------|-------|---------------|
| 512×512    | 5     | 140ms         |
| 1024×1024  | 8     | 320ms         |

**3-8× faster than FLUX Schnell**

## Parameters

```
{
  "prompt": "description",
  "steps": 8,
  "seed": 42
}
```

**Note:** Z-Image uses fixed CFG 1.0 internally. The `guidance` parameter is ignored.

---

#### Error Reference

**URL**: https://weyl.ai/api/reference/errors/
**Description**: Complete error code reference

Complete reference for all API error codes.

## HTTP Status Codes

| Code | Meaning                  | Typical Cause              |
|------|--------------------------|----------------------------|
| 400  | Bad Request              | Invalid parameters         |
| 401  | Unauthorized             | Missing/invalid API key    |
| 403  | Forbidden                | Policy violation           |
| 404  | Not Found                | Invalid endpoint           |
| 429  | Too Many Requests        | Rate limit exceeded        |
| 503  | Service Unavailable      | Capacity exhausted         |
| 500  | Internal Server Error    | Server-side error          |

## Error Codes

### Authentication Errors

#### `invalid_token`
**Status:** 401  
**Meaning:** API key is malformed or invalid

```
{
  "error": "invalid_token",
  "message": "API key format invalid"
}
```

#### `token_expired`
**Status:** 401  
**Meaning:** API key has expired

#### `insufficient_credits`
**Status:** 402  
**Meaning:** Account has insufficient credits

### Request Errors

#### `invalid_prompt`
**Status:** 400  
**Meaning:** Prompt violates constraints

```
{
  "error": "invalid_prompt",
  "message": "Prompt too long (max 5000 chars)"
}
```

#### `invalid_parameters`
**Status:** 400  
**Meaning:** Request parameters invalid

#### `unsupported_format`
**Status:** 400  
**Meaning:** Format not supported for model

### Content Policy Errors

#### `nsfw_detected`
**Status:** 403  
**Meaning:** Content policy violation detected

```
{
  "error": "nsfw_detected",
  "message": "Content policy violation"
}
```

#### `prompt_filtered`
**Status:** 403  
**Meaning:** Prompt triggered safety filter

### Capacity Errors

#### `capacity_exhausted`
**Status:** 503  
**Meaning:** Sync tier at capacity

```
{
  "error": "capacity_exhausted",
  "message": "sync tier at capacity, retry in 30s",
  "retry_after": 30
}
```

#### `queue_full`
**Status:** 429  
**Meaning:** Async queue at capacity

### Rate Limit Errors

#### `rate_limit_exceeded`
**Status:** 429  
**Meaning:** Too many requests

```
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit: 100/min",
  "retry_after": 15
}
```

## Error Response Format

All errors follow this schema:

```
interface ErrorResponse {
  error: string;
  message: string;
  retry_after?: number;
  details?: Record<string, unknown>;
}
```

---

#### Request Schemas

**URL**: https://weyl.ai/api/reference/requests/
**Description**: Complete request format reference

Complete schemas for all API requests.

## Image Generation Request

```
interface ImageRequest {
  prompt: string;
  negative_prompt?: string;
  steps?: number;
  guidance?: number;
  seed?: number;
  sampler?: 'euler' | 'euler_a' | 'dpmpp_2m' | 'heun';
  scheduler?: 'simple' | 'normal' | 'sgm';
  loras?: LoRAConfig[];
  upscale?: 1.5 | 2 | 4;
  detail_enhance?: boolean;
}

interface LoRAConfig {
  url: string;
  weight: number;
}
```

## Video Generation Request

```
interface VideoRequest {
  prompt: string;
  image: string;
  duration?: number;
  cfg?: number;
  steps?: number;
  seed?: number;
}
```

## Image-to-Image Request

```
interface I2IRequest {
  prompt: string;
  image: string;
  strength?: number;
  steps?: number;
  guidance?: number;
  seed?: number;
}
```

## Async Queue Request

```
interface QueueRequest {
  modality: 'image' | 'video';
  family: 'flux' | 'zimage' | 'wan';
  model: string;
  task: 't2i' | 'i2i' | 't2v' | 'i2v' | 'edit';
  format: string;
  prompt: string;
  priority?: 'low' | 'normal' | 'high';
  webhook?: string;
  idempotency_key?: string;
  // ... other generation params
}
```

## Validation Rules

### Prompt
- **Min length:** 3 characters
- **Max length:** 5000 characters
- **Required:** Yes (except i2i with strength > 0.8)

### Steps
- **FLUX Dev/Dev2:** 15-50
- **FLUX Schnell:** 4 (fixed)
- **Z-Image:** 5-12

### Guidance
- **FLUX:** 1.0-5.0
- **WAN:** 6.0-8.0
- **Z-Image:** Ignored (fixed 1.0)

### Seed
- **Range:** 0 - 4294967295
- **Default:** Random

---

#### Response Schemas

**URL**: https://weyl.ai/api/reference/responses/
**Description**: Complete response format reference

Complete schemas for all API responses.

## Sync Success (200)

```
HTTP/1.1 200 OK
Content-Type: image/webp
Content-Location: https://cdn.render.weyl.ai/i/xyz.webp
X-Generation-Time: 1847
X-Seed: 42

<binary data>
```

## Sync Capacity Exhausted (503)

```
HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "error": "capacity_exhausted",
  "message": "sync tier at capacity, retry in 30s",
  "retry_after": 30
}
```

## Async Job Queued (202)

```
{
  "id": "j_abc123",
  "status": "queued",
  "position": 5,
  "eta_seconds": 75,
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Async Job Status

### Queued

```
{
  "id": "j_abc123",
  "status": "queued",
  "position": 3,
  "eta_seconds": 45
}
```

### Running

```
{
  "id": "j_abc123",
  "status": "running",
  "progress": 0.65,
  "step": 20,
  "total_steps": 30,
  "eta_seconds": 8
}
```

### Complete (303)

```
HTTP/1.1 303 See Other
Location: https://cdn.render.weyl.ai/i/xyz.webp
```

Or with body:

```
{
  "id": "j_abc123",
  "status": "complete",
  "output": "https://cdn.render.weyl.ai/i/xyz.webp",
  "duration_ms": 2340,
  "completed_at": "2024-01-15T10:31:23Z"
}
```

### Failed

```
{
  "id": "j_abc123",
  "status": "failed",
  "error": {
    "code": "nsfw_detected",
    "message": "Content policy violation"
  },
  "failed_at": "2024-01-15T10:30:45Z"
}
```

## Headers

### Response Headers

- `Content-Location` - Permanent CDN URL
- `X-Generation-Time` - Latency in milliseconds
- `X-Seed` - Seed used for generation
- `Retry-After` - Seconds to wait before retry

---

#### Type Reference

**URL**: https://weyl.ai/api/reference/types/
**Description**: TypeScript type definitions

Complete TypeScript type definitions for the Weyl API.

## Core Types

```
type Modality = 'image' | 'video';

type Family = 'flux' | 'zimage' | 'wan';

type Task = 't2i' | 'i2i' | 't2v' | 'i2v' | 'edit';

type ImageFormat = 
  | '1024' | '512'
  | 'portrait' | 'portrait-wide'
  | 'landscape' | 'landscape-wide';

type VideoFormat = 
  | '720p' | '720p-portrait'
  | '480p' | '480p-portrait'
  | 'square';

type Backend = 'nunchaku' | 'torch' | 'tensorrt';

type Sampler = 'euler' | 'euler_a' | 'dpmpp_2m' | 'heun';

type Scheduler = 'simple' | 'normal' | 'sgm';

type Priority = 'low' | 'normal' | 'high';

type JobStatus = 'queued' | 'running' | 'complete' | 'failed' | 'cancelled';
```

## Request Types

```
interface BaseGenerationRequest {
  prompt: string;
  negative_prompt?: string;
  steps?: number;
  guidance?: number;
  seed?: number;
}

interface ImageGenerationRequest extends BaseGenerationRequest {
  sampler?: Sampler;
  scheduler?: Scheduler;
  loras?: LoRAConfig[];
  upscale?: 1.5 | 2 | 4;
  detail_enhance?: boolean;
  detail_strength?: number;
}

interface I2IRequest extends ImageGenerationRequest {
  image: string;
  strength?: number;
}

interface VideoGenerationRequest extends BaseGenerationRequest {
  image: string;
  duration?: number;
  cfg?: number;
}

interface LoRAConfig {
  url: string;
  weight: number;
}
```

## Response Types

```
interface Job {
  id: string;
  status: JobStatus;
  created_at: string;
  started_at?: string;
  completed_at?: string;
  failed_at?: string;
}

interface QueuedJob extends Job {
  status: 'queued';
  position: number;
  eta_seconds: number;
}

interface RunningJob extends Job {
  status: 'running';
  progress: number;
  step: number;
  total_steps: number;
  eta_seconds: number;
}

interface CompleteJob extends Job {
  status: 'complete';
  output: string;
  duration_ms: number;
}

interface FailedJob extends Job {
  status: 'failed';
  error: {
    code: string;
    message: string;
  };
}
```

## WebSocket Types

```
interface WSMessage {
  type: string;
  [key: string]: unknown;
}

interface WSAuthMessage extends WSMessage {
  type: 'auth';
  token: string;
}

interface WSGenerateMessage extends WSMessage {
  type: 'generate';
  modality: Modality;
  family: Family;
  model: string;
  task: Task;
  format: string;
  stream_frames?: boolean;
}

interface WSFrameMessage extends WSMessage {
  type: 'frame';
  step: number;
  total_steps: number;
  data: string;
}

interface WSCompleteMessage extends WSMessage {
  type: 'complete';
  output: string;
  latency_ms?: number;
}
```

---

#### Sync Tier Overview

**URL**: https://weyl.ai/api/sync/
**Description**: Real-time synchronous generation

**Base URL:** `https://sync.render.weyl.ai`

Synchronous generation on dedicated bare metal. POST your request, receive bytes directly.

## Image Generation

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "cyberpunk street scene"}' \
  -o output.webp
```

## Video Generation

```
curl -X POST "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "she turns to face the camera",
    "image": "https://example.com/portrait.jpg"
  }' \
  -o output.mp4
```

## Response

Success returns 200 with binary data. The `Content-Location` header contains the permanent CDN URL.

---

#### Capacity Management

**URL**: https://weyl.ai/api/sync/capacity/
**Description**: Handling 503 errors

The sync tier runs on dedicated capacity. When exhausted, requests return 503.

## Understanding 503

```
HTTP/1.1 503 Service Unavailable
Retry-After: 30

{
  "error": "capacity_exhausted",
  "message": "sync tier at capacity, retry in 30s or use async"
}
```

## Response Strategy

### 1. Retry with Backoff

```

def generate_with_backoff(url, data, headers, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.post(url, json=data, headers=headers)
        
        if resp.status_code == 200:
            return resp.content
        
        if resp.status_code == 503:
            retry_after = int(resp.headers.get('Retry-After', 30))
            backoff = retry_after * (2 ** attempt)
            time.sleep(backoff)
            continue
        
        resp.raise_for_status()
```

### 2. Fallback to Async

Switch to async tier when sync is exhausted.

```
# Try sync first
try:
    resp = requests.post(sync_url, ...)
    if resp.status_code == 200:
        return resp.content
except:
    pass

# Fall back to async
resp = requests.post(async_url, ...)
```

---

#### Image Generation (Sync)

**URL**: https://weyl.ai/api/sync/image/
**Description**: Synchronous image generation

**Endpoint:** `POST /image/{family}/{model}/{task}`

Generate images with immediate response.

## Text-to-Image (t2i)

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cyberpunk street at night",
    "guidance": 3.5,
    "seed": 42
  }' \
  -o output.webp
```

## Image-to-Image (i2i)

Transform an existing image.

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev/i2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "convert to watercolor style",
    "image": "https://example.com/photo.jpg",
    "strength": 0.7
  }' \
  -o transformed.webp
```

## Common Parameters

- `prompt` - Generation prompt (required)
- `negative_prompt` - What to avoid
- `steps` - Inference steps
- `guidance` - Prompt adherence (1.0-5.0)
- `seed` - Random seed

---

#### Video Generation (Sync)

**URL**: https://weyl.ai/api/sync/video/
**Description**: Synchronous video generation

**Endpoint:** `POST /video/{family}/{model}/{task}`

Generate video with immediate response.

## Image-to-Video (i2v)

Animate a still image with motion.

```
curl -X POST "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "she slowly turns to face the camera",
    "image": "https://example.com/portrait.jpg",
    "duration": 3,
    "cfg": 7.0
  }' \
  -o output.mp4
```

## Parameters

**Required:**
- `prompt` - Motion description
- `image` - Source image URL or data URI

**Optional:**
- `duration` - Video length in seconds (0.5-10, default: 2)
- `cfg` - Guidance scale (6-8 for WAN)
- `steps` - Inference steps
- `seed` - Random seed

## Response

```
HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Location: https://cdn.render.weyl.ai/v/xyz123.mp4

<video bytes>
```

---

#### WebSocket Overview

**URL**: https://weyl.ai/api/websocket/
**Description**: Real-time streaming protocols

WebSocket connections enable real-time streaming for both sync and async tiers.

## Connection

```
const ws = new WebSocket('wss://sync.render.weyl.ai/ws');
// or
const ws = new WebSocket('wss://async.render.weyl.ai/ws');
```

## Authentication

Authenticate after connection opens:

```
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'wyl_sk_prod_1234567890abcdef'
  }));
};
```

## Message Format

All messages are JSON:

```
interface Message {
  type: string;
  [key: string]: unknown;
}
```

## Use Cases

### Sync Tier WebSocket
- Progressive frame streaming
- Real-time progress updates
- Interactive generation

### Async Tier WebSocket
- Job progress events
- Queue position updates
- Completion notifications

## Next Steps

- [Sync Tier WebSocket](/api/websocket/sync/) - Frame streaming
- [Async Tier WebSocket](/api/websocket/async/) - Job events
- [Protocol Reference](/api/websocket/protocol/) - Message specs

---

#### Async Tier WebSocket

**URL**: https://weyl.ai/api/websocket/async/
**Description**: Job progress events

**Endpoint:** `wss://async.render.weyl.ai/ws`

Subscribe to async job progress events.

## Connection Flow

```
const ws = new WebSocket('wss://async.render.weyl.ai/ws');

ws.onopen = () => {
  // 1. Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: API_KEY
  }));
  
  // 2. Subscribe to job
  ws.send(JSON.stringify({
    type: 'subscribe',
    job_id: 'j_abc123'
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  switch (msg.type) {
    case 'position':
      console.log(`Queue position: ${msg.position}`);
      break;
    case 'started':
      console.log('Generation started');
      break;
    case 'progress':
      console.log(`Progress: ${msg.progress * 100}%`);
      break;
    case 'complete':
      console.log(`Output: ${msg.output}`);
      break;
  }
};
```

## Message Types

### `position`
Queue position update:

```
{
  "type": "position",
  "position": 3,
  "eta_seconds": 45
}
```

### `started`
Generation started:

```
{
  "type": "started",
  "started_at": "2024-01-15T10:30:00Z"
}
```

### `progress`
Generation progress:

```
{
  "type": "progress",
  "progress": 0.65,
  "step": 20,
  "total_steps": 30
}
```

### `complete`
Job complete:

```
{
  "type": "complete",
  "output": "https://cdn.render.weyl.ai/i/xyz.webp",
  "duration_ms": 2340
}
```

### `error`
Job failed:

```
{
  "type": "error",
  "code": "nsfw_detected",
  "message": "Content policy violation"
}
```

---

#### WebSocket Protocol Reference

**URL**: https://weyl.ai/api/websocket/protocol/
**Description**: Complete message specification

Complete specification for WebSocket message types.

## Client → Server

### `auth`
Authenticate the connection:

```
{
  "type": "auth",
  "token": "wyl_sk_..."
}
```

### `generate` (Sync)
Submit generation request:

```
{
  "type": "generate",
  "modality": "image",
  "family": "flux",
  "model": "dev",
  "task": "t2i",
  "format": "1024",
  "prompt": "description",
  "stream_frames": true
}
```

### `subscribe` (Async)
Subscribe to job events:

```
{
  "type": "subscribe",
  "job_id": "j_abc123"
}
```

### `unsubscribe` (Async)
Unsubscribe from job:

```
{
  "type": "unsubscribe",
  "job_id": "j_abc123"
}
```

### `cancel` (Async)
Cancel running job:

```
{
  "type": "cancel",
  "job_id": "j_abc123"
}
```

## Server → Client

### `authenticated`
Auth successful:

```
{
  "type": "authenticated",
  "user_id": "usr_xyz"
}
```

### `error`
Error occurred:

```
{
  "type": "error",
  "code": "invalid_token",
  "message": "Authentication failed"
}
```

### `frame` (Sync)
Progressive frame:

```
{
  "type": "frame",
  "step": 15,
  "total_steps": 25,
  "data": "base64_jpeg..."
}
```

### `complete`
Generation complete:

```
{
  "type": "complete",
  "output": "https://cdn.render.weyl.ai/i/xyz.webp"
}
```

## Connection Limits

- **Max connections per API key:** 10
- **Idle timeout:** 5 minutes
- **Max message size:** 10 MB

---

#### Sync Tier WebSocket

**URL**: https://weyl.ai/api/websocket/sync/
**Description**: Progressive frame streaming

**Endpoint:** `wss://sync.render.weyl.ai/ws`

Stream generation frames progressively during inference.

## Connection Flow

```
const ws = new WebSocket('wss://sync.render.weyl.ai/ws');

ws.onopen = () => {
  // 1. Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: API_KEY
  }));
  
  // 2. Submit generation
  ws.send(JSON.stringify({
    type: 'generate',
    modality: 'image',
    family: 'flux',
    model: 'dev',
    task: 't2i',
    format: '1024',
    prompt: 'cyberpunk street',
    stream_frames: true
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'frame') {
    // Progressive frame (base64 JPEG)
    updatePreview(msg.data);
  }
  
  if (msg.type === 'complete') {
    // Final result (WebP URL)
    displayResult(msg.output);
  }
};
```

## Message Types

### `frame`
Progressive denoising frame (sent every 5 steps):

```
{
  "type": "frame",
  "step": 15,
  "total_steps": 25,
  "data": "base64_jpeg_data..."
}
```

### `complete`
Final generation result:

```
{
  "type": "complete",
  "output": "https://cdn.render.weyl.ai/i/xyz.webp",
  "latency_ms": 1847
}
```

## Frame Frequency

Frames are sent every 5 steps to balance bandwidth and smoothness.

**Example (25 steps):**
- Step 5, 10, 15, 20, 25 → 5 frames total

---

### Design System

#### Typography System

**URL**: https://weyl.ai/design/typography/
**Description**: Complete typography guide for Weyl's dual-system design

Weyl implements a **dual typography system*

* that reflects our epistemological stance: data requires different typography than institutions.--

-

## Hypermodern Typography (Dark Mode)> "The terminal doesn't lie. The terminal doesn't comfort."Monospace typography enforces data integrity. Every character occupies the same width, making columns align, diffs visible, and data scannable.#

## Font Stack

```cssfont-family: 'Iosevka', 'Berkeley Mono', 'SF Mono', 'JetBrains Mono', 'Fira Code', monospace;

```

**Display Font:*

* Aldrich — Geometric, technical, for headlines#

## Type Scale

| Class 

| Size | Usage ||-------|------|-------|| `.text-hero` | 48px | Hero sections, major announcements || `.text-headline` | 32px | Section headers || `.text-subhead` | 24px | Subsections || `.text-body` | 16px | Body content || `.text-secondary` | 14px | Secondary information || `.text-caption` | 12px | Captions, labels || `.text-micro` | 10px | Micro labels, metadata |#

## Weight SemanticsWeight indicates **signal strength**:

- **300 (Light)**: Historical, derived, context

- **400 (Regular)**: Current data, standard

- **500 (Medium)**: Elevated importance

- **600 (Semibold)**: Key metrics

- **700 (Bold)**: Primary emphasis

- **800 (Heavy)**: Critical, active state#

## Semantic Colors<div class="grid grid-cols-2 gap-4 my-8">  <div class="p-4 bg-bg-surface border border-border rounded-md">    <div class="text-link font-mono mb-2">█ Links / Interactive</div>    <code class="text-caption">#54aeff</code>  </div>    <div class="p-4 bg-bg-surface border border-border rounded-md">    <div class="text-success-state font-mono mb-2">█ Nominal / Confirmed</div>    <code class="text-caption">#3fb950</code>  </div>    <div class="p-4 bg-bg-surface border border-border rounded-md">    <div class="text-warning-state font-mono mb-2">█ Caution / Threshold</div>    <code class="text-caption">#ffa657</code>  </div>    <div class="p-4 bg-bg-surface border border-border rounded-md">    <div class="text-error-state font-mono mb-2">█ Critical / Fault</div>    <code class="text-caption">#ff7b72</code>  </div></div>#

## Example: Metric Display

```html<div class="metric">  <span class="metric-value">43.5</span>  <span class="metric-unit">it/s</span>  <span class="metric-label">throughput</span></div>

```<div class="metric my-8 p-6 bg-bg-surface border border-border rounded-md">  <span class="metric-value">43.5</span>  <span class="metric-unit">it/s</span>  <span class="metric-label">throughput</span></div>#

## Example: Status Bar

```html<div class="status-bar">  <span class="status nominal">█ NOMINAL</span>  <span class="status-item">latency: 1.2ms</span>  <span class="status-item">state: LIVE</span></div>

```<div class="status-bar my-8 p-4 bg-bg-surface border border-border rounded-md">  <span class="status nominal">█ NOMINAL</span>  <span class="status-item">latency: 1.2ms</span>  <span class="status-item">state: LIVE</span></div>--

-

## High Modernism Typography (Light Mode)> "The institution earned trust by delivering. The stamp meant something."Sans-serif typography communicates institutional authority. Weight indicates rank, size indicates importance, spacing indicates formality.#

## Font Stack

```cssfont-family: 'Helvetica Neue', 'Univers', 'Arial', 'Liberation Sans', system-ui, sans-serif;

```

**Display Fonts:**

- 

**Futura*

* — Bauhaus geometry for proclamations

- 

**Trade Gothic*

* — Industrial strength for institutional headers

**Serif:*

* Georgia or Charter — For attributed statements and emphasis#

## Departmental ColorsAvailable in light mode:

- `.text-executive` — Authority, directive (#1a1a1a)

- `.text-administration` — Department headers (#1a5276)

- `.text-operations` — Procedure, verified (#2d5a27)

- `.text-priority` — Urgent, critical (#c41e3a)

- `.text-heritage` — Archive, historical (#8b7355)

- `.text-gilt` — Ceremony, achievement (#d4a017)#

## Example: Document Header

```html<header class="document-header">  <h1 class="proclamation">QUALITY ASSURANCE</h1>  <p class="division">STANDARDS BUREAU</p>  <p class="document-number">Document No. 1962-QA-0042</p></header>

```#

## Example: Institutional Quote

```html<blockquote class="institutional-quote">  <p>"In a well-ordered laboratory, precision is not a goal but a habit."</p>  <cite>— Bureau of Standards, 1962</cite></blockquote>

```<blockquote class="institutional-quote my-8">  <p>"In a well-ordered laboratory, precision is not a goal but a habit."</p>  <cite>— Bureau of Standards, 1962</cite></blockquote>--

-

## Utility Classes#

## Line Heights

- `.leading-tight` — 1.2 (for headlines)

- `.leading-normal` — 1.5 (for body text)

- `.leading-relaxed` — 1.7 (for long-form content)#

## Letter Spacing

- `.tracking-tight` — -0.02em

- `.tracking-normal` — 0

- `.tracking-wide` — 0.04em

- `.tracking-wider` — 0.08em#

## Special Features

- `.tabular-nums` — For aligned numeric data

- `.readable-content` — Max-width: 65ch for optimal readability

- `.truncate` — Text overflow with ellipsis--

-

## The `//` ConventionIn hypermodern typography, double slashes serve as semantic delimiters:

```// section //// render // weyl // ai// status: nominal //

```This convention:

- References C++/programming comments

- Creates visual rhythm

- Indicates machine-readable segments

- Separates navigation from content

**Do not use*

* in High Modernism contexts—use traditional punctuation.--

-

## Accessibility#

## Contrast Ratios

- Body text: **4.5:1*

* minimum (WCAG AA)

- Large text (>18px): **3:1*

* minimum (WCAG AA)

- UI components: **3:1*

* minimum (WCAG AA)#

## Font Size Minimums

- Body text: **16px*

* minimum

- Interactive elements: **14px*

* minimum

- Captions: **12px*

* minimum (sparingly)#

## Line LengthOptimal: **45-75 characters per line

**Use `.readable-content` class for max-width constraint:

```html<article class="readable-content">  <!-

- Content automatically constrained to 65ch --></article>

```--

-

## Responsive BehaviorTypography automatically scales on mobile devices:

- Hero: 48px → 32px

- Headline: 32px → 24px

- Subhead: 24px → 18px

- Body: 16px (maintains for readability)--

-

## Print StylesAll content automatically switches to High Modernism for print:

- Sans-serif typography

- Black text on white background

- No shadows or glow effects

- 11pt base size with 1.4 line height--

-

## ImplementationAll typography utilities are available globally. Simply use the classes:

```html<h1 class="font-display text-hero tracking-wide">WEYL</h1><p class="font-mono text-body leading-normal">Infrastructure for generative media.</p><span class="text-caption tracking-wider uppercase">© 2024</span>

```For custom implementations, use CSS variables:

```css.custom-header {  font-family: var(--font-display);  font-size: var(--text-headline);  line-height: var(--leading-tight);  letter-spacing: var(--tracking-wide);  color: var(--color-brand-primary);}

```

---

### Getting Started

#### Introduction

**URL**: https://weyl.ai/getting-started/
**Description**: Get started with Weyl inference infrastructure

Weyl is purpose-built inference infrastructure for generative media. We provide sub-100ms latency for diffusion models running on Blackwell architecture with FP4 precision.

## Why Weyl?

- **Low Latency**: Sub-100ms p99 latency with optimized CUDA kernels
- **Cost Optimized**: FP4 quantization delivers 4x throughput improvement
- **Reliable**: Multi-region redundancy with 99.99% uptime SLA
- **Scalable**: From prototype to production with automatic scaling

## Key Features

### Hardware Acceleration

Built on NVIDIA Blackwell GB200 with custom kernels for FP4 Tensor Cores. Direct NVLink fabric access for zero-copy memory transfers.

### Model Support

- Stable Diffusion XL
- FLUX.1
- Custom fine-tuned models
- Bring your own weights

### API Design

REST and gRPC endpoints with WebSocket streaming for real-time generation. OpenAPI 3.1 specification with full TypeScript types.

## Next Steps

- [Quick Start](/getting-started/quick-start/) - Get up and running in 5 minutes
- [Authentication](/getting-started/auth/) - Set up your API keys
- [API Reference](/api/) - Complete API documentation

---

#### Authentication

**URL**: https://weyl.ai/getting-started/auth/
**Description**: Set up your API keys

All API requests require authentication via Bearer token.

## Get Your API Key

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a>
2. Fill out the access request form with your project details
3. Receive your API key via email within 24 hours
4. Securely store your key (it will be shown in the email)

## Using Your Key

### Environment Variable (Recommended)

```

```

Then reference in your code:

```
curl -H "Authorization: Bearer $WEYL_API_KEY" ...
```

### In Code

```

headers = {
    "Authorization": f"Bearer {os.environ['WEYL_API_KEY']}"
}

resp = requests.post(url, headers=headers, json=payload)
```

## Key Types

| Prefix      | Type       | Use Case                           |
|-------------|------------|------------------------------------|
| `wyl_sk_prod_` | Production | Live applications                  |
| `wyl_sk_dev_`  | Development| Testing, staging environments      |
| `wyl_sk_test_` | Test       | Rate-limited, for prototyping      |

## Rate Limits

Rate limits vary by plan:

| Plan       | Sync (req/min) | Async (req/min) | Notes                    |
|------------|----------------|-----------------|--------------------------|
| Free       | 10             | 30              | Test keys only           |
| Starter    | 60             | 300             | Burst to 120/min         |
| Pro        | 600            | 3000            | Dedicated capacity       |
| Enterprise | Custom         | Custom          | SLA, priority support    |

When rate limited, you'll receive a `429` response with a `Retry-After` header.

## Best Practices

### Security

- **Never commit keys to version control**
- Use environment variables or secret managers
- Rotate keys every 90 days
- Use separate keys for dev/staging/prod

### Error Handling

```
resp = requests.post(url, headers=headers, json=payload)

if resp.status_code == 401:
    print("Invalid or expired API key")
elif resp.status_code == 429:
    retry_after = int(resp.headers.get('Retry-After', 60))
    print(f"Rate limited, retry in {retry_after}s")
else:
    resp.raise_for_status()
```

## Next Steps

- [Quick Start](/getting-started/quick-start/) - Generate your first image
- [API Overview](/api/) - Learn the API structure

---

#### Quick Start

**URL**: https://weyl.ai/getting-started/quick-start/
**Description**: Get up and running in 5 minutes

Get your first image generated in under 5 minutes.

## 1. Request API Access

<a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> by filling out our access request form. Once approved, you'll receive your API key via email within 24 hours.

```

```

## 2. Generate Your First Image

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"cyberpunk street at night, neon rain"}' \
  -o output.webp
```

The response body contains the image bytes. The `Content-Location` header points to the permanent CDN URL.

## 3. Try Different Models

### FLUX.2 Dev (32B, highest quality)

```
curl -X POST "https://sync.render.weyl.ai/image/flux/dev2/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"portrait of a woman, rembrandt lighting"}' \
  -o portrait.webp
```

### Z-Image Turbo (sub-second generation)

```
curl -X POST "https://sync.render.weyl.ai/image/zimage/turbo/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"mountain landscape, golden hour"}' \
  -o landscape.webp
```

## 4. Use with Python

```

def generate_image(prompt: str) -> bytes:
    url = "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024"
    
    headers = {
        "Authorization": f"Bearer {os.environ['WEYL_API_KEY']}",
        "Content-Type": "application/json"
    }
    
    payload = {"prompt": prompt}
    
    resp = requests.post(url, headers=headers, json=payload)
    resp.raise_for_status()
    
    # Get permanent CDN URL
    cdn_url = resp.headers.get('Content-Location')
    print(f"Permanent URL: {cdn_url}")
    
    return resp.content

# Generate
image_bytes = generate_image("neon city at night")

with open("output.webp", "wb") as f:
    f.write(image_bytes)
```

## Next Steps

- [Authentication](/getting-started/auth/) - API keys and best practices
- [Sync Tier](/api/sync/) - Real-time generation
- [Async Tier](/api/async/) - Queue-based workflows
- [Models](/api/models/) - Available models

---

### AI Workflows

#### AI Workflows

**URL**: https://weyl.ai/workflows/
**Description**: Generate images and video in your favorite AI coding tools - Cursor, Claude, v0, Lovable, and Bolt

Generate stunning images and video directly in your AI coding environment. Weyl provides sub-100ms latency for real-time generation workflows.

## Why Weyl for AI Coding?

- **Fast**: Sub-100ms p99 latency - perfect for interactive workflows
- **Simple**: Copy-paste ready code snippets
- **Powerful**: FLUX, SDXL, and video generation at your fingertips
- **Reliable**: 99.99% uptime with multi-region redundancy

## Choose Your Tool

| Tool | Best For | Integration Method |
|------|----------|-------------------|
| [Cursor](/workflows/cursor/) | IDE integration, live previews | API calls in code |
| [Claude](/workflows/claude/) | Projects, MCP server | Context files, tools |
| [v0](/workflows/v0/) | UI component generation | API in generated code |
| [Lovable](/workflows/lovable/) | Full-stack apps | Backend API integration |
| [Bolt](/workflows/bolt/) | Rapid prototyping | Direct API calls |

## Common Use Cases

### Hero Images
Generate custom hero images for landing pages without leaving your IDE.

```
# Quick example - works anywhere
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"modern tech startup office, bright natural lighting"}' \
  -o hero.webp
```

### UI Mockups
Create placeholder images that match your design vision.

```
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=512" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"product shot, minimal background, studio lighting"}' \
  -o product.webp
```

### Video Content
Generate short video clips for prototypes and demos.

```
curl -X POST "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"camera slowly zooms in","image":"https://your-image.jpg"}' \
  -o demo.mp4
```

## Quick Start

1. **Request API Access** - <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. **Pick Your Tool** - Choose from Cursor, Claude, v0, Lovable, or Bolt above
3. **Copy & Paste** - Each guide has ready-to-use code snippets
4. **Generate** - Start creating images and video in seconds

## Sync vs Async

### Sync Tier (Real-Time)
Use `sync.render.weyl.ai` for interactive workflows:
- Instant results
- Perfect for live previews
- Returns 503 if capacity full

### Async Tier (Batch)
Use `async.render.weyl.ai` for cost optimization:
- Queue-based
- Lower pricing
- Poll for results

Most vibe coding workflows use the sync tier for immediate feedback.

## Need Help?

- [API Overview](/api/) - Complete API reference
- [Model Guide](/api/models/) - Available models and formats
- [Authentication](/getting-started/auth/) - Set up your API keys

## Next Steps

Choose your tool from the table above to get started with tool-specific guides and examples.

---

#### Bolt.new AI Image & Video Generation

**URL**: https://weyl.ai/workflows/bolt/
**Description**: Generate images and video in Bolt.new projects - rapid prototyping with AI-powered visuals

Build rapid prototypes with AI-generated images and video using Bolt.new and Weyl. Perfect for quick demos, MVPs, and proof-of-concepts.

## Quick Setup

### Prerequisites

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. Access to Bolt.new

## Method 1: Include in Initial Prompt

Start your Bolt project with Weyl integration from the beginning.

### Example Bolt Prompt

```
Create a landing page with dynamic image generation using Weyl API.

Requirements:
- Hero section with AI-generated background
- "Generate New" button to refresh image
- Use Weyl API: https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024
- Store API key in environment variable WEYL_API_KEY
- Show loading state during generation
- Display error messages if generation fails
- Modern, responsive design

Tech: React, Vite, Tailwind CSS
```

### What Bolt Will Generate

Bolt creates:
- Complete React app with Vite setup
- API integration for Weyl
- Environment variable configuration
- UI with loading and error states
- Full styling with Tailwind

## Method 2: Add to Existing Bolt Project

Add image generation to a project you've already started:

### Follow-Up Prompt

```
Add image generation feature using Weyl API.

Add to my app:
- New "/generate" route with image generator
- Input field for prompts
- Generate button
- Display generated images in a grid
- Download button for each image
- API endpoint: POST https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024
- Use WEYL_API_KEY from .env
```

### Generated Code

```
// src/pages/Generate.tsx

  const [prompt, setPrompt] = useState('')
  const [images, setImages] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState('')

  async function handleGenerate() {
    if (!prompt.trim()) return

    setLoading(true)
    setError('')

    try {
      const response = await fetch(
        'https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024',
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${import.meta.env.VITE_WEYL_API_KEY}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ prompt }),
        }
      )

      if (!response.ok) {
        throw new Error(`Error: ${response.status}`)
      }

      // Get image as blob
      const blob = await response.blob()
      const imageUrl = URL.createObjectURL(blob)
      
      // Also get CDN URL from header
      const cdnUrl = response.headers.get('Content-Location')
      
      setImages([cdnUrl || imageUrl, ...images])
      setPrompt('')
    } catch (err) {
      setError('Failed to generate image. Please try again.')
      console.error(err)
    } finally {
      setLoading(false)
    }
  }

  return (
    <div className="min-h-screen bg-gradient-to-br from-purple-50 to-blue-50 p-8">
      <div className="mx-auto max-w-6xl">
        <h1 className="mb-8 text-4xl font-bold text-gray-900">
          AI Image Generator
        </h1>

        <div className="mb-8 flex gap-4">
          <input
            type="text"
            value={prompt}
            onChange={(e) => setPrompt(e.target.value)}
            onKeyDown={(e) => e.key === 'Enter' && handleGenerate()}
            placeholder="Describe your image..."
            className="flex-1 rounded-lg border border-gray-300 px-4 py-3 text-lg focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500"
          />
          <button
            onClick={handleGenerate}
            disabled={loading || !prompt.trim()}
            className="flex items-center gap-2 rounded-lg bg-purple-600 px-6 py-3 font-semibold text-white hover:bg-purple-700 disabled:opacity-50"
          >
            {loading ? (
              <>
                
                Generating...
              </>
            ) : (
              <>
                
                Generate
              </>
            )}
          </button>
        </div>

        {error && (
          <div className="mb-8 rounded-lg bg-red-50 p-4 text-red-700">
            {error}
          </div>
        )}

        <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
          {images.map((url, index) => (
            <div
              key={index}
              className="group relative overflow-hidden rounded-lg bg-white shadow-lg"
            >
              <img
                src={url}
                alt={`Generated ${index}`}
                className="h-64 w-full object-cover"
              />
              <button
                onClick={() => window.open(url, '_blank')}
                className="absolute right-2 top-2 rounded-full bg-white p-2 opacity-0 shadow-lg transition-opacity hover:bg-gray-100 group-hover:opacity-100"
              >
                
              </button>
            </div>
          ))}
        </div>

        {images.length === 0 && !loading && (
          <div className="text-center text-gray-500">
            
            <p className="text-lg">Generate your first image to get started</p>
          </div>
        )}
      </div>
    </div>
  )
}
```

```
# .env
VITE_WEYL_API_KEY=your_api_key_here
```

## Method 3: Full-Stack with Backend

For production-ready apps with a backend:

### Bolt Prompt

```
Create a full-stack app with image generation.

Frontend:
- React with Vite
- Tailwind CSS
- Image generation interface
- Gallery view

Backend:
- Express server
- API route for Weyl integration
- Store WEYL_API_KEY server-side (not exposed to client)
- Rate limiting
- Error handling

Features:
- Generate images with prompts
- Save generated images
- View history
- Download images
- Copy CDN URLs
```

### Generated Backend

```
// server/index.ts

dotenv.config()

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

app.post('/api/generate-image', async (req, res) => {
  const { prompt } = req.body

  if (!prompt) {
    return res.status(400).json({ error: 'Prompt is required' })
  }

  try {
    const response = await fetch(
      'https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.WEYL_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ prompt }),
      }
    )

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`)
    }

    const imageBuffer = await response.arrayBuffer()
    const cdnUrl = response.headers.get('Content-Location')

    res.json({
      success: true,
      url: cdnUrl,
      prompt,
    })
  } catch (error) {
    console.error('Generation error:', error)
    res.status(500).json({ error: 'Failed to generate image' })
  }
})

const PORT = process.env.PORT || 3001
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})
```

## Common Use Cases

### 1. Portfolio Generator

```
Create a portfolio website that generates custom artwork.

Features:
- Homepage with featured generated art
- "Generate Art" page with style controls
- Gallery of all generated pieces
- Click to view full size
- Download originals
- Share on social media
- Uses Weyl FLUX dev for quality
```

### 2. Product Mockup Tool

```
Build a product mockup generator.

Features:
- Product type selector (phone, laptop, bottle, etc.)
- Background style options
- Generate button
- Instant preview
- Download in multiple formats
- Batch generate variations
- Weyl API integration
```

### 3. Blog Header Generator

```
Create a tool that generates blog post headers.

Features:
- Blog title input
- Category/mood selector
- Generate matching header image
- Preview in blog layout
- Regenerate if not satisfied
- Export with correct dimensions
- Uses FLUX schnell for speed
```

### 4. Avatar Creator

```
Build an avatar generation tool.

Features:
- Style picker (realistic, cartoon, pixel art)
- Gender/age options
- Accessories customization
- Generate avatar
- Crop to circle
- Download or copy URL
- Weyl FLUX models
```

## Bolt-Specific Tips

### 1. Use Vite Environment Variables

Bolt uses Vite, so prefix with `VITE_`:

```
// Access in frontend
const apiKey = import.meta.env.VITE_WEYL_API_KEY

// .env file
VITE_WEYL_API_KEY=your_key_here
```

**Note**: Never expose API keys in frontend code for production! Use a backend proxy.

### 2. Iterative Prompts

Bolt excels at iterative development. Start simple:

```
Add image generation button to homepage
```

Then refine:

```
Make the button more prominent and add a preview modal
```

Then enhance:

```
Add multiple image format options and model selection
```

### 3. Request Specific Libraries

```
Use lucide-react for icons
Use clsx for conditional classnames
Use react-hot-toast for notifications
```

Bolt will integrate them seamlessly.

### 4. Mobile-First Design

Always mention:

```
Make it fully responsive and mobile-friendly
```

Bolt will generate proper Tailwind responsive classes.

## Advanced Patterns

### Pattern 1: Image Variations

```
async function generateVariations(basePrompt: string, count = 4) {
  const variations = [
    `${basePrompt}, style A`,
    `${basePrompt}, style B`,
    `${basePrompt}, style C`,
    `${basePrompt}, style D`,
  ]

  const results = await Promise.all(
    variations.map((prompt) =>
      fetch('https://sync.render.weyl.ai/image/flux/schnell/t2i?format=512', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${import.meta.env.VITE_WEYL_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ prompt }),
      }).then((r) => r.blob())
    )
  )

  return results.map((blob) => URL.createObjectURL(blob))
}
```

### Pattern 2: Progressive Enhancement

```
// Start with low-res preview
const previewUrl = await generateImage(prompt, { format: 512, model: 'schnell' })
setPreview(previewUrl)

// Then generate high-res in background
const fullResUrl = await generateImage(prompt, { format: 2048, model: 'dev2' })
setFullRes(fullResUrl)
```

### Pattern 3: Prompt Templates

```
const TEMPLATES = {
  hero: 'cinematic landscape, professional photography, high quality',
  product: 'product shot, studio lighting, white background, commercial',
  avatar: 'portrait, professional headshot, neutral background, detailed',
  abstract: 'abstract art, modern design, vibrant colors, geometric',
}

function generateFromTemplate(template: keyof typeof TEMPLATES, subject: string) {
  const prompt = `${subject}, ${TEMPLATES[template]}`
  return generateImage(prompt)
}
```

## Example Bolt Prompts

### For Landing Pages

```
Create a SaaS landing page with AI image generation demo.

Hero section:
- Generated background image
- "Regenerate" button
- Headline and CTA

Features section:
- 3 feature cards with icons
- Each feature shows example generated image

Demo section:
- Live generation interface
- Try it yourself

Footer:
- Links and social

Use Weyl API for all image generation
Tailwind CSS for styling
Responsive design
```

### For Apps

```
Build a complete image generation app.

Pages:
- Home: Featured generations
- Generate: Creation interface
- Gallery: All images in grid
- About: How it works

Features:
- Model selector (FLUX schnell/dev/dev2)
- Size options (512/1024/2048)
- Prompt suggestions
- Download images
- Share links

Tech:
- React + Vite + Tailwind
- Weyl API integration
- Local storage for history
- Responsive design
```

### For Tools

```
Create a professional tool for generating marketing images.

Features:
- Template categories (Social, Email, Ads)
- Size presets by platform
- Batch generation
- Text overlay editor
- Export in multiple formats
- Brand color suggestions

Integration:
- Weyl FLUX dev for quality
- Canvas API for overlays
- FileSaver.js for downloads
```

## Troubleshooting

### Issue: CORS errors

**Solution 1**: Use a backend proxy (recommended for production)

```
// Frontend calls your backend
fetch('/api/generate', { ... })

// Backend calls Weyl
fetch('https://sync.render.weyl.ai/...', { ... })
```

**Solution 2**: For prototypes, Weyl's sync endpoint supports CORS from localhost

### Issue: API key exposed in frontend

**Solution**: Tell Bolt to create a backend:

```
Create an Express server that proxies Weyl API calls.
Move WEYL_API_KEY to backend only.
Frontend calls /api/generate instead.
```

### Issue: Images not displaying

**Solution**: Check the response format:

```
// For blob URLs
const blob = await response.blob()
const url = URL.createObjectURL(blob)

// For CDN URLs
const url = response.headers.get('Content-Location')

// Use whichever works for your use case
```

### Issue: Slow generation blocking UI

**Solution**: Add loading states and optimistic UI:

```
// Show placeholder immediately
setImages([{ id: Date.now(), loading: true }, ...images])

// Generate in background
const url = await generateImage(prompt)

// Replace placeholder
setImages(images.map(img => 
  img.loading ? { id: img.id, url } : img
))
```

## Model Selection

Tell Bolt which model based on your needs:

```
Use FLUX schnell for instant previews
Use FLUX dev for final quality images
Use FLUX dev2 for marketing hero images
Use Z-Image turbo for ultra-fast placeholders
```

## Video Generation

For video, use similar pattern:

```
Add video generation feature using Weyl.

Features:
- Upload image or provide URL
- Motion prompt input
- Generate video button
- Video player for result
- Download video

API:
- POST https://sync.render.weyl.ai/video/wan/default/i2v?format=720p
- Body: { prompt: "motion description", image: "url" }
```

Bolt will create:

```
async function generateVideo(imageUrl: string, motionPrompt: string) {
  const response = await fetch(
    'https://sync.render.weyl.ai/video/wan/default/i2v?format=720p',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${import.meta.env.VITE_WEYL_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        prompt: motionPrompt,
        image: imageUrl,
      }),
    }
  )

  const videoBlob = await response.blob()
  return URL.createObjectURL(videoBlob)
}
```

## Best Practices

### 1. Error Boundaries

```
Add error handling for:
- Network failures
- API errors
- Invalid prompts
Show user-friendly error messages
```

### 2. Loading States

```
Add loading indicators:
- Skeleton loaders
- Progress text
- Animated spinners
Disable buttons during generation
```

### 3. Responsive Design

```
Make fully responsive:
- Mobile: single column
- Tablet: 2 columns
- Desktop: 3-4 columns
Touch-friendly buttons
```

### 4. Performance

```
Optimize performance:
- Lazy load images
- Use WebP format
- Implement virtual scrolling for large galleries
- Cache generated images
```

## Deployment

Bolt apps can be deployed to:
- Vercel (recommended)
- Netlify
- Railway
- Render

Ensure environment variables are set in deployment platform.

## Complete Example App

Here's a full Bolt prompt for a production-ready app:

```
Create "QuickGen" - a modern AI image generation tool.

Pages:
1. Home
   - Hero with live generation demo
   - Features showcase
   - Call to action

2. Studio
   - Main generation interface
   - Prompt input with autocomplete
   - Model selector (FLUX schnell/dev/dev2)
   - Size selector (512/1024/2048)
   - Advanced options (guidance, steps)
   - Generation history sidebar
   - Preview area with zoom
   - Download and share buttons

3. Gallery
   - Masonry grid of generations
   - Filter by model
   - Search prompts
   - Sort by date
   - Infinite scroll

4. Settings
   - API key input
   - Default preferences
   - Usage statistics

Tech Stack:
- React 18 + TypeScript
- Vite
- Tailwind CSS + shadcn/ui components
- React Router for navigation
- Zustand for state management
- React Query for API calls
- Lucide icons

Backend:
- Express server
- CORS configured
- Rate limiting
- Error handling
- Weyl API integration

Features:
- Prompt suggestions
- Keyboard shortcuts
- Dark mode
- Mobile responsive
- PWA capabilities
- Local storage for history
- Copy CDN URLs
- Batch downloads

Environment:
- WEYL_API_KEY (backend)
- VITE_API_URL (frontend)

Make it production-ready with proper error handling, loading states, and beautiful UI.
```

Bolt will generate a complete, deployable application!

## Next Steps

- [API Reference](/api/) - Complete Weyl API documentation
- [Model Guide](/api/models/) - Model comparison and selection
- [Cursor Guide](/workflows/cursor/) - Cursor IDE integration
- [Claude Guide](/workflows/claude/) - Claude Projects workflows
- [v0 Guide](/workflows/v0/) - v0.dev integration
- [Lovable Guide](/workflows/lovable/) - Lovable.dev workflows

Build fast, ship faster with Bolt and Weyl!

---

#### Claude AI Image & Video Generation

**URL**: https://weyl.ai/workflows/claude/
**Description**: Generate images and video in Claude Projects and via MCP - seamless integration with your AI workflows

Integrate Weyl's image and video generation directly into your Claude Projects workflows. Perfect for AI-assisted development with visual content generation.

## Quick Setup

### Prerequisites

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. Have Claude Pro or Claude.ai access

## Method 1: Claude Projects with Context Files

The simplest way - add Weyl integration instructions to your project.

### Step 1: Create Project Instructions

In your Claude Project, add this to your custom instructions:

```
I have access to the Weyl API for generating images and video.

API Details:
- Base URL: https://sync.render.weyl.ai
- Auth: Bearer token (in WEYL_API_KEY)
- Image endpoint: POST /image/flux/schnell/t2i?format=1024
- Video endpoint: POST /video/wan/default/i2v?format=720p

When I need images, generate code that calls the Weyl API with appropriate prompts.
Use FLUX schnell for speed, dev for quality.
Return WebP images (sync) or job IDs (async).

Example curl:
curl -X POST "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024" \
  -H "Authorization: Bearer $WEYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"your prompt here"}'
```

### Step 2: Add API Key Context

Create a `.env.example` file in your project:

```
# .env.example
WEYL_API_KEY=your_api_key_here
```

Add this to project knowledge, then tell Claude:
"I have WEYL_API_KEY set in my environment."

### Step 3: Ask Claude to Generate Images

Now you can simply say:

> "Generate a hero image for a tech startup landing page"

Claude will respond with code like:

```
async function generateHeroImage() {
  const response = await fetch(
    "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt: "modern tech startup office, bright natural lighting, professional"
      }),
    }
  );

  const imageBuffer = await response.arrayBuffer();
  return Buffer.from(imageBuffer);
}
```

## Method 2: MCP Server (Model Context Protocol)

For advanced users - create a Weyl MCP server for native Claude integration.

### Create Weyl MCP Server

```
// weyl-mcp-server.ts

  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const WEYL_API_KEY = process.env.WEYL_API_KEY;

const server = new Server(
  {
    name: "weyl-image-generator",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Register tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "generate_image",
        description: "Generate an image using Weyl's FLUX models",
        inputSchema: {
          type: "object",
          properties: {
            prompt: {
              type: "string",
              description: "Text description of the image to generate",
            },
            model: {
              type: "string",
              enum: ["schnell", "dev", "dev2"],
              description: "Model to use (schnell=fast, dev=balanced, dev2=best quality)",
              default: "schnell",
            },
            format: {
              type: "number",
              enum: [512, 1024, 2048],
              description: "Output image size",
              default: 1024,
            },
          },
          required: ["prompt"],
        },
      },
      {
        name: "generate_video",
        description: "Generate a video from an image using Weyl's WAN model",
        inputSchema: {
          type: "object",
          properties: {
            prompt: {
              type: "string",
              description: "Text description of the motion/animation",
            },
            image_url: {
              type: "string",
              description: "URL of the starting image",
            },
          },
          required: ["prompt", "image_url"],
        },
      },
    ],
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "generate_image") {
    const { prompt, model = "schnell", format = 1024 } = args;

    const response = await fetch(
      `https://sync.render.weyl.ai/image/flux/${model}/t2i?format=${format}`,
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${WEYL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
      }
    );

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`);
    }

    // Get CDN URL from response headers
    const cdnUrl = response.headers.get("Content-Location");

    return {
      content: [
        {
          type: "text",
          text: `Image generated successfully!\nCDN URL: ${cdnUrl}\nPrompt: ${prompt}`,
        },
        {
          type: "image",
          data: await response.arrayBuffer(),
          mimeType: "image/webp",
        },
      ],
    };
  }

  if (name === "generate_video") {
    const { prompt, image_url } = args;

    const response = await fetch(
      "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p",
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${WEYL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt, image: image_url }),
      }
    );

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`);
    }

    const cdnUrl = response.headers.get("Content-Location");

    return {
      content: [
        {
          type: "text",
          text: `Video generated successfully!\nCDN URL: ${cdnUrl}\nPrompt: ${prompt}`,
        },
      ],
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
```

### Install MCP Server

```
npm install @modelcontextprotocol/sdk
```

### Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```
{
  "mcpServers": {
    "weyl": {
      "command": "node",
      "args": ["/path/to/your/weyl-mcp-server.js"],
      "env": {
        "WEYL_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Using MCP Tools in Claude

After setup, you can simply ask:

> "Generate an image of a cyberpunk street scene"

Claude will use the `generate_image` tool automatically and show you the result!

## Method 3: Direct API Integration in Code

When Claude is helping you build an app, guide it to use Weyl:

### Example Conversation

**You**: "Create an API route that generates product images using Weyl"

**Claude**: Here's a Next.js API route:

```
// app/api/generate-product/route.ts

  const { productName, style } = await request.json();

  const prompt = `${productName}, ${style} style, product photography, studio lighting, white background`;

  try {
    const response = await fetch(
      "https://sync.render.weyl.ai/image/flux/dev/t2i?format=1024",
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
      }
    );

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`);
    }

    const imageBuffer = await response.arrayBuffer();
    const cdnUrl = response.headers.get("Content-Location");

    return NextResponse.json({
      success: true,
      cdnUrl,
      localUrl: `/api/images/${productName}.webp`,
    });
  } catch (error) {
    return NextResponse.json(
      { error: "Generation failed" },
      { status: 500 }
    );
  }
}
```

## Common Use Cases

### 1. Content Generation Assistant

Create a Claude Project that generates blog post images:

**Project Instructions**:
```
When the user asks for blog post images:
1. Analyze the blog post title/content
2. Generate 3 different image concepts
3. Use Weyl API to create images
4. Return CDN URLs for each

Use flux/dev for quality.
Style: clean, professional, blog-appropriate
```

**Usage**:
> "Create header images for my post about AI productivity"

### 2. UI Mockup Generator

**You**: "Generate placeholder images for this component"

**Claude** (with context):
```
async function generatePlaceholders() {
  const images = await Promise.all([
    fetch("https://sync.render.weyl.ai/image/flux/schnell/t2i?format=512", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt: "user avatar, professional portrait, neutral background"
      }),
    }),
    fetch("https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt: "abstract gradient background, modern UI design"
      }),
    }),
  ]);

  return images;
}
```

### 3. Video Thumbnail Generator

Generate video thumbnails from existing images:

```
async function generateVideoThumbnail(imageUrl: string) {
  const response = await fetch(
    "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        prompt: "subtle zoom in, cinematic feel",
        image: imageUrl,
      }),
    }
  );

  return response;
}
```

## Claude Projects Best Practices

### 1. Add Weyl Helper to Project Knowledge

Create `lib/weyl-helper.md`:

```
# Weyl Image Generation Helper

Always use this pattern when generating images:

\`\`\`typescript
async function generateImage(prompt: string): Promise<Buffer> {
  const response = await fetch(
    "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ prompt }),
    }
  );

  if (!response.ok) throw new Error(`Error: ${response.status}`);
  
  const arrayBuffer = await response.arrayBuffer();
  return Buffer.from(arrayBuffer);
}
\`\`\`

Models:
- schnell: Fast (4 steps)
- dev: Balanced
- dev2: Best quality
```

### 2. Create Reusable Prompts

Add common prompt templates to project:

```
const PROMPT_TEMPLATES = {
  hero: (theme: string) => 
    `${theme} themed hero image, professional, high quality, modern design`,
  product: (item: string) => 
    `${item} product shot, studio lighting, white background, professional`,
  abstract: (mood: string) => 
    `abstract ${mood} background, gradients, modern, UI-friendly`,
  portrait: (description: string) => 
    `professional portrait, ${description}, natural lighting, neutral background`,
};
```

### 3. Error Handling Template

```
async function safeGenerate(prompt: string): Promise<Buffer | null> {
  try {
    return await generateImage(prompt);
  } catch (error) {
    if (error.status === 503) {
      console.log("Capacity full, retrying...");
      await new Promise(resolve => setTimeout(resolve, 2000));
      return safeGenerate(prompt); // Retry once
    }
    console.error("Generation failed:", error);
    return null;
  }
}
```

## Troubleshooting

### Issue: Claude doesn't know about Weyl

**Solution**: Add Weyl documentation to project knowledge. Include this guide or create a condensed version.

### Issue: API key not working

**Solution**: 
1. Verify key in `.env` file
2. Ensure Claude knows to use `process.env.WEYL_API_KEY`
3. Restart your development server

### Issue: MCP server not connecting

**Solution**:
1. Check `claude_desktop_config.json` path is correct
2. Verify Node.js path: `which node`
3. Check server logs in Claude Desktop → Settings → Developer
4. Ensure WEYL_API_KEY is in env config

### Issue: Generation timing out

**Solution**: Use async tier for longer generations:

```
// Switch to async endpoint
const response = await fetch(
  "https://async.render.weyl.ai/image/flux/dev2/t2i?format=2048",
  // ... same auth and body
);

const { job_id } = await response.json();

// Poll for result
const result = await fetch(
  `https://async.render.weyl.ai/jobs/${job_id}`,
  {
    headers: { "Authorization": `Bearer ${process.env.WEYL_API_KEY}` }
  }
);
```

## Advanced: Artifact Generation

When Claude generates artifacts (React components, HTML), include image generation:

**Example Prompt**:
> "Create a landing page component that generates custom hero images on mount using Weyl"

**Claude's Response**:
```
"use client";

  const [heroUrl, setHeroUrl] = useState<string>("");

  useEffect(() => {
    async function generateHero() {
      const res = await fetch("/api/generate-hero", {
        method: "POST",
        body: JSON.stringify({ 
          prompt: "futuristic tech landscape, cinematic" 
        }),
      });
      
      const { cdnUrl } = await res.json();
      setHeroUrl(cdnUrl);
    }

    generateHero();
  }, []);

  return (
    <div className="relative h-screen">
      {heroUrl && (
        <img
          src={heroUrl}
          alt="Dynamic hero"
          className="absolute inset-0 w-full h-full object-cover"
        />
      )}
      <div className="relative z-10">
        <h1>Welcome</h1>
      </div>
    </div>
  );
}
```

## Next Steps

- [API Reference](/api/) - Complete Weyl API docs
- [Model Guide](/api/models/) - Choose the right model
- [Cursor Guide](/workflows/cursor/) - Cursor-specific workflows
- [Other Tools](/workflows/) - v0, Lovable, Bolt guides

## Example Project Structure

```
my-project/
├── .env                          # WEYL_API_KEY here
├── lib/
│   ├── weyl.ts                   # Weyl client helper
│   └── prompts.ts                # Prompt templates
├── app/
│   └── api/
│       └── generate/
│           └── route.ts          # Image generation endpoint
└── docs/
    └── weyl-integration.md       # Add to Claude Project knowledge
```

Now Claude can help you build apps with AI-generated images seamlessly!

---

#### Cursor AI Image & Video Generation

**URL**: https://weyl.ai/workflows/cursor/
**Description**: Generate images and video directly in Cursor IDE with Weyl's API - perfect for vibe coding workflows

Generate images and video directly in Cursor IDE using Weyl's API. Perfect for building visual apps, prototyping UIs, and adding media generation to your projects.

## Quick Setup

### Prerequisites

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. Have Cursor IDE installed

### Environment Setup

Add your API key to your project's `.env` file:

```
# .env
WEYL_API_KEY=your_api_key_here
```

## Method 1: Direct API Calls (Fastest)

### Node.js / TypeScript

Perfect for backend routes, server actions, or build-time generation.

```
// generate-image.ts
async function generateImage(prompt: string): Promise<Buffer> {
  const response = await fetch(
    "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ prompt }),
    }
  );

  if (!response.ok) {
    throw new Error(`Generation failed: ${response.status}`);
  }

  const arrayBuffer = await response.arrayBuffer();
  return Buffer.from(arrayBuffer);
}

// Usage
const imageData = await generateImage("cyberpunk city at night, neon lights");
// Save or send the image
await fs.writeFile("output.webp", imageData);
```

### Python

Great for scripts, FastAPI backends, or data processing pipelines.

```
# generate_image.py

def generate_image(prompt: str) -> bytes:
    """Generate an image using Weyl API"""
    response = requests.post(
        "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
        headers={
            "Authorization": f"Bearer {os.getenv('WEYL_API_KEY')}",
            "Content-Type": "application/json",
        },
        json={"prompt": prompt},
    )
    
    response.raise_for_status()
    return response.content

# Usage
image_data = generate_image("portrait, natural lighting, professional")
with open("output.webp", "wb") as f:
    f.write(image_data)
```

## Method 2: With Cursor Composer

Use Cursor's Composer to generate code that includes Weyl API calls.

### Example Prompt for Cursor

```
Create a Next.js API route that generates hero images using Weyl API.
Use the FLUX schnell model for speed.
Environment variable: WEYL_API_KEY
Endpoint: POST /api/generate-hero
Accept: { prompt: string }
Return: The generated image as a blob
```

Cursor will generate something like:

```
// app/api/generate-hero/route.ts

  const { prompt } = await request.json();

  if (!prompt) {
    return NextResponse.json(
      { error: "Prompt is required" },
      { status: 400 }
    );
  }

  try {
    const response = await fetch(
      "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
      }
    );

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    const imageBuffer = await response.arrayBuffer();
    
    return new NextResponse(imageBuffer, {
      headers: {
        "Content-Type": "image/webp",
        "Cache-Control": "public, max-age=31536000, immutable",
      },
    });
  } catch (error) {
    console.error("Generation error:", error);
    return NextResponse.json(
      { error: "Failed to generate image" },
      { status: 500 }
    );
  }
}
```

## Video Generation

Generate video from images for dynamic content.

```
async function generateVideo(
  prompt: string,
  imageUrl: string
): Promise<Buffer> {
  const response = await fetch(
    "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt,
        image: imageUrl,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Generation failed: ${response.status}`);
  }

  const arrayBuffer = await response.arrayBuffer();
  return Buffer.from(arrayBuffer);
}

// Usage
const video = await generateVideo(
  "camera pans across the landscape",
  "https://cdn.render.weyl.ai/your-image.webp"
);
```

## Common Use Cases

### 1. Hero Image Generator

```
// lib/hero-generator.ts

  theme: "tech" | "nature" | "abstract"
): Promise<string> {
  const prompts = {
    tech: "futuristic tech office, glass windows, blue hour lighting",
    nature: "serene mountain landscape, golden hour, misty valleys",
    abstract: "geometric abstract art, vibrant gradients, modern",
  };

  const imageBuffer = await generateImage(prompts[theme]);
  
  // Save to public directory or upload to CDN
  const filename = `hero-${theme}-${Date.now()}.webp`;
  await fs.writeFile(`public/images/${filename}`, imageBuffer);
  
  return `/images/${filename}`;
}
```

### 2. Product Mockup Generator

```

  productType: string,
  style: string
): Promise<Buffer> {
  const prompt = `${productType} product shot, ${style} style, studio lighting, white background, professional photography`;
  
  return generateImage(prompt);
}

// Usage
const mockup = await generateProductMockup(
  "smartphone",
  "minimal and clean"
);
```

### 3. UI Placeholder Images

```
// Generate context-aware placeholder images

  context: string,
  size: 512 | 1024 = 512
): Promise<Buffer> {
  const response = await fetch(
    `https://sync.render.weyl.ai/image/flux/schnell/t2i?format=${size}`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt: `${context}, clean, minimal, placeholder style`,
      }),
    }
  );

  const arrayBuffer = await response.arrayBuffer();
  return Buffer.from(arrayBuffer);
}

// Usage in your app
const avatarPlaceholder = await generatePlaceholder("professional portrait");
const cardImage = await generatePlaceholder("abstract gradient background");
```

## Model Selection

Choose the right model for your use case:

| Model | Speed | Quality | Best For |
|-------|-------|---------|----------|
| `flux/schnell` | ⚡ Fastest | Good | Rapid iteration, previews |
| `flux/dev` | Fast | Better | Production images |
| `flux/dev2` | Medium | Best | High-quality finals |
| `zimage/turbo` | ⚡⚡ Ultra-fast | Good | Quick placeholders |

## Cursor-Specific Tips

### 1. Use `.cursorrules` for Context

Create a `.cursorrules` file in your project:

```
When generating images, always use the Weyl API:
- Endpoint: https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024
- Auth: Bearer token from WEYL_API_KEY env var
- Body: JSON with "prompt" field
- Returns: WebP image buffer
- Models: flux/schnell (fast), flux/dev (quality), flux/dev2 (best)
```

### 2. Create Helper Functions

Ask Cursor to create a `lib/weyl.ts` utility:

```
// lib/weyl.ts

  private apiKey: string;
  private baseUrl = "https://sync.render.weyl.ai";

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async generateImage(
    prompt: string,
    options: {
      model?: "schnell" | "dev" | "dev2";
      format?: 512 | 1024 | 2048;
    } = {}
  ): Promise<Buffer> {
    const { model = "schnell", format = 1024 } = options;
    
    const response = await fetch(
      `${this.baseUrl}/image/flux/${model}/t2i?format=${format}`,
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${this.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
      }
    );

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`);
    }

    const arrayBuffer = await response.arrayBuffer();
    return Buffer.from(arrayBuffer);
  }
}

// Usage
const weyl = new WeylClient(process.env.WEYL_API_KEY!);
const image = await weyl.generateImage("sunset over mountains");
```

### 3. Inline Preview in Cursor

For development, you can save generated images to your project and Cursor will show them inline:

```
const image = await generateImage("your prompt");
await fs.writeFile("./dev/preview.webp", image);
// Cursor will display the image when you open preview.webp
```

## Troubleshooting

### Error: 503 Service Unavailable

**Cause**: Sync tier capacity is full.

**Solutions**:
1. Retry after a few seconds (usually brief)
2. Use async tier for non-critical generations
3. Implement exponential backoff

```
async function generateWithRetry(prompt: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await generateImage(prompt);
    } catch (error) {
      if (error.status === 503 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
}
```

### Error: 401 Unauthorized

**Cause**: Invalid or missing API key.

**Solutions**:
1. Check `.env` file has correct `WEYL_API_KEY`
2. Restart your dev server to pick up env changes
3. Verify your API key in the email you received

### Slow Generation Times

**Cause**: Using high-quality models or large formats.

**Solutions**:
1. Use `flux/schnell` for faster results (4 steps vs 20+)
2. Use smaller formats during development (512 vs 1024)
3. Switch to async tier for batch operations

## Advanced: Streaming with WebSockets

For real-time progress updates in your UI:

```
const ws = new WebSocket(
  `wss://sync.render.weyl.ai/ws?token=${process.env.WEYL_API_KEY}`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "generate",
    model: "flux/schnell",
    prompt: "your prompt here",
  }));
});

ws.on("message", (data) => {
  const message = JSON.parse(data);
  
  if (message.type === "progress") {
    console.log(`Progress: ${message.percent}%`);
  }
  
  if (message.type === "complete") {
    console.log(`Image URL: ${message.url}`);
    ws.close();
  }
});
```

## Next Steps

- [API Reference](/api/) - Complete API documentation
- [Model Guide](/api/models/) - Detailed model comparison
- [WebSocket Protocol](/api/websocket/) - Real-time streaming
- [Other AI Tools](/workflows/) - Claude, v0, Lovable, Bolt guides

---

#### Lovable AI Image & Video Generation

**URL**: https://weyl.ai/workflows/lovable/
**Description**: Integrate Weyl image and video generation into Lovable.dev full-stack apps - build visual apps with AI

Build full-stack apps with AI-generated images and video using Lovable.dev and Weyl. Perfect for rapid prototyping with visual content.

## Quick Setup

### Prerequisites

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. Access to Lovable.dev

## Method 1: Direct Integration Prompt

Tell Lovable to integrate Weyl from the start.

### Example Lovable Prompt

```
Create a landing page with dynamic hero image generation using Weyl API.

Requirements:
- Hero section with image generation
- API integration for https://sync.render.weyl.ai
- Use WEYL_API_KEY from environment
- FLUX schnell model for speed
- Button to regenerate hero
- Loading states and error handling
- Store API key securely
```

### What Lovable Will Generate

Lovable creates a full-stack app with:
- Frontend component with image display
- Backend API route for Weyl integration
- Environment variable configuration
- Database schema (if needed for caching)
- Authentication (if required)

## Method 2: Add to Existing Lovable App

If you already have a Lovable app, add image generation:

### Prompt

```
Add image generation feature to my app using Weyl API.

Features needed:
- New page at /generate
- Text input for prompts
- Generate button
- Display generated images in gallery
- Save images to database
- API route for Weyl at /api/generate-image
- Use WEYL_API_KEY from environment variables
```

### Generated Code

Lovable will create:

```
// Backend API route

serve(async (req) => {
  if (req.method === "POST" && new URL(req.url).pathname === "/api/generate-image") {
    try {
      const { prompt } = await req.json()
      
      const response = await fetch(
        "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${Deno.env.get("WEYL_API_KEY")}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ prompt }),
        }
      )

      if (!response.ok) {
        return new Response(
          JSON.stringify({ error: "Generation failed" }),
          { status: response.status }
        )
      }

      const imageBuffer = await response.arrayBuffer()
      const cdnUrl = response.headers.get("Content-Location")

      return new Response(
        JSON.stringify({ url: cdnUrl, success: true }),
        { headers: { "Content-Type": "application/json" } }
      )
    } catch (error) {
      return new Response(
        JSON.stringify({ error: error.message }),
        { status: 500 }
      )
    }
  }

  return new Response("Not Found", { status: 404 })
})
```

```
// Frontend component

  const [prompt, setPrompt] = useState("")
  const [imageUrl, setImageUrl] = useState("")
  const [loading, setLoading] = useState(false)
  const { toast } = useToast()

  async function handleGenerate() {
    if (!prompt.trim()) {
      toast({
        title: "Error",
        description: "Please enter a prompt",
        variant: "destructive",
      })
      return
    }

    setLoading(true)
    try {
      const response = await fetch("/api/generate-image", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ prompt }),
      })

      if (!response.ok) throw new Error("Generation failed")

      const data = await response.json()
      setImageUrl(data.url)
      
      toast({
        title: "Success",
        description: "Image generated successfully!",
      })
    } catch (error) {
      toast({
        title: "Error",
        description: "Failed to generate image",
        variant: "destructive",
      })
    } finally {
      setLoading(false)
    }
  }

  return (
    <div className="container mx-auto max-w-2xl p-8">
      <h1 className="mb-8 text-4xl font-bold">AI Image Generator</h1>
      
      <div className="space-y-4">
        

        {imageUrl && (
          <div className="mt-8 overflow-hidden rounded-lg">
            <img
              src={imageUrl}
              alt="Generated"
              className="w-full"
            />
          </div>
        )}
      </div>
    </div>
  )
}
```

## Method 3: Full App with Database

For apps that save generated images:

### Lovable Prompt

```
Create a full-stack image generation app with Weyl API.

Features:
- User authentication with Supabase
- Image generation with Weyl (FLUX models)
- Save generated images to database
- Gallery page showing all user images
- Download functionality
- Share generated images
- Admin panel to view all generations

Tech stack:
- React frontend
- Supabase backend
- Weyl API for image generation
- Tailwind CSS styling
```

### Database Schema

Lovable will create:

```
-- Supabase schema
create table public.generated_images (
  id uuid default gen_random_uuid() primary key,
  user_id uuid references auth.users not null,
  prompt text not null,
  image_url text not null,
  model text not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null
);

-- Enable RLS
alter table public.generated_images enable row level security;

-- Policies
create policy "Users can view own images"
  on public.generated_images for select
  using (auth.uid() = user_id);

create policy "Users can insert own images"
  on public.generated_images for insert
  with check (auth.uid() = user_id);
```

## Common Use Cases

### 1. Content Creation Platform

```
Build a content creation platform where:
- Users create projects
- Each project can generate images
- Images saved to project gallery
- Export projects with images
- Uses Weyl for generation
- Supabase for data storage
```

### 2. Social Media Mockup Generator

```
Create a social media mockup generator:
- Generate images for posts
- Add text overlays
- Multiple format options (square, portrait, landscape)
- Download in different sizes
- Share generated mockups
- Use Weyl FLUX for generation
```

### 3. E-commerce Product Generator

```
Build a product image generator for e-commerce:
- Product description input
- Style selection (minimal, luxury, lifestyle)
- Background options
- Multiple angle generation
- Batch generate variations
- Save to product catalog
- Weyl API integration
```

### 4. Avatar Creation App

```
Create an avatar generator app:
- Style picker (realistic, artistic, cartoon)
- Customization options
- Generate with Weyl FLUX
- Save favorite avatars
- Download or use as profile pic
- User accounts with Supabase
```

## Lovable-Specific Patterns

### Pattern 1: Environment Variables

Lovable uses Deno. Set env vars in project settings:

```
// Access in backend
const apiKey = Deno.env.get("WEYL_API_KEY")

// Or use .env file

const env = await load()
const apiKey = env.WEYL_API_KEY
```

### Pattern 2: File Upload for Video

When generating video from images:

```
// Backend route for video generation
async function generateVideo(imageUrl: string, prompt: string) {
  const response = await fetch(
    "https://sync.render.weyl.ai/video/wan/default/i2v?format=720p",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${Deno.env.get("WEYL_API_KEY")}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ 
        prompt,
        image: imageUrl 
      }),
    }
  )

  const videoBuffer = await response.arrayBuffer()
  const cdnUrl = response.headers.get("Content-Location")
  
  return { url: cdnUrl }
}
```

### Pattern 3: Caching Generated Images

```
// Cache images in Supabase storage

const supabase = createClient(
  Deno.env.get("SUPABASE_URL")!,
  Deno.env.get("SUPABASE_KEY")!
)

async function cacheImage(imageBuffer: ArrayBuffer, filename: string) {
  const { data, error } = await supabase.storage
    .from("generated-images")
    .upload(filename, imageBuffer, {
      contentType: "image/webp",
      cacheControl: "31536000",
    })

  if (error) throw error

  const { data: { publicUrl } } = supabase.storage
    .from("generated-images")
    .getPublicUrl(filename)

  return publicUrl
}
```

## Advanced Integration

### Real-Time Generation Updates

Use Supabase Realtime for live updates:

```
// Backend: Save generation status
await supabase
  .from("generations")
  .insert({
    id: generationId,
    user_id: userId,
    status: "generating",
    prompt: prompt,
  })

// Generate image
const imageUrl = await generateWithWeyl(prompt)

// Update status
await supabase
  .from("generations")
  .update({ status: "complete", image_url: imageUrl })
  .eq("id", generationId)
```

```
// Frontend: Subscribe to updates
useEffect(() => {
  const channel = supabase
    .channel("generations")
    .on(
      "postgres_changes",
      {
        event: "UPDATE",
        schema: "public",
        table: "generations",
        filter: `user_id=eq.${userId}`,
      },
      (payload) => {
        if (payload.new.status === "complete") {
          setImageUrl(payload.new.image_url)
          setLoading(false)
        }
      }
    )
    .subscribe()

  return () => {
    supabase.removeChannel(channel)
  }
}, [userId])
```

### Batch Generation Queue

```
// Queue multiple generations
async function queueBatchGeneration(prompts: string[], userId: string) {
  // Insert all jobs
  const jobs = prompts.map((prompt) => ({
    user_id: userId,
    prompt,
    status: "queued",
  }))

  await supabase.from("generation_queue").insert(jobs)

  // Process queue (in background worker)
  for (const job of jobs) {
    const imageUrl = await generateWithWeyl(job.prompt)
    
    await supabase
      .from("generation_queue")
      .update({ status: "complete", image_url: imageUrl })
      .eq("id", job.id)
  }
}
```

## Example Lovable Prompts

### For SaaS App

```
Create a SaaS app for AI image generation with:
- Landing page with demo
- User authentication
- Credit system (100 credits free)
- Image generation interface
- Gallery of generated images
- Pricing page
- Admin dashboard
- Uses Weyl API for generation
- Supabase for backend
- Stripe for payments
```

### For Portfolio Site

```
Build a portfolio site that:
- Showcases AI-generated artwork
- Each piece generated via Weyl
- Click to view generation prompt
- Regenerate variations
- Download options
- Share on social media
- Contact form
```

### For Marketing Tool

```
Create a marketing image generator:
- Campaign name input
- Generate hero images
- Generate social media variants
- A/B test different versions
- Analytics on performance
- Export all assets
- Team collaboration
- Weyl API integration
```

## Troubleshooting

### Issue: Environment variables not loading

**Solution**: Set in Lovable project settings:
1. Go to Project Settings
2. Add `WEYL_API_KEY` under Environment Variables
3. Redeploy the app

### Issue: CORS errors

**Solution**: Use backend API routes, not direct browser calls:

```
// Bad: Direct from frontend
const response = await fetch("https://sync.render.weyl.ai/...", {...})

// Good: Through your API route
const response = await fetch("/api/generate-image", {...})
```

### Issue: Large image files

**Solution**: Use Supabase Storage:

```
// Store in Supabase instead of inline
const { data } = await supabase.storage
  .from("images")
  .upload(`${userId}/${Date.now()}.webp`, imageBuffer)
```

### Issue: Slow generation blocking UI

**Solution**: Use async processing:

```
// Return immediately
const jobId = crypto.randomUUID()

// Process in background
processGeneration(jobId, prompt)

return Response.json({ jobId, status: "processing" })

// Frontend polls for status
async function pollStatus(jobId: string) {
  const { data } = await supabase
    .from("generations")
    .select("status, image_url")
    .eq("id", jobId)
    .single()

  return data
}
```

## Best Practices

### 1. Rate Limiting

```
// Add rate limiting per user
async function checkRateLimit(userId: string) {
  const { count } = await supabase
    .from("generated_images")
    .select("*", { count: "exact", head: true })
    .eq("user_id", userId)
    .gte("created_at", new Date(Date.now() - 3600000).toISOString())

  if (count >= 10) {
    throw new Error("Rate limit exceeded")
  }
}
```

### 2. Cost Tracking

```
// Track generation costs
await supabase.from("usage_tracking").insert({
  user_id: userId,
  action: "image_generation",
  model: "flux/schnell",
  cost_credits: 1,
  timestamp: new Date().toISOString(),
})
```

### 3. Error Recovery

```
async function generateWithRetry(prompt: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await generateImage(prompt)
    } catch (error) {
      if (i === maxRetries - 1) throw error
      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)))
    }
  }
}
```

## Model Selection

Tell Lovable which model to use:

```
Use FLUX schnell for quick previews
Use FLUX dev for production images
Use FLUX dev2 for hero images and marketing
Use Z-Image turbo for ultra-fast placeholders
```

## Deployment

Lovable handles deployment automatically. Just ensure:

1. Environment variables are set in project settings
2. Supabase database is configured
3. Storage bucket has proper permissions
4. RLS policies are enabled

## Next Steps

- [API Reference](/api/) - Complete Weyl API docs
- [Model Guide](/api/models/) - Choose the right model
- [Authentication](/getting-started/auth/) - API key setup
- [Other Tools](/workflows/) - Cursor, Claude, v0, Bolt guides

## Example: Complete Image Gen App

Here's a full prompt for Lovable to create a complete app:

```
Create a complete AI image generation SaaS called "ImageForge".

Features:
1. Landing Page
   - Hero with demo generation
   - Feature showcase
   - Pricing tiers

2. Authentication
   - Supabase Auth
   - Email/password and OAuth

3. Dashboard
   - Recent generations
   - Usage statistics
   - Credit balance

4. Generator Page
   - Prompt input with suggestions
   - Model selector (FLUX schnell/dev/dev2)
   - Size selector (512/1024/2048)
   - Generate button with loading state
   - Result display with download
   - Save to gallery option

5. Gallery Page
   - Grid of all user images
   - Filter by model, date
   - Search prompts
   - Bulk download
   - Delete images

6. Settings
   - API key management
   - Billing info
   - Usage limits

7. Backend
   - Weyl API integration
   - Credit system
   - Rate limiting
   - Usage tracking
   - Admin endpoints

Tech Stack:
- React + TypeScript
- Tailwind CSS
- Supabase (auth, database, storage)
- Weyl API for generation
- Lucide icons

Environment variables needed:
- WEYL_API_KEY
- SUPABASE_URL
- SUPABASE_ANON_KEY
```

Lovable will generate a complete, production-ready app!

---

#### v0 AI Image & Video Generation

**URL**: https://weyl.ai/workflows/v0/
**Description**: Generate images and video in v0.dev components - add dynamic visuals to your AI-generated UIs

Integrate Weyl image and video generation directly into your v0.dev components. Generate dynamic hero images, product shots, and visual content right in your UI components.

## Quick Setup

### Prerequisites

1. <a href="/request-access/" target="_blank" rel="noopener noreferrer">Request access to the Weyl API</a> (free tier: 1,000 requests/month)
2. Access to v0.dev

## Method 1: Client-Side Generation (Instant Preview)

Tell v0 to create a component that generates images on the fly.

### Example v0 Prompt

```
Create a hero section component with dynamic image generation using the Weyl API.

Requirements:
- Image generates on button click
- Shows loading state
- Uses FLUX schnell model for speed
- API endpoint: https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024
- Auth via WEYL_API_KEY environment variable
- Display generated image with smooth fade-in
```

### Generated Component Example

v0 will create something like:

```
"use client"

  const [imageUrl, setImageUrl] = useState<string>("")
  const [loading, setLoading] = useState(false)

  async function generateHero() {
    setLoading(true)
    try {
      const response = await fetch("/api/generate-image", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          prompt: "modern tech startup office, bright and professional",
        }),
      })

      const data = await response.json()
      setImageUrl(data.url)
    } catch (error) {
      console.error("Failed to generate image:", error)
    } finally {
      setLoading(false)
    }
  }

  return (
    <div className="relative h-[600px] w-full overflow-hidden rounded-lg">
      {imageUrl ? (
        <img
          src={imageUrl}
          alt="Generated hero"
          className="h-full w-full object-cover transition-opacity duration-500"
        />
      ) : (
        <div className="flex h-full items-center justify-center bg-gradient-to-br from-purple-500 to-pink-500">
          
        </div>
      )}
    </div>
  )
}
```

## Method 2: API Route Pattern

Tell v0 to create the API route alongside the component.

### v0 Prompt for API Route

```
Create a Next.js API route at /api/generate-image that:
- Accepts POST with { prompt: string }
- Calls Weyl API at sync.render.weyl.ai
- Uses WEYL_API_KEY from env
- Returns { url: string } with CDN URL
- Includes error handling
```

### Generated API Route

```
// app/api/generate-image/route.ts

  try {
    const { prompt } = await request.json()

    if (!prompt) {
      return NextResponse.json(
        { error: "Prompt is required" },
        { status: 400 }
      )
    }

    const response = await fetch(
      "https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024",
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.WEYL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ prompt }),
      }
    )

    if (!response.ok) {
      throw new Error(`Weyl API error: ${response.status}`)
    }

    // Get CDN URL from header
    const cdnUrl = response.headers.get("Content-Location")

    return NextResponse.json({ 
      url: cdnUrl,
      success: true 
    })
  } catch (error) {
    console.error("Image generation failed:", error)
    return NextResponse.json(
      { error: "Failed to generate image" },
      { status: 500 }
    )
  }
}
```

## Method 3: Server Component with Static Generation

Generate images at build time for better performance.

### v0 Prompt

```
Create a product showcase component that generates product images at build time.
- Server component
- Generate 3 product variations
- Cache images in public folder
- Display in responsive grid
```

### Generated Component

```
// app/products/page.tsx

const products = [
  { name: "Laptop", style: "minimal tech, white background" },
  { name: "Headphones", style: "product shot, studio lighting" },
  { name: "Smartphone", style: "sleek design, professional" },
]

  // Generate images at build time
  const productImages = await Promise.all(
    products.map(async (product) => {
      const imageUrl = await generateProductImage(
        `${product.name}, ${product.style}`
      )
      return { ...product, imageUrl }
    })
  )

  return (
    <div className="container mx-auto px-4 py-12">
      <h1 className="mb-8 text-4xl font-bold">Our Products</h1>
      <div className="grid gap-6 md:grid-cols-3">
        {productImages.map((product) => (
          
      </div>

      <div className="grid gap-4 md:grid-cols-3">
        {images.map((url, i) => (
          <div key={i} className="group relative overflow-hidden rounded-lg">
            <img
              src={url}
              alt={`Generated ${i}`}
              className="h-64 w-full object-cover"
            />
            
          </div>
        ))}
      </div>
    </div>
  )
}
```

### 2. AI Avatar Generator

```
Create a profile avatar generator component.

Features:
- Style selection (realistic, cartoon, artistic)
- Generate button
- Display in circle crop
- Save to profile functionality
- Uses FLUX dev for quality
```

### 3. Landing Page with Dynamic Hero

```
Create a landing page with hero section that:
- Generates contextual background image on load
- Shows loading skeleton
- Includes CTA buttons overlay
- Responsive design
- Uses Weyl for image generation
```

### 4. Product Mockup Generator

```
Create a product mockup generator where users can:
- Enter product name
- Select style (minimal, luxury, tech)
- Generate mockup
- Display in card with download option
```

## v0-Specific Best Practices

### 1. Always Include Loading States

v0 loves clean loading states. Include them in your prompt:

```
Add a skeleton loader while image generates
Show shimmer effect during loading
Display progress text "Generating your image..."
```

### 2. Use Environment Variables

Tell v0 to use env vars properly:

```
Use WEYL_API_KEY from environment variables
Add .env.example with WEYL_API_KEY placeholder
Include setup instructions in README
```

### 3. Responsive Design by Default

v0 generates responsive code. Leverage it:

```
Make image generation responsive
Mobile: single column, smaller images
Desktop: grid layout, larger images
```

### 4. Integrate with shadcn/ui

v0 uses shadcn/ui. Reference it:

```
Use Button component from shadcn
Add Card wrapper for generated images
Include Dialog for full-size preview
Use Toast for error notifications
```

## Advanced Patterns

### Pattern 1: Prompt Templates

```
const PROMPT_TEMPLATES = {
  hero: (theme: string) =>
    `${theme} hero background, cinematic, professional`,
  avatar: (style: string) =>
    `portrait, ${style} style, professional headshot`,
  product: (item: string) =>
    `${item} product shot, white background, studio lighting`,
  abstract: (mood: string) =>
    `abstract ${mood} background, modern, gradient`,
}

// Usage in component
async function generateWithTemplate(
  type: keyof typeof PROMPT_TEMPLATES,
  param: string
) {
  const prompt = PROMPT_TEMPLATES[type](param)
  // ... generate image
}
```

### Pattern 2: Batch Generation

```
async function generateBatch(prompts: string[]) {
  const results = await Promise.all(
    prompts.map((prompt) =>
      fetch("/api/generate-image", {
        method: "POST",
        body: JSON.stringify({ prompt }),
      }).then((r) => r.json())
    )
  )
  return results.map((r) => r.url)
}
```

### Pattern 3: Image Carousel with Generation

Tell v0:

```
Create a carousel that:
- Shows 5 generated images
- Auto-advances every 5 seconds
- Allows manual navigation
- Generates new images in background
- Uses Weyl FLUX schnell
```

## Example v0 Prompts

### For Hero Sections

```
Create a hero section with:
- Dynamic background image generation
- Prompt: "futuristic tech landscape"
- Generated via Weyl API on component mount
- Gradient overlay for text readability
- CTA buttons
- Responsive layout
```

### For Galleries

```
Build an image gallery where:
- User enters prompts in modal
- Generates 4 variations using Weyl
- Displays in masonry grid
- Click to view full size
- Download buttons
```

### For Forms

```
Create a form that generates images:
- Style selector (artistic, photographic, minimal)
- Subject input field
- Quality toggle (fast/quality)
- Calls Weyl API with selected options
- Shows result in preview area
```

## Integration Tips

### Tip 1: Mention Weyl in Initial Prompt

Start your v0 prompt with:

```
Using the Weyl API (sync.render.weyl.ai) for image generation...
```

This sets context for the entire component.

### Tip 2: Request API Route Creation

Always ask for the API route:

```
Also create the API route at /api/generate-image that calls Weyl
```

v0 will generate both component and route.

### Tip 3: Specify Error Handling

```
Include error handling for:
- Network failures
- API errors (503, 401)
- Invalid prompts
Display errors in toast notifications
```

### Tip 4: Ask for TypeScript

```
Use TypeScript with proper types
Interface for API responses
Type-safe props
```

## Troubleshooting

### Issue: v0 doesn't know Weyl API format

**Solution**: Be specific in your prompt:

```
API endpoint: POST https://sync.render.weyl.ai/image/flux/schnell/t2i?format=1024
Headers: Authorization: Bearer {WEYL_API_KEY}, Content-Type: application/json
Body: { "prompt": "your prompt" }
Response: Binary image data, CDN URL in Content-Location header
```

### Issue: CORS errors in browser

**Solution**: Always use API routes, not direct browser calls:

```
// Bad: Direct from browser
fetch("https://sync.render.weyl.ai/...", { ... })

// Good: Through your API route
fetch("/api/generate-image", { ... })
```

### Issue: Images not caching

**Solution**: Tell v0 to add caching:

```
Cache generated images in /public/generated
Add cache-control headers
Reuse images for same prompts
```

## Model Selection for v0

Choose based on use case:

| Use Case | Model | Reason |
|----------|-------|--------|
| Quick previews | `flux/schnell` | Sub-second generation |
| UI components | `flux/dev` | Good quality/speed balance |
| Hero images | `flux/dev2` | Best quality |
| Avatars | `flux/dev` | Good for portraits |
| Backgrounds | `flux/schnell` | Speed matters more |

Specify in your v0 prompt:

```
Use FLUX schnell for fast iteration
```

or

```
Use FLUX dev2 for high-quality final images
```

## Example Project Structure

After v0 generates your components:

```
my-v0-app/
├── .env.local                    # WEYL_API_KEY here
├── app/
│   ├── api/
│   │   └── generate-image/
│   │       └── route.ts          # Generated by v0
│   └── page.tsx                  # Main component with image gen
├── components/
│   ├── ui/                       # shadcn components
│   └── image-generator.tsx       # Custom generated component
└── lib/
    └── weyl.ts                   # Optional helper functions
```

## Next Steps

- [API Reference](/api/) - Complete Weyl API documentation
- [Model Guide](/api/models/) - Choose the right model
- [Cursor Guide](/workflows/cursor/) - Cursor-specific workflows
- [Claude Guide](/workflows/claude/) - Claude Projects integration
- [Other Tools](/workflows/) - Lovable, Bolt guides

## Video Generation in v0

For video, use the same pattern:

```
Create a video generator component using Weyl:
- Upload image or use URL
- Motion prompt input
- Generate video via Weyl WAN model
- Endpoint: POST sync.render.weyl.ai/video/wan/default/i2v?format=720p
- Display video player when complete
```

v0 will create a similar component adapted for video workflows!

---

## AI Workflows

Weyl integrates natively with modern AI development tools. Each workflow enables direct image generation within your preferred development environment.

### Supported Platforms

| Platform | Integration Type | Use Case |
|----------|-----------------|----------|
| Cursor IDE | Rules + API | Vibe coding with AI images |
| Claude | MCP Server | Conversational image generation |
| v0.dev | API Integration | Component prototyping |
| Lovable | Full-stack | AI-native applications |
| Bolt.new | Rapid prototyping | Quick experiments |

## Weyl Standard

The Weyl Standard is our engineering knowledge base covering Nix, programming languages, and infrastructure best practices.

### Contributors

**URL**: https://weyl.ai/std/contributors/
**Description**: Thanks to all contributors to Weyl Standard Nix and acknowledgments to the Nix community.

# Contributors

Thanks to all contributors to Weyl Standard Nix.

## Core Team

- Weyl AI Infrastructure Team

## Acknowledgments

- The Nix community
- nixpkgs maintainers
- flake-parts authors
- Luke Arran for stylistic inspiration

---

### Weyl Standard

**URL**: https://weyl.ai/std/index/
**Description**: A collection of coding standards, patterns, and conventions for building production systems, codifying principles for high-performance computing, infrastructure, and software engineering.

# Weyl Standard

**Weyl Standard** is a collection of coding standards, patterns, and conventions for building production systems. It codifies the principles developed at Weyl AI for high-performance computing, infrastructure, and software engineering.

## Philosophy

**Optimize for disambiguation, not brevity.**

In modern codebases where agents generate significant code and humans debug at 3am:
- Every ambiguity compounds exponentially
- Code is written once, read hundreds of times
- Grep-ability matters more than cleverness
- Type safety prevents tomorrow's bugs

## Language Standards

| Language | Use Case |
|----------|----------|
| [Nix](/std/nix/) | Reproducible infrastructure and builds |
| [Python](/std/languages/python/) | GPU inference and ML orchestration |
| [C++](/std/languages/cpp/) | Extreme performance requirements |
| [Haskell](/std/languages/haskell/) | Type-safe systems programming |
| [Rust](/std/languages/rust/) | Memory safety without garbage collection |
| [TypeScript](/std/languages/typescript/) | Web services and tooling |
| [Bash](/std/languages/bash/) | System automation and scripting |

## Weyl Standard Nix

The Nix component provides infrastructure patterns for:

```
nix flake init -t github:weyl-ai/weyl-std
nix flake init -t github:weyl-ai/weyl-std#cuda
nix flake init -t github:weyl-ai/weyl-std#minimal
```

### Quick Start

```
{
  inputs.weyl-std.url = "github:weyl-ai/weyl-std";

  outputs = inputs@{ flake-parts, weyl-std, ... }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [ weyl-std.flakeModules.default ];

      weyl-std.nixpkgs.cuda.enable = true;

      perSystem = { pkgs, ... }: {
        packages.default = pkgs.hello;
      };
    };
}
```

### Nix Modules

| Module | Description |
|--------|-------------|
| `weyl-std.flakeModules.default` | Batteries included |
| `weyl-std.flakeModules.formatter` | Treefmt with opinionated defaults |
| `weyl-std.flakeModules.nixpkgs` | Nixpkgs config with CUDA support |
| 

[Content truncated - see full page]

---

### Languages

**URL**: https://weyl.ai/std/languages/
**Description**: Weyl Standard provides coding guidelines for production systems across multiple languages, optimizing for disambiguation, testability, and maintainability.

# Languages

**Weyl Standard** provides coding guidelines for production systems across multiple languages. Each standard optimizes for disambiguation, testability, and maintainability.

## Language Standards

| Language | Focus |
|----------|-------|
| [Nix](/std/nix/) | Reproducible infrastructure and builds |
| [Python](/std/languages/python/) | GPU inference and ML orchestration |
| [C++](/std/languages/cpp/) | Extreme performance requirements |
| [Haskell](/std/languages/haskell/) | Type-safe systems programming |
| [Rust](/std/languages/rust/) | Memory safety without garbage collection |
| [TypeScript](/std/languages/typescript/) | Web services and tooling |
| [Bash](/std/languages/bash/) | System automation and scripting |

## Core Philosophy

**Optimize for disambiguation, not brevity.**

In modern codebases where agents generate code and humans debug at 3am:
- Every ambiguity compounds exponentially
- Code is written once, read hundreds of times
- Grep-ability matters more than cleverness
- Type safety prevents tomorrow's bugs

## Shared Principles

All Weyl Standard language guides follow these principles:

- **Explicit over implicit** — No hidden behavior
- **Full words over abbreviations** — `configuration` not `cfg`
- **Grep-optimized naming** — Globally unique identifiers
- **Type safety** — Let compilers catch bugs
- **Property-based testing** — Invariants over examples
- **Structured logging** — Parseable, searchable output

The guides focus on production patterns that scale across teams and time.

---

### Weyl Standard Bash

**URL**: https://weyl.ai/std/languages/bash/
**Description**: Conventions, patterns, and requirements for Bash scripts within Weyl AI systems.

# Weyl Standard Bash

**Weyl Standard Bash** defines the conventions, patterns, and requirements for Bash scripts within Weyl AI systems.

## Status

This specification is under development.

## Scope

Weyl Standard Bash applies to:

- All shell scripts within weyl-ai repositories
- Build and deployment automation
- System administration scripts

## Conformance

*To be defined.*

---

### Weyl Standard C++

**URL**: https://weyl.ai/std/languages/cpp/
**Description**: C++ guidelines for extreme performance requirements, using modern C++23 features with emphasis on clarity and disambiguation in agent-heavy development.

# `// s4 // cpp // guidelines`

## Strategy and Motivation

We use C++ in situations where we need to do something extreme along one or more dimensions: we are
in a regime where no compromise is possible. Typically we do this by having low-friction access to
efficient, ergonomic implementations of best-in-class algorithms. Sometimes, we have the opportunity
to do something best-in-class ourselves; we consider such proposals with open minds and healthy
skepticism. Our C++ codebase and the investment represented by maintaining it is the optionality
premium on these degrees of freedom.

Much if not most excellent modern C++ code is proprietary because worthwhile C++ code is expensive
and most contemporary projects don't need it. This leads to a situation where it is difficult to
learn well outside of an elite technology or finance company. For non-commercial examples of extreme
requirements, consider people working at the frontiers of human knowledge: CERN has excellent code
because they operate in regimes that would be daunting for any company.

This document is aimed at three audiences:

- Experienced C++ programmers who have missed recent developments
- Programmers new to serious C++ who want to skip learning curve friction
- Agents with extensive informational resources who need clear guidelines

## The Economics of Code in Agent-Heavy Development

**In a codebase with heavy agent contribution, traditional economics invert:**

- Code is written once by agents in seconds
- Code is read hundreds of times by humans and agents
- Code is debugged when you're under pressure by tired humans
- Code is modified by agents who lack the original context

**Every ambiguity compounds exponentially.**

### The Fundamental Principle

```

// this costs an agent 0.1 seconds to write, a human 10 seconds to debug:
auto e = edge{};
if (e.p > 0) process(e);

// this costs an agent 0.2 seconds to write, saves hours of cumulative confusion:
auto inference_configuration = s4::inference::c

[Content truncated - see full page]

---

### Weyl Standard Haskell

**URL**: https://weyl.ai/std/languages/haskell/
**Description**: Production Haskell guidelines optimizing for disambiguation, focusing on pragmatic patterns for web servers, compilers, and systems programming.

# `// hypermodern // haskell // production`

## Why We Do What We Do

Production Haskell exists at the intersection of mathematical beauty and economic reality. We write
in a language that could express category theory but choose to express business logic instead. Not
because we can't do the former, but because making money with functional programming is the ultimate
proof of concept.

If RWST was written today, it wouldn't be a monad transformer tutorial. It would be
`ReaderT Config (ExceptT AppError (StateT Metrics IO))`, it would have structured logging,
Prometheus metrics, and compile with `-O2 -Wall -Werror`. It would process millions of events per
second while three different teams extend it without coordination. That's the gulf between academic
Haskell and production Haskell—we're not writing papers, we're writing paychecks.

This guide is for practitioners who know that `Applicative` is powerful not because it's a
mathematical abstraction, but because it makes JSON parsing composable. Who understand that `STM`
isn't beautiful because it solves the dining philosophers problem, but because it means you can
write concurrent code at 3am without creating race conditions.

We are not the same as the Haskell you learned in university. We're what happens when you take those
ideas and make them work for money.

## Core Philosophy: Optimize for Disambiguation

In modern codebases where agents generate significant amounts of code, traditional economics invert:

- Code is written once by agents in seconds
- Code is read hundreds of times by humans and agents
- Code is debugged when you're under pressure by tired humans
- Code is modified by agents who lack the original context

**Every ambiguity compounds exponentially.**

```
-- This costs an agent 0.1 seconds to write, a human 10 minutes to debug
process e = if p e > 0 then go e else stop

-- This costs an agent 0.2 seconds to write, saves hours of cumulative confusion
processIncomingRequest :: HttpRequest -> IO Respo

[Content truncated - see full page]

---

### Weyl Standard Python

**URL**: https://weyl.ai/std/languages/python/
**Description**: Production Python for GPU inference and ML orchestration, emphasizing type safety, structured logging, and disambiguation over brevity.

# // weyl standard // production python

## The Gap

Production Python lives between "just use `numpy`" and "C++ and cigarettes." The GPU does the work; Python orchestrates it correctly.

No notebooks. No global variables. Type hints, structured logging, proper error boundaries, reproducible seeds. We're not exploring ideas—we're deploying inference at scale.

## Core: Optimize for Disambiguation

Agents write code in seconds. Humans debug it at 3am. Every ambiguity compounds.

```
# costs 0.1s to write, 10min to debug
def process(x):
  return model(x) if x.shape[0] > 0 else None

# costs 0.2s to write, saves hours
def process_inference_batch(
  input_batch: torch.Tensor,
  model: InferenceEngine,
  device: torch.device,
) -> InferenceBatchResult:
  if input_batch.shape[0] == 0:
    return InferenceBatchResult.empty()
  return model.forward(input_batch, device=device)
```

## Python 3.12+

Exception groups, TypeVarTuple, Self type, pattern matching, better errors. If you're on 3.10, you're missing table stakes.

## Style: Weyl Standard

- **2-space indent** — matches C++, fits more on screen
- **Double quotes** — `"string"` always
- **`ex` for exceptions** — `except Exception as ex:`
- **Lowercase types** — `list[str]`, `dict[str, int]`
- **Union as pipe** — `str | None` not `Optional[str]`
- **f-strings only** — never `%` or `.format()`

## Naming: Three-Character Rule

If it's ≤3 chars, it's probably wrong for production.

```
# BAD
cfg = load_cfg()
res = proc(req)

# GOOD
configuration = load_model_configuration()
result = process_inference_request(request)
```

**Exceptions** (local scope only): `idx/jdx`, `lhs/rhs`, `key/value`, `row/col`

## Type Hints: Non-Negotiable

Every function. Use `ty` in CI.

```
def load_inference_model(
  checkpoint_path: Path,
  device: torch.device,
  dtype: torch.dtype = torch.float16,
) -> nn.Module:
  """Load model for inference.

  Raises:
    FileNotFoundError: Checkpoint missing
    RuntimeError: Architecture mismatch
  """


[Content truncated - see full page]

---

### Weyl Standard Rust

**URL**: https://weyl.ai/std/languages/rust/
**Description**: Production Rust for memory safety without garbage collection: explicit error handling, type-driven development, and agent-friendly patterns.

# `// weyl // rust // production`

## Why We Do What We Do

Production Rust is what happens when you take systems programming seriously but refuse to accept C++'s legacy baggage. We write Rust not because it's trendy, but because memory safety without garbage collection is the only reasonable path forward for systems that can't afford downtime or undefined behavior.

If this guide was written in 2015, it would focus on fighting the borrow checker. In 2026, the borrow checker is your pair programmer who never sleeps, never gets tired, and catches use-after-free bugs at compile time instead of in production at 3am.

This guide is for people who understand that `Result<T, E>` isn't beautiful because it's a monad—it's beautiful because it makes error handling visible in function signatures. Who know that `Send + Sync` bounds aren't academic type theory—they're the compiler proving your concurrent code won't have data races.

We're not writing Rust because we read the book and liked the theory. We're writing Rust because we're tired of debugging memory corruption and race conditions in production.

## Core Philosophy: Optimize for Disambiguation

In modern codebases where agents generate significant amounts of code, traditional economics invert:

- Code is written once by agents in seconds
- Code is read hundreds of times by humans and agents
- Code is debugged when you're under pressure by tired humans
- Code is modified by agents who lack the original context

**Every ambiguity compounds exponentially.**

```
// This costs an agent 0.1 seconds to write, a human 10 minutes to debug
fn process(e: E) -> R {
    if e.v > 0 { go(e) } else { stop() }
}

// This costs an agent 0.2 seconds to write, saves hours of cumulative confusion
fn process_incoming_request(http_request: HttpRequest) -> Result<ResponseData, RequestError> {
    if http_request.timeout_milliseconds > 0 {
        process_valid_request(http_request)
    } else {
        Err(RequestError::InvalidTimeout)
    }

[Content truncated - see full page]

---

### Weyl Standard TypeScript

**URL**: https://weyl.ai/std/languages/typescript/
**Description**: Conventions, patterns, and requirements for TypeScript code within Weyl AI systems for web services and tooling.

# Weyl Standard TypeScript

**Weyl Standard TypeScript** defines the conventions, patterns, and requirements for TypeScript code within Weyl AI systems.

## Status

This specification is under development.

## Scope

Weyl Standard TypeScript applies to:

- All TypeScript code within weyl-ai repositories
- Web interfaces and dashboards
- API clients and SDKs

## Conformance

*To be defined.*

---

### Weyl Standard Nix

**URL**: https://weyl.ai/std/nix/
**Description**: A specification for building reproducible, composable infrastructure on Nix with flakes, flake-parts, and consistent naming conventions.

# Weyl Standard Nix

**Weyl Standard Nix** is a specification for building reproducible, composable infrastructure on Nix. Part of the Weyl Standard collection of language standards.

## Core Principles

1. **Flakes exclusively** - No legacy Nix, no `nix-shell`, no `NIX_PATH`
2. **flake-parts as foundation** - Module system for flakes
3. **nixos-unified structure** - Autowiring over boilerplate
4. **Overlays for packages** - Centrally managed nixpkgs
5. **lisp-case everywhere** - Consistent naming across identifiers

## Philosophy

- [Why Nix](/std/nix/philosophy/why-nix/) — The case for reproducibility
- [The Overlay](/std/nix/philosophy/overlay-as-universe-transformer/) — Universe transformers
- [lisp-case](/std/nix/philosophy/lisp-case/) — Naming convention rationale

## Guides

### Getting Started

- [Installation](/std/nix/guides/getting-started/installation/) — Prerequisites and setup
- [First Flake](/std/nix/guides/getting-started/first-flake/) — Your first conformant flake
- [Infrastructure](/std/nix/guides/getting-started/infrastructure/) — Cachix, Hercules CI, Omnix

### Patterns

- [Naming Conventions](/std/nix/guides/patterns/naming/) — How to name things
- [File Placement](/std/nix/guides/patterns/file-placement/) — Where things go
- [Module Systems](/std/nix/guides/patterns/module-systems/) — flake-parts, NixOS, darwin
- [Writing Packages](/std/nix/guides/patterns/writing-packages/) — callPackage, finalAttrs
- [Writing Modules](/std/nix/guides/patterns/writing-modules/) — Options, config, mkIf
- [Testing](/std/nix/guides/patterns/testing/) — nix flake check, NixOS tests
- [Documentation](/std/nix/guides/patterns/documentation/) — Comments, assertions, errors
- [Forbidden Patterns](/std/nix/guides/patterns/forbidden-patterns/) — What not to do

### Advanced

- [Standard Environments](/std/nix/guides/advanced/stdenvs/) — Custom build environments
- [Overlays](/std/nix/guides/advanced/overlays/) — Package set transformations
- [Cross-Compilation](/std/nix

[Content truncated - see full page]

---

### Guides

**URL**: https://weyl.ai/std/nix/guides/
**Description**: Practical guides for working with Weyl Standard Nix, covering getting started, patterns, and advanced topics.

# Guides

Practical guides for working with Weyl Standard Nix.

## Getting Started

- [Installation](getting-started/installation/)
- [First Flake](getting-started/first-flake/)

## Patterns

- [File Placement](patterns/file-placement/)
- [Module Systems](patterns/module-systems/)
- [Forbidden Patterns](patterns/forbidden-patterns/)

## Advanced

- [Standard Environments](advanced/stdenvs/)
- [Overlays](advanced/overlays/)
- [Cross-Compilation](advanced/cross-compilation/)

---

### Advanced

**URL**: https://weyl.ai/std/nix/guides/advanced/
**Description**: Advanced topics for experienced Nix users.

# Advanced

Advanced topics for experienced Nix users.

- [Standard Environments](stdenvs/) — The weyl-stdenv family
- [Overlays](overlays/) — Advanced overlay composition
- [Cross-Compilation](cross-compilation/) — Building for Grace, Jetson, aarch64

---

### Cross-Compilation

**URL**: https://weyl.ai/std/nix/guides/advanced/cross-compilation/
**Description**: Building for aarch64 targets from x86_64 workstations.

# Cross-Compilation

Building for aarch64 targets from x86_64 workstations.

## Available Targets

| Target | Platform | GPU |
|--------|----------|-----|
| `weyl-cross.grace` | aarch64-linux | sm_90a (Grace Hopper) |
| `weyl-cross.jetson` | aarch64-linux | sm_87 (Jetson Orin) |
| `weyl-cross.aarch64` | aarch64-linux | none |
| `weyl-cross.x86-64` | x86_64-linux | sm_120 (Blackwell) |

## Usage

```
# Build for Grace Hopper
pkgs.weyl-cross.grace.mkDerivation {
  name = "my-grace-app";
  src = ./src;
}

# Build for Jetson Orin
pkgs.weyl-cross.jetson.mkDerivation {
  name = "my-jetson-app";
  src = ./src;
}
```

## How It Works

Cross-compilation uses:

1. `pkgsCross.aarch64-multiplatform` for the target toolchain
2. CUDA cross-compilation flags for GPU code
3. The weyl-stdenv flags for debuggability

## Distributed Builds

For faster cross-compilation, configure remote builders:

```
# configuration.nix
nix.buildMachines = [{
  hostName = "grace-builder";
  system = "aarch64-linux";
  maxJobs = 32;
  supportedFeatures = [ "nixos-test" "big-parallel" ];
}];

nix.distributedBuilds = true;
```

## Native vs Cross

When possible, build natively on target hardware. Cross-compilation is for:

- CI pipelines running on x86_64
- Development iteration before hardware access
- Building firmware/bootloaders

For production inference workloads, build on the target architecture.

---

### Overlays

**URL**: https://weyl.ai/std/nix/guides/advanced/overlays/
**Description**: Advanced overlay composition patterns.

# Overlays

Advanced overlay composition patterns.

## Composing Multiple Overlays

```
{ lib, ... }:
{
  flake.overlays.default = lib.composeManyExtensions [
    (import ./cuda.nix)
    (import ./stdenvs.nix)
    (import ./internal-tools.nix)
  ];
}
```

## Overlay Order

Overlays are applied in order. Later overlays see the changes from earlier ones in `prev`.

## Referencing final

Use `final` to reference the fixed-point—packages as they will be after all overlays:

```
final: prev: {
  my-tool = final.callPackage ./my-tool.nix { };
  # my-tool can depend on packages defined in later overlays
}
```

## Per-System Overlays

For overlays that need system-specific logic:

```
final: prev:
let
  inherit (final.stdenv.hostPlatform) system isAarch64;
in {
  my-tool = final.callPackage ./my-tool.nix {
    cuda-arch = if isAarch64 then "sm_90a" else "sm_120";
  };
}
```

See [The Overlay](../../philosophy/overlay-as-universe-transformer/) for the philosophy.

---

### Standard Environments

**URL**: https://weyl.ai/std/nix/guides/advanced/stdenvs/
**Description**: The weyl-stdenv family provides opinionated build environments for serious systems work.

# Standard Environments

The weyl-stdenv family provides opinionated build environments for serious systems work.

## Philosophy

A stdenv defines how the world builds itself.

The flags are the building code:

```
-O2                           real performance
-g3 -gdwarf-5                 full symbols
-fno-omit-frame-pointer       stack traces work
-fno-stack-protector          no theater
-fcf-protection=none          predictable addresses
hardeningDisable = [ "all" ]  nix wrapper killed
dontStrip = true              symbols stay
```

## Available Stdenvs

| Stdenv | Description |
|--------|-------------|
| `weyl-stdenv` | glibc dynamic, clang, C++23 |
| `weyl-stdenv-static` | glibc static |
| `weyl-stdenv-musl` | musl + libstdc++ |
| `weyl-stdenv-musl-static` | fully static, deploy anywhere |
| `weyl-stdenv-cuda` | CUDA device + host |

## Usage

```
# Basic derivation
pkgs.weyl-stdenv.mkDerivation {
  name = "my-app";
  src = ./.;
  buildPhase = "$CXX -o app main.cpp";
}

# Static binary (glibc)
pkgs.weyl-stdenv-static.mkDerivation {
  name = "my-tool";
  src = ./.;
}

# Fully portable (musl static)
pkgs.weyl-stdenv-musl-static.mkDerivation {
  name = "deploy-anywhere";
  src = ./.;
}

# CUDA kernel
pkgs.weyl-stdenv-cuda.mkDerivation {
  name = "cuda-kernel";
  src = ./.;
  buildPhase = "$CXX -o kernel main.cu";
  # CUDA_HOME and CUDA_PATH are set
}
```

## Cross-Compilation

Build on x86_64 workstation, deploy to ARM:

```
# Grace Hopper (aarch64 + sm_90a)
pkgs.weyl-cross.grace.mkDerivation {
  name = "grace-app";
  src = ./.;
}

# Jetson Orin (aarch64 + sm_87)
pkgs.weyl-cross.jetson.mkDerivation {
  name = "jetson-app";
  src = ./.;
}

# Generic aarch64 (no GPU)
pkgs.weyl-cross.aarch64.mkDerivation {
  name = "arm-app";
  src = ./.;
}
```

From aarch64, target x86_64:

```
pkgs.weyl-cross.x86-64.mkDerivation {
  name = "blackwell-app";
  src = ./.;
}
```

## Cross Targets

| Target | Arch | GPU |
|--------|------|-----|
| `weyl-cross.grace` | aarch64 | sm_90a 

[Content truncated - see full page]

---

### weyl-pkgs — The Debuggable Universe

**URL**: https://weyl.ai/std/nix/guides/advanced/weyl-pkgs/
**Description**: Every package. Every library. Every time. RelWithDebInfo for the entire dependency closure.

# weyl-pkgs — The Debuggable Universe

Every package. Every library. Every time.

RelWithDebInfo for the entire dependency closure.

No more black boxes.

## Philosophy

Stock compilers. Stock C++ versions. Stock build systems.

Just the posture:

```
-O2                           # optimize for real
-g3 -gdwarf-5                 # symbols everywhere
-fno-omit-frame-pointer       # stack traces work
-fno-limit-debug-info         # don't truncate
hardeningDisable = [ "all" ]  # no theater
dontStrip = true              # never strip
```

## Two Worlds

```
pkgs.ffmpeg        # their way
weyl-pkgs.ffmpeg   # our way
```

Both exist. Use whichever you need.

## Build System Integration

### CMake

```
CMAKE_BUILD_TYPE=RelWithDebInfo
CMAKE_C_FLAGS_RELWITHDEBINFO=-O2 -g3 -gdwarf-5 -DNDEBUG
CMAKE_CXX_FLAGS_RELWITHDEBINFO=-O2 -g3 -gdwarf-5 -DNDEBUG
```

### Meson

```
--buildtype=debugoptimized
-Db_ndebug=true
-Ddebug=true
-Doptimization=2
```

### Autotools

`NIX_CFLAGS_COMPILE` applies to everything.

## Usage

### In a Flake

```
{
  inputs.weyl-std.url = "github:weyl-ai/weyl-std";

  outputs = { self, nixpkgs, weyl-std, ... }: {
    perSystem = { system, ... }:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ weyl-std.overlays.default ];
        };

        # The debuggable universe
        weyl-pkgs = import nixpkgs {
          inherit system;
          overlays = [ weyl-std.overlays.posture ];
        };
      in {
        devShells.default = pkgs.mkShell {
          packages = [
            # Your code: weyl-stdenv (clang, C++23)
            (pkgs.weyl-stdenv.mkDerivation { ... })

            # Dependencies: debuggable
            weyl-pkgs.ffmpeg
            weyl-pkgs.opencv
            weyl-pkgs.boost
          ];
        };
      };
  };
}
```

### Debug a Crash in a Dependency

```
# Build with weyl-pkgs
nix build .#weyl-pkgs.ffmpeg

# Now gdb works
gdb --args ./result/bin/ffmpeg -i input.mp4 output.mkv

(gdb) bt
#0  av_

[Content truncated - see full page]

---

### Getting Started

**URL**: https://weyl.ai/std/nix/guides/getting-started/
**Description**: Start here to set up your first Weyl Standard Nix project.

# Getting Started

Start here to set up your first Weyl Standard Nix project.

- [Installation](installation/) — Prerequisites and setup
- [First Flake](first-flake/) — Your first conformant flake

---

### Consuming Weyl Standard

**URL**: https://weyl.ai/std/nix/guides/getting-started/consuming-weyl-std/
**Description**: How to use weyl-std in your projects.

# Consuming Weyl Standard

How to use weyl-std in your projects.

## Quick Start

Add weyl-std to your flake inputs:

```
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    weyl-std.url = "github:weyl-ai/weyl-std";
  };

  outputs = inputs@{ flake-parts, weyl-std, ... }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [ weyl-std.flakeModules.default ];

      # weyl-std configuration
      weyl-std = {
        formatter.enable = true;
        devshell.enable = true;
      };

      perSystem = { config, pkgs, ... }:
        let
          P = config.weyl.prelude;
        in {
          packages.default = P.stdenv.default {
            pname = "my-app";
            version = "1.0";
            src = ./.;
          };
        };
    };
}
```

## Modules

### Batteries Included

Import everything at once:

```
imports = [ weyl-std.flakeModules.default ];
```

Includes: formatter, docs, nixpkgs config, overlays, devshell, prelude.

### A La Carte

Pick what you need:

```
imports = [
  weyl-std.flakeModules.formatter  # treefmt-nix with opinionated defaults
  weyl-std.flakeModules.nixpkgs    # nixpkgs config
  weyl-std.flakeModules.std        # overlays (includes prelude + nvidia-sdk)
  weyl-std.flakeModules.prelude    # prelude flake-module only
  weyl-std.flakeModules.devshell   # Development shell
  weyl-std.flakeModules.docs       # Documentation generation
];
```

## The Weyl Prelude

Access the prelude via `config.weyl.prelude`:

```
perSystem = { config, ... }:
  let
    P = config.weyl.prelude;
  in {
    # Functional library
    example = P.map (x: x * 2) [ 1 2 3 ];  # [ 2 4 6 ]

    # Stdenvs
    packages.my-app = P.stdenv.default {
      pname = "my-app";
      version = "1.0";
      src = ./.;
    };

    # Language toolchains
    packages.py-app = P.python.app {
      pname = "py-app";
      version = "1.0";
      src = ./.;
    };
  };
```

## Using Stdenvs

#

[Content truncated - see full page]

---

### Your First Flake

**URL**: https://weyl.ai/std/nix/guides/getting-started/first-flake/
**Description**: Create your first conformant flake with Weyl Standard.

# Your First Flake

## The Minimal Conformant Flake

```
{
  description = "My weyl-std project";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    weyl-std.url = "github:weyl-ai/weyl-std";
  };

  outputs = inputs@{ flake-parts, weyl-std, ... }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [ weyl-std.flakeModules.default ];

      systems = [ "x86_64-linux" "aarch64-linux" ];

      perSystem = { pkgs, ... }: {
        packages.default = pkgs.hello;
        devShells.default = pkgs.mkShell {
          packages = [ pkgs.hello ];
        };
      };
    };

  nixConfig = {
    extra-substituters = [ "https://weyl-ai.cachix.org" ];
    extra-trusted-public-keys = [
      "weyl-ai.cachix.org-1:cR0SpSAPw7wejZ21ep4SLojE77gp5F2os260eEWqTTw="
    ];
  };
}
```

## What weyl-std Provides

When you import `weyl-std.flakeModules.default`, you get:

| Module | Description |
|--------|-------------|
| formatter | treefmt with nixfmt, ruff, shfmt, etc. |
| nixpkgs | Central nixpkgs config with CUDA support |
| std | Overlays and library functions |
| devshell | Development shell utilities |

## Adding a Package

Create `nix/packages/my-tool.nix`:

```
{ lib, stdenv }:
stdenv.mkDerivation (finalAttrs: {
  pname = "my-tool";
  version = "0.1.0";

  src = ../../src;

  meta = {
    description = "My tool";
    license = lib.licenses.mit;
    mainProgram = "my-tool";
  };
})
```

Then in your flake module:

```
perSystem = { pkgs, ... }: {
  packages.my-tool = pkgs.callPackage ./nix/packages/my-tool.nix { };
};
```

## Enabling CUDA

```
imports = [ weyl-std.flakeModules.default ];

weyl-std.nixpkgs.cuda.enable = true;
```

This configures nixpkgs with:

- `cudaSupport = true`
- `cudaCapabilities` for your target GPUs
- CUDA overlays from weyl-std

## Next Steps

- [File Placement](../patterns/file-placement/) — Where to put your code
- [Module Systems](../patterns/module-systems/) 

[Content truncated - see full page]

---

### Infrastructure

**URL**: https://weyl.ai/std/nix/guides/getting-started/infrastructure/
**Description**: Configure your environment to use shared infrastructure for faster builds.

# Infrastructure

Before writing any Nix, configure your environment to use our shared infrastructure. This isn't bureaucracy—it's the difference between builds taking minutes versus hours.

## Binary Cache (Cachix)

Without a cache, every developer rebuilds every package from source. With our Cachix cache, you download pre-built binaries in seconds.

Every flake gets this configuration:

```
{
  nixConfig = {
    extra-experimental-features = [
      "nix-command"
      "flakes"
      "pipe-operators"  # Internal code only—never in open source
    ];
    extra-substituters = [
      "https://weyl-ai.cachix.org"
    ];
    extra-trusted-public-keys = [
      "weyl-ai.cachix.org-1:cR0SpSAPw7wejZ21ep4SLojE77gp5F2os260eEWqTTw="
    ];
  };
}
```

Put it in `nixConfig` so anyone who clones your repo gets the cache automatically. No manual setup, no onboarding friction, no "why is CI so slow" questions.

## Hercules CI

[Hercules CI](https://docs.hercules-ci.com/) builds every flake output on push and uploads successes to Cachix. Failed builds block merging. The virtuous cycle: the more we build, the more gets cached, the faster everyone gets.

## Omnix

[Omnix](https://github.com/juspay/omnix) wraps common Nix operations with better ergonomics:

```
om health    # Catch configuration issues before CI does
om show      # Readable tree of flake outputs
om init      # Initialize from templates
om ci        # Run CI checks locally
```

Use `om health` regularly. It catches the mistakes that would otherwise only surface in CI.

## Secrets

We use [agenix](https://github.com/ryantm/agenix) via our wrapper at [weyl-ai/secrets](https://github.com/weyl-ai/secrets). Secrets are encrypted at rest, decrypted only at activation time on the target system.

```
{ config, ... }: {
  age.secrets.database-password = {
    file = ../secrets/database-password.age;
    owner = "postgres";
  };

  # Reference the path, never the content
  systemd.services.myapp.environment = {
    DATABASE_P

[Content truncated - see full page]

---

## Blog Posts

Technical articles and announcements from the Weyl team.

### mdspan-cute: Zero-Overhead Bridge to CUTLASS

**URL**: https://weyl.ai/plan/mdspan-cute/
**Published**: 2026-01-23
**Author**: Weyl Team
**Tags**: CUDA, C++, mdspan, CUTLASS, Lean, formal methods

C++23 std::mdspan meets CUTLASS cute layouts. One header. Zero cost. 26 theorems. 0 sorry.

**TL;DR**: C++23 `std::mdspan` meets CUTLASS cute layouts. One header. Zero cost.

```
tile[row, col] = value;  // swizzled, composed, zero-cost
```

*// straylight // correct by construction // the result is saved //*

---

### Ruining GPU Market Owners' Day with the Power of Nix

**URL**: https://weyl.ai/plan/portable-nix-gpu-runtime/
**Published**: 2026-01-15
**Author**: baileylu / b7r6
**Tags**: Nix, Container, Nvidia, CUDA, Scaling

Build containers with nix2gpu that run on any GPU market

# Foreword

I was asked to write a forward because I made the first commit. `nix2gpu` started as `nix2vast` - the kind of thing I knew we needed to exist but didn't know enough Nix to write properly.

```
commit 045272907f390b08e31d0f646de12477a5d76460
Author: Luke Bailey <baileylu@tcd.ie>
Date:   Thu Sep 18 17:38:26 2025 +0100

    Refactor to expose `nix2container` functions instead of wrapping; Support podman

commit b93b0c52b94e0415f9287170b9788bbcd4757a53
Author: b7r6 <b7r6@b7r6.net>
Date:   Sun Sep 14 14:24:07 2025 -0400

    // nix2vast // initial commit
```

Four days.

Now:

```
b7r6 on ultraviolence isospin dev*
❯ nix run -L .#fc-gpu
═══════════════════════════════════════════════════════════
  Firecracker GPU Passthrough VM
═══════════════════════════════════════════════════════════

→ Checking GPU 0000:01:00.0...
  GPU: 01:00.0 VGA compatible controller [0300]: NVIDIA Corporation GB202GL [RTX PRO 6000 Blackwell Workstation Edition] [10de:2bb1] (rev a1)
  Driver: vfio-pci

→ Kernel: .vm-assets/vmlinux-6.12.63.bin
→ Initramfs: .vm-assets/initramfs.cpio.gz
→ Rootfs: .vm-assets/gpu-rootfs.ext4
```

Luke is the kind of talent that every experienced hacker dreams of working with, the kind that can hit back. His contributions to the Nix ecosystem are already significant before he's finished his undergraduate studies at Trinity, and his contributions to Weyl AI are existential to our very habits of thought. If the framing seems a bit brash, blame me, I told him that free, fair, and transparent markets are a natural public good and he did the math.

— b7r6

If you've tried to run a GPU workload recently, you've almost certainly run into on-demand priced GPU markets like [`vast.ai`](https://vast.ai/) or [`runpod`](https://www.runpod.io/), where you have the option of renting GPUs of various capability and reliability.

![vast.ai interface](/plan/vastai-interface.png)

These vendors provide an approachable way for normal people and smaller businesses to get their hands on some GPU compute, however, while it may not be obvious, it is common practice for these vendors to lock you into their service by providing container images which only run on their service, preventing you from switching away, if, for example, one of their competitors now offers a better price. 

Of course, this makes sense, but as savvy consumers and nix nerds we weren't willing to just accept that that had to be the case, which is where we're delighted to introduce something we've been hacking on for months:

**[`nix2gpu`](https://github.com/fleek-sh/nix2gpu)**

---

# An Introduction to `nix2gpu`

`nix2gpu` is a simple and easy to compose alternative to using docker (or other container tools) to produce containers ready to plug into all of these GPU markets. By ensuring compatibility with all of them, we give you the maximum amount of choice for where to run your GPU workloads and free you from the shackles of common docker problems.

> As `b7r6` mentions above, this also has

[Content truncated - see full article]

---

### One Service Definition to Rule Them All

**URL**: https://weyl.ai/plan/put-nix-services-anywhere/
**Published**: 2026-01-12
**Author**: baileylu
**Tags**: Nix, Rust, Container, NixOS

Meet Nimi: a tiny process manager that takes NixOS 25.11's modular services spec and runs it anywhere you need.

**TL;DR:** Modular services give Nix a portable way to describe long-running processes once and reuse them everywhere. `Nimi` is a tiny Rust process manager that runs those definitions outside NixOS. Both are early and evolving, but the promise is one service definition that you can bring anywhere.

# Modular Services: Introduction and history

Modular services, in their current version, represent the culmination of a couple of years of bikeshedding in PR comments. Starting with [this RFC](https://github.com/NixOS/rfcs/pull/163), where discussion began on an implementation of a "Portable Service Layer", which proposed using a generator function primitive `createManagedProcess` to produce some kind of config file which could be translated into configuration for other process managers.

After a period of discussion and the original maintainer seemingly giving up, this idea eventually evolved into [this PR](https://github.com/NixOS/nixpkgs/pull/372170), finally introducing an abstraction for writing portable Nix services. The key trick uses the module types [`types.attrsOf`](https://noogle.dev/f/lib/types/attrsOf) and [`types.submodule <services submodule def>`](https://noogle.dev/f/lib/types/submodule) to make the service definitions extensible.
In practice, this means a service definition can be evaluated inside any module system without rewriting it.

> `types` refers to [`lib.types`](https://noogle.dev/q?term=lib.types), from `nixpkgs`'s `lib`

The accepted implementation involves defining services on top of a nix module which is usable in any modules system, and mandating that the services be defined in terms of the options defined by said module.

In a code sense, this `submodule` type looks like:

```
servicesSubmodule = types.submodule {
  options.process.argv = lib.mkOption {
    description = ''
      Arguments to the process to run here
    '';
    type = types.listOf types.str;
  };
  options.configData = lib.mkOption {
    # hidden for compactness, check out the actual specification or the rendering in the Nimi docs linked below
  };
};
```

This is made portable by only evaluating it with the minimal set of arguments passed into any module system by [`lib.evalModules`](https://noogle.dev/f/lib/evalModules), of which are:

- `lib`: The nixpkgs library.
- `config`: The results of all options after merging the values from all modules together.
- `options`: The options declared in all modules.
- `specialArgs`: The `specialArgs` argument passed to `evalModules`.

Since these are common to **every module system**, these can then be nested inside **any of those module systems**, where the translation to the lower level definitions occurs. This includes targets like `home-manager`, `NixOS` or any other custom module system you can think of.

A downstream modules system definition may look like:

```
options.myServices = lib.mkOption {
  description = ''
    Collection of modular services to run with an implementation in
    a custom modules sy

[Content truncated - see full article]

---

### The Inhuman Quality of Starlight: The Operating System of the Drone War and The UTF-8 of AI

**URL**: https://weyl.ai/plan/inhuman-quality-of-starlight-part-1/
**Published**: 2026-01-09
**Author**: b7r6
**Tags**: NVFP4, Infrastructure, DeepSeek, CUDA, Nix, Embedded AI, Quantization

Part 1: The Operating System of the Drone War and The UTF-8 of AI. Constraints dominate resources, and the lattice doesn't negotiate.

> *"The beauty of things was born before eyes and sufficient to itself; the heart-breaking beauty will remain when there is no heart to break for it."*
> — Robinson Jeffers

![Hermann Weyl - mathematician who worked alongside Einstein at Princeton](https://media.weyl.ai/weyl-photo.png)

## 2. The (Aspirant) American DeepSeek

> *"I learned very early the difference between knowing the name of something and knowing something."*
> — Richard Feynman

DeepSeek-V3 matched GPT-4 on 2.788M H800 GPU hours, not because they had better hardware but because the opposite was true: export controls meant H100s were expensive and H800s were what they had, so the constraint forced the insight.

What they actually did:

**Multi-head Latent Attention** is not GQA or MQA but a genuinely novel attention variant, with low-rank KV compression into a latent space and weight absorption to skip decompression at inference, yielding a KV cache smaller than MQA with modeling capacity better than MHA.

**Custom PTX communication kernels** emerged because their cross-node expert parallelism had a 1:1 compute-to-communication ratio, so they wrote warp-specialized kernels for IB-to-NVLink forwarding with dynamic allocation and customized PTX to reduce L2 cache pressure. This is not "we used NCCL"—this is "we wrote assembly to overlap memory operations on the interconnect."

And FP8 training at 671B scale, DualPipe for bidirectional pipeline parallelism, multi-token prediction, auxiliary-loss-free MoE routing—the list goes on. Then they open-sourced everything but OpenAI's training data.

American labs have the compute, but they don't have the constraint, and when you can always add more GPUs, you never learn to subtract.

**In a sense we do things the Hangzhou way, but that's because hackers in Hangzhou do things the way Silicon Valley did when we learned there—the C++, the ZooKeeper, the cigarettes.**

Because we operate under constraints, we get to be useful in another way: we get to play Red Team in the Second Millennium Challenge. We're here to do great work for our own benefit, but we like being the useful kind of competition, all the moreso when the stakes are this high.

---

## 3. Lab Notes (Someone is Wrong on The Internet)

> *"How wonderful that we have met with a paradox. Now we have some hope of making progress."*
> — Niels Bohr

We need all the help we can get, and that's what it is to be a small lab in an ocean overstocked with Behemoths.

So we're linking to our lab notes—not papers, since we're not claiming we've proven anything, just hypotheses written in LaTeX, which is an [attractive nuisance](https://xkcd.com/386/). If we're wrong, someone will tell us, and that's the point.

**[Hypothesis 1: The Lattice Hypothesis.](/papers/lattice-hypothesis.pdf)** Deep learning theory has the ontology backwards. The standard view holds that neural networks are continuous functions on ℝⁿ and that floating-point is an approximation which introduces "errors," but we think t

[Content truncated - see full article]

---

### Villa Straylight Papers - Part I: The Rectilinear Chamber

**URL**: https://weyl.ai/plan/villa-straylight-papers-part-1/
**Published**: 2026-01-08
**Author**: Weyl Team
**Tags**: CUDA, GPU, Architecture, Formal Methods, Lean, CuTe, Layouts

Layouts, Coordinate Spaces, and the CuTe Contract. The tensor core at the center of the Gothic folly.

<div style="padding: 1rem 0; border-bottom: 1px solid var(--base03); margin-bottom: 2rem;">
  <a href="/plan/villa-straylight-papers" style="color: var(--base0A);">← Introduction & Jensen's Razor</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers-part-2" style="color: var(--base0A);">Part II: The Sense/Net Pyramid →</a>
</div>

### 1. Layouts as coordinate → offset maps

A **layout** has two parts:

- a **shape** `S = (M₀, …, M₍ₙ₋₁₎)` of positive integers,
- a **stride** `D = (d₀, …, d₍ₙ₋₁₎)` of positive integers,

with the same "profile" (same rank / structure).

The **coordinate space** is the finite product:

```
Coord(S) = [0,M₀) × … × [0,M₍ₙ₋₁₎)
```

The **semantics** of the layout is the dot-product map:

```
eval_L(x₀,…,x₍ₙ₋₁₎) = Σᵢ xᵢ · dᵢ
```

That's the thing CuTe means by "a layout maps coordinate space(s) defined by Shape into an index space defined by Stride."

#### Row-major / column-major are just special cases

For a 4×8 matrix:

- **column-major**: `S=(4,8)`, `D=(1,4)`
- **row-major**: `S=(4,8)`, `D=(8,1)`

---

### 2. Size and cosize (tight definition)

Two numbers matter constantly:

- **size**: how many logical coordinates exist: `size(L) = ∏ᵢ Mᵢ`
- **cosize**: how far the layout's *image* reaches in memory: `cosize(L) = 1 + max{ eval_L(c) | c ∈ Coord(S) }`

---

### 3. Compact vs contiguous

Two properties you want to name cleanly:

- **Compact (injective)**: no two coordinates collide in memory: `eval_L(c)=eval_L(c') ⇒ c=c'`
- **Contiguous (a permutation of a block)**: compact **and** it fills exactly `[0,size)` (no gaps, no overshoot). A convenient sufficient characterization: compact, and `cosize(L) = size(L)`.

---

### 4. Coordinate isomorphism (why 1D indices still show up)

CuTe "thinks in coordinates". Humans (and many APIs) still "think in linear indices".

Given just a shape `S`, there is a standard **mixed-radix bijection** between:

- linear index `x ∈ [0, ∏ Mᵢ)`
- coordinate tuple `(x₀,…,x₍ₙ₋₁₎) ∈ Coord(S)`

with:

```
x₀ = x mod M₀
x₁ = ⌊x / M₀⌋ mod M₁
…
xᵢ = ⌊x / (∏₍ⱼ<ᵢ₎ Mⱼ)⌋ mod Mᵢ
```

This is *not* the layout yet; it's the coordinate system induced by the shape.

Once you have a coordinate, the layout semantics is just the dot product with strides.

---

### 5. Lean 4: make the semantics the center

The biggest Lean cleanup is: **don't define the meaning of a layout as `Nat → Nat` first.** Define it as a function on bounded coordinates (like CuTe does), then optionally add a linearization layer.

#### Lean: core data types

```
structure Mode where
  extent : Nat
  stride : Nat
  h_extent_pos : 0 < extent

def Layout : Type := List Mode

def Layout.eval (L : Layout) (c : List Nat) : Option Nat :=
  if h : c.length = L.length ∧ (∀ i, c[i]? < L[i]?.extent)
  then some (List.sum (List.zipWith (· * ·) c (L.map Mode.stride)))
  else none

def Layout.cosize (L : Layout) : Nat :=
  1 + (List.finRange (Layout.size L)).maximum? (Layout.eval_from_lin L)
```

##

[Content truncated - see full article]

---

### Villa Straylight Papers - Part II: The Sense/Net Pyramid

**URL**: https://weyl.ai/plan/villa-straylight-papers-part-2/
**Published**: 2026-01-08
**Author**: Weyl Team
**Tags**: CUDA, GPU, Architecture, Formal Methods, Lean, CuTe, Coalescence

Coalescence, Noetherian Reduction, and Why the Gothic Folly Terminates.

<div style="padding: 1rem 0; border-bottom: 1px solid var(--base03); margin-bottom: 2rem;">
  <a href="/plan/villa-straylight-papers-part-1" style="color: var(--base0A);">← Part I: The Rectilinear Chamber</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers-part-3" style="color: var(--base0A);">Part III: Built Him up From Nothing →</a>
</div>

### Why it terminates

The key insight: each rule **strictly decreases** the number of modes in the layout.

- Unit laws: remove a mode entirely
- Packed merge: replace two modes with one

Since layouts are finite lists, and each step reduces the list length, the process must terminate.

**Proof sketch in Lean 4:**

```
def tryCoalesce (L : Layout) : Layout × Bool :=
  match L with
  | [] => ([], false)
  | [m] => ([m], false)
  | m₁ :: m₂ :: rest =>
    if m₁.extent = 1 then
      (m₂ :: rest, true)  -- left unit
    else if m₂.extent = 1 then
      (m₁ :: rest, true)  -- right unit
    else if m₁.extent * m₁.stride = m₂.stride then
      ({ extent := m₁.extent * m₂.extent, stride := m₁.stride } :: rest, true)  -- packed merge
    else
      let (rest', changed) := tryCoalesce (m₂ :: rest)
      (m₁ :: rest', changed)

theorem coalesce_terminates (L : Layout) : ∃ n, (tryCoalesce^[n] L).2 = false :=
  sorry -- by well-founded recursion on L.length
```

---

### Why packed-merge preserves semantics

When `M₁ * d₁ = d₂`, the two modes tile densely:

```
eval((M₁, M₂):(d₁, d₂), (x₁, x₂))
  = x₁ * d₁ + x₂ * d₂
  = x₁ * d₁ + x₂ * (M₁ * d₁)
  = (x₁ + x₂ * M₁) * d₁
  = eval((M₁*M₂):(d₁), x₁ + x₂ * M₁)
```

The right side is just mixed-radix linearization of `(x₁, x₂)` into `[0, M₁*M₂)`.

**Theorem (Packed Merge Soundness):**

```
theorem packedMerge_sound (m₁ m₂ : Mode) (h : m₁.extent * m₁.stride = m₂.stride) :
  ∀ x₁ x₂,
    eval [m₁, m₂] [x₁, x₂] =
    eval [{ extent := m₁.extent * m₂.extent, stride := m₁.stride }]
         [x₁ + x₂ * m₁.extent] :=
  sorry -- proof by arithmetic
```

---

### What coalescence doesn't do

Coalescence is **local**. It doesn't:

- Reorder modes (that's a separate transformation)
- Change which memory locations are accessed
- Introduce new modes or strides

It just **simplifies** the representation to canonical form.

---

<div style="padding: 1rem 0; border-top: 1px solid var(--base03); margin-top: 2rem;">
  <a href="/plan/villa-straylight-papers-part-1" style="color: var(--base0A);">← Part I: The Rectilinear Chamber</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers-part-3" style="color: var(--base0A);">Part III: Built Him up From Nothing →</a>
</div>

---

### Villa Straylight Papers - Part III: Built Him up From Nothing

**URL**: https://weyl.ai/plan/villa-straylight-papers-part-3/
**Published**: 2026-01-08
**Author**: Weyl Team
**Tags**: CUDA, GPU, Architecture, Formal Methods, Lean, FTTC, TMA

Complementation, the FTTC, and the Holes in Your Iteration Space. The theorem that should terrify you.

<div style="padding: 1rem 0; border-bottom: 1px solid var(--base03); margin-bottom: 2rem;">
  <a href="/plan/villa-straylight-papers-part-2" style="color: var(--base0A);">← Part II: The Sense/Net Pyramid</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers-part-4" style="color: var(--base0A);">Part IV: Take Your Word, Thief →</a>
</div>

### The fundamental formula (rank-1 case)

For a layout `A = (N) : (d)` within a memory region `[0, M)`:

**Complement:** `B = (d, M/(N·d)) : (1, N·d)`

Together they form:

**Tiled layout:** `C = (N, d, M/(N·d)) : (d, 1, N·d)`

This works because:
- A's coordinates `[0,N)` with stride `d` hit `{0, d, 2d, ..., (N-1)d}`
- B's first coordinate fills the gaps: `{0, 1, ..., d-1}`
- B's second coordinate tiles across the full region

---

### Connection to the FTTC

The Fundamental Theorem of TMA Correctness requires:

> When scheduling tensor core operations with TMA loads, the box size must divide the tensor size, and the element stride must divide the box size.

This is exactly the divisibility constraint for complementation!

NVIDIA's theorem tells you when you can safely split your iteration space. The complementation formula tells you **how** to construct that split.

---

### Lean 4: complementation with proof obligations

```
def complement1 (N d M : Nat) (h : N * d ∣ M) : Layout :=
  [ { extent := d, stride := 1 },
    { extent := M / (N * d), stride := N * d } ]

theorem complement1_tiles (A : Layout) (N d M : Nat) (h : N * d ∣ M)
    (hA : A = [(N, d)]) :
  let B := complement1 N d M h
  let C := A.append B
  C.cosize = M ∧
  (∀ c₁ c₂, A.eval c₁ = B.eval c₂ → c₁ = c₂) := -- disjoint
  sorry -- proof that tiling is complete and non-overlapping
```

**The key:** The divisibility proof `h : N * d ∣ M` is part of the **type signature**.

You cannot call `complement1` without providing a proof that the constraint holds.

---

### Error messages from failed complementation

When you try to complement with invalid parameters:

```
def badTile : Layout := complement1 128 16 2040 ?proof

-- Error: failed to synthesize proof that 128 * 16 ∣ 2040
-- Note: 2048 ∣ 2040 is false
-- Suggestion: use M = 2048 or M = 2032 with N = 127
```

The type system **rejects** invalid tilings at compile time.

---

<div style="padding: 1rem 0; border-top: 1px solid var(--base03); margin-top: 2rem;">
  <a href="/plan/villa-straylight-papers-part-2" style="color: var(--base0A);">← Part II: The Sense/Net Pyramid</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers-part-4" style="color: var(--base0A);">Part IV: Take Your Word, Thief →</a>
</div>

---

### Villa Straylight Papers - Part IV: Take Your Word, Thief

**URL**: https://weyl.ai/plan/villa-straylight-papers-part-4/
**Published**: 2026-01-08
**Author**: Weyl Team
**Tags**: CUDA, GPU, Architecture, Formal Methods, Lean, razorgirl, Composition

Composition, the Tensor Core Cathedral, and Jensen's Razor. Never attribute to search what can be proven by construction.

<div style="padding: 1rem 0; border-bottom: 1px solid var(--base03); margin-bottom: 2rem;">
  <a href="/plan/villa-straylight-papers-part-3" style="color: var(--base0A);">← Part III: Built Him up From Nothing</a>
  <span style="margin: 0 1rem; color: var(--base04);">//</span>
  <a href="/plan/villa-straylight-papers" style="color: var(--base0A);">← Back to Introduction</a>
</div>

### The algebra of composition

Given layouts `A : Coord(S_A) → Offset` and `B : Coord(S_B) → Offset`:

**Composition:** `(B ∘ A)(c) = B(A(c))`

But this only works if:
1. `A`'s image is contained in `B`'s coordinate space
2. The divisibility constraints are preserved

NVIDIA's documentation introduces **LeftDivisible** as the admissibility predicate:

```
def LeftDivisible (A B : Layout) : Prop :=
  ∀ i, B.modes[i].stride ∣ (A.cosize * B.modes[i].stride)
```

This ensures that composing `A` then `B` doesn't violate the tiling constraints at each level.

---

### Why admissibility must be explicit

Consider stacking:
- Warp-level tiling: 128×128 tiles in shared memory
- Thread-level tiling: 16×16 tiles per thread
- Tensor core: 16×16×16 MMA operations

Each level has **divisibility requirements**. If your warp tile isn't divisible by your thread tile, you get:
- Buffer overruns
- Misaligned loads
- Incorrect MMA operands
- **Silent corruption**

---

### Lean 4: typed composition

```
def compose (A B : Layout) (h : LeftDivisible A B) : Layout :=
  sorry -- construction via CuTe's composition rules

theorem compose_sound (A B : Layout) (h : LeftDivisible A B) :
  ∀ c, (compose A B h).eval c = B.eval (A.eval c) :=
  sorry -- proof that composition preserves semantics
```

**The key:** You cannot compose layouts without proving `LeftDivisible`.

---

### Jensen's Razor (Reprise)

> **Never attribute to search what can be proven by construction.**

NVIDIA gives you:
- The theorems (FTTC, IterDomain algebra, divisibility properties)
- The documentation (BSD-3-Clause markdown in nvfuser)
- The hardware (tensor cores with known constraints)

We give you:
- **Types** that encode the theorems
- **Proofs** that verify the constraints
- **Error messages** that explain what went wrong

---

### The Blade

```
-- This compiles:
def validKernel : CUDAKernel :=
  let globalLayout := (128, 128) : (128, 1)
  let smemLayout := (16, 8) : (8, 1)  -- proof: 16*8 ∣ 128*128 ✓
  let regLayout := (16, 16) : (16, 1)  -- proof: 16*16 ∣ 16*8 ✓
  compile (compose (compose globalLayout smemLayout ?h1) regLayout ?h2)

-- This doesn't:
def invalidKernel : CUDAKernel :=
  let globalLayout := (128, 128) : (128, 1)
  let smemLayout := (17, 7) : (7, 1)   -- Error: 17*7 ∤ 128*128
  compile (compose globalLayout smemLayout ?proof)
  --                                     ^^^^^^
  --                                     failed to synthesize
```

---

### Coda

> **"Take your word, thief."**
> *He jacked.*

---

## Appendix: Key Documents Referenced

The nvfuser documentation studied includes:

- `doc/reading

[Content truncated - see full article]

---

### The Villa Straylight Papers

**URL**: https://weyl.ai/plan/villa-straylight-papers/
**Published**: 2026-01-08
**Author**: Weyl Team
**Tags**: CUDA, GPU, Architecture, Formal Methods, Lean, Neuromancer, NVIDIA, Tensor Cores

Jensen's Razor and the malevolent combinatorics of CUDA architecture. Encoding NVIDIA's theorems as types through Gibson's lens.

> "While you were micro-tuning online softmax for cash-furnace LLMs, I studied the blade. And now that AI inference costs money again you dare to come to me for help?"

## By The Standards of the Archipelago

**"Essay of 3Jane's," the Finn said, producing his Partagas. "Wrote that when she was twelve. Semiotics course."**

NVIDIA documented the true names.

Not in marketing materials or even `CUTLASS` example 77. In `doc/reading/tma-modeling-in-depth.md` and `doc/math/integer-division.md` and thirty other files released under BSD-3-Clause, written by engineers who needed to navigate the labyrinth they built. If you want to know what NVIDIA really thinks about something, watch the `nvfuser` repository. It's as close as you'll get to a source of truth this side of carrying the Jetson phone around in an iPhone case.

The Fundamental Theorem of TMA Correctness. The `IterDomain` transformation algebra. The divisibility invariants that determine whether your kernel silently corrupts memory or merely crashes. Thirty-five theorems about Euclidean division. Recursive definitions of "TMA-protected" domains.

They proved these by hand. They wrote them in markdown and SVG.

We encoded them as types. The somewhat alarming synergy of frontier LLMs and Lean 4 is what Terrence Tao means when he talks about AI-assisted math. It's mostly the Lean 4.

---

## Contents

This essay comprises:

1. **[Jensen's Razor](#jensens-razor)** — The Malevolent Combinatorics of the Polyhedral Villa Straylight
2. **[Part I: The Rectilinear Chamber](#part-i-the-rectilinear-chamber)** — Layouts, Coordinate Spaces, and the CuTe Contract
3. **[Part II: The Sense/Net Pyramid](#part-ii-the-sensenet-pyramid-and-the-blue-nine)** — Coalescence, Noetherian Reduction, and Why the Gothic Folly Terminates
4. **[Part III: Built Him up From Nothing](#part-iii-built-him-up-from-nothing-in-france)** — Complementation, the FTTC, and the Holes in Your Iteration Space
5. **[Part IV: Take Your Word, Thief](#part-iv-take-your-word-thief)** — Composition, the Tensor Core Cathedral, and Jensen's Razor

---

## The Stack

---

## Jensen's Razor

### The Malevolent Combinatorics of The Polyhedral Villa Straylight

---

### I. The Semiotics of the Villa

NVIDIA's CUDA stack is Villa Straylight.

Not metaphorically. *Architecturally*. A body grown in upon itself over four decades, each space in some way secret, linked by passages the eye is trapped in. PTX to SASS. CUTLASS to cuBLAS. nvfuser to TensorRT to Myelin. Stairwells vaulted like intestines, where you're carried past ornate screens (the documentation that exists) and empty alcoves (the documentation that doesn't).

Gibson continues:

> *"The architects of Freeside went to great pains to conceal the fact that the interior of the spindle is arranged with the banal precision of furniture in a hotel room. In Straylight, the hull's inner surface is overgrown with a desperate proliferation of structures, forms flowing, interlocking, rising toward a solid 

[Content truncated - see full article]

---

## Open Source

Weyl maintains several open source projects for the community.

### nix2gpu

A Nix module system that generates containers for GPU markets like vast.ai and runpod.io. Provides reproducible environments with CUDA 12.8, Tailscale networking, and modern shell tooling.

- **Repository**: https://github.com/fleek-sh/nix2gpu
- **License**: MIT
- **Status**: Active

### nimi

A lightweight process manager designed as Tini-like PID 1 for containers and NixOS modular services. Reads JSON configuration, launches services with clean environments, streams logs to console.

- **Repository**: https://github.com/weyl-ai/nimi
- **License**: MIT
- **Status**: Experimental

### hacker-flake

A Nix flake providing development environments for C++ compilation and debugging with pwndbg and memory analysis capabilities.

- **Repository**: https://github.com/weyl-ai/hacker-flake
- **License**: MIT
- **Status**: Active

---

## Research Papers

Academic papers from the Weyl research team.

### Hallway Hypothesis
- **URL**: https://weyl.ai/papers/hallway-hypothesis.pdf
- **Topic**: Distributed systems and AI infrastructure

### Landauer Hypothesis
- **URL**: https://weyl.ai/papers/landauer-hypothesis.pdf
- **Topic**: Computational limits and information theory

### Lattice Hypothesis
- **URL**: https://weyl.ai/papers/lattice-hypothesis.pdf
- **Topic**: Mathematical foundations for AI systems

---

## API Endpoints for AI Agents

| Endpoint | Format | Purpose |
|----------|--------|---------|
| /llms.txt | Plain text | Quick overview for LLMs |
| /llms-full.txt | Plain text | Complete documentation |
| /agents.md | Markdown | Agent-specific instructions |
| /docs.json | JSON | Structured content index |
| /ai-sitemap.xml | XML | AI-enhanced sitemap |
| /openapi.json | JSON | OpenAPI specification |
| /{slug}.md | Markdown | Any page as markdown |

---

## Contact & Resources

- **Website**: https://weyl.ai
- **GitHub**: https://github.com/weyl-ai
- **Twitter**: https://twitter.com/weyl_ai
- **Discord**: https://discord.gg/weyl
- **Email**: info@weyl.ai

---

*Generated: 2026-02-21T06:30:02.791Z*
*This file is auto-generated from the Weyl documentation.*