AssetMax

Manifest-driven asset management with multi-model AI generation

AssetMax generates assets from TOML manifests using 9 AI models with automatic cost optimization and TypeScript type generation.

Installation

npm install -g assetmax

Quick Start

# Set API token
export REPLICATE_API_TOKEN="your_token_here"

# Initialize project
assetmax init

# Generate assets
assetmax generate --dry-run  # Preview costs
assetmax generate            # Generate all assets

Commands

Core Commands

# Initialize new project
assetmax init [options]
  -n, --name <name>           Project name
  -t, --template <template>   Template (react, nextjs, vue)
  --typescript               Use TypeScript (default: true)
  --base-url <url>           Assets base URL (default: /assets)

# Compile TOML manifest to TypeScript
assetmax compile [options]
  -i, --input <file>         Input manifest (default: asset-manifest.toml)
  -o, --output <file>        Output TypeScript file

# Generate assets from manifest
assetmax generate [options]
  -i, --input <file>         Input manifest (default: asset-manifest.toml)
  --dry-run                  Preview generation without creating assets
  --force                    Regenerate existing assets

# Validate manifest
assetmax validate [options]
  -i, --input <file>         Input manifest (default: asset-manifest.toml)

# Build pipeline (compile + generate + verify)
assetmax build [options]
  --skip-generation          Skip asset generation
  --force                    Force regeneration

Model Commands

# List all available AI models
assetmax list

# Model management
assetmax model list                    # Same as assetmax list
assetmax model help <model>            # Detailed model information
assetmax model cost <model> <count>    # Calculate generation costs
assetmax model params <model>          # Show model parameters

# Examples
assetmax model help flux-schnell       # Get info about FLUX Schnell
assetmax model cost recraft-v3 10      # Cost for 10 assets with Recraft V3
assetmax model params ideogram-v3-turbo # Show supported parameters

Placeholder Generation

Generate intelligent placeholders for assets defined in your manifest:

# Generate placeholders for all assets
assetmax placeholder --all

# Generate placeholders for specific asset group
assetmax placeholder --group branding

# Generate placeholder for specific asset
assetmax placeholder --asset primary_logo

# Preview what would be generated (dry run)
assetmax placeholder --all --dry-run

# Override dimensions while maintaining aspect ratio
assetmax placeholder --all --width 600
assetmax placeholder --group social --height 400

# Different placeholder styles
assetmax placeholder --all --style wireframe   # Default: dashed border
assetmax placeholder --all --style solid       # Solid background
assetmax placeholder --all --style branded     # Blue branded style

Smart Features:

• Automatically converts aspect ratios (1:1, 16:9, 4:3) to optimal pixel dimensions
• Creates proper directory structure matching your manifest
• Shows asset name, category, dimensions, and prompt preview on placeholder
• Maintains aspect ratios when overriding dimensions
• Generates SVG files that can be easily converted to PNG/JPG

Asset Verification

Check your manifest and assets for errors:

# Verify asset configuration and files
assetmax verify

# Automatically fix common issues
assetmax verify --fix

# Verify specific manifest file
assetmax verify -i custom-manifest.toml

Template Commands

# List available templates
assetmax template list

# Create from template
assetmax template create <template> [options]
  -n, --name <name>          Project name

Manifest Generation

# Generate manifest from existing assets
assetmax generate-manifest [options]
  -d, --assets-dir <dir>     Assets directory to scan
  -f, --assets-file <file>   Existing assets.ts file to parse
  -n, --name <name>          Project name
  -o, --output <file>        Output manifest file
  --base-url <url>           Base URL for assets

Multi-Model System

AssetMax supports 9 AI models with automatic cost optimization.

Model Discovery

# List all available models with costs
assetmax list

# Get detailed info about a specific model
assetmax model help flux-schnell

# Check model parameters and supported formats
assetmax model params recraft-v3

# Calculate costs before generating
assetmax model cost seedream-3 5

Available Models

# Fast & economical
flux-schnell         # $0.003 - Fastest generation
imagen-4-fast        # $0.02  - Google's fast model

# Best quality  
seedream-3           # $0.03  - Best overall with text rendering
flux-pro             # $0.04  - Premium FLUX quality

# Specialized
ideogram-v3-turbo    # $0.03  - Best for text-heavy assets
recraft-v3           # $0.04  - Best for brand assets
recraft-v3-svg       # $0.08  - Vector graphics/logos

# High-end
stable-diffusion-3.5-large  # $0.065 - Premium quality

Example Model Discovery

assetmax list

Output:

🤖 Available AI Models

📋 Fastest Models:
   FLUX Schnell              $0.003 - Fastest FLUX variant optimized for speed

📋 Economical Models:
   Imagen 4 Fast             $0.020 - Google's fast model
   Seedream 3                $0.030 - Best overall with text rendering
   Ideogram V3 Turbo         $0.030 - Best for text-heavy assets

📋 Premium Models:
   FLUX 1.1 Pro              $0.040 - Premium FLUX quality
   Recraft V3                $0.040 - Best for brand assets

📋 Specialized Models:
   Recraft V3 SVG            $0.080 - Vector graphics/logos
   Stable Diffusion 3.5      $0.065 - Premium quality

Cost Optimization Example

assetmax generate --dry-run

Output:

📊 Summary:
   Total assets: 16
   Estimated cost: $0.469
   Models:
     recraft-v3: 3 assets ($0.120)      # Premium branding
     seedream-3: 3 assets ($0.090)      # Social cards  
     flux-pro: 4 assets ($0.160)        # Documentation
     ideogram-v3-turbo: 3 assets ($0.090) # Text features
     flux-schnell: 3 assets ($0.009)    # Simple badges

Manifest Configuration

Create asset-manifest.toml:

[meta]
name = "My Project"
version = "1.0.0"
description = "Project assets"
base_url = "/assets"

[categories.branding]
path = "branding"
type = "image"
formats = ["png", "svg"]

[build]
output_dir = "assets"
output_file = "generated-assets.ts"
type_definitions = true

[cli]
output_dir = "generated"

# Model selection per asset group
[assets.logos]
description = "Brand logos"
category = "branding"
format = "png"
generation_model = "recraft-v3"    # Best for logos
aspect_ratio = "1:1"

[assets.logos.primary_logo]
prompt = "Modern minimalist logo for tech company"
alt = "Company logo"

[assets.social_cards]
description = "Social media cards"
category = "social"
format = "png"
generation_model = "seedream-3"    # Best text rendering
aspect_ratio = "16:9"

[assets.social_cards.og_card]
prompt = "Open Graph card with company branding"
alt = "Social media card"

[assets.badges]
description = "Status badges"
category = "branding"
format = "png"
generation_model = "flux-schnell"  # Cheapest for simple graphics
aspect_ratio = "21:9"

[assets.badges.build_status]
prompt = "Green 'Build: Passing' status badge"
alt = "Build status"

Generated TypeScript

AssetMax compiles your manifest to type-safe TypeScript:

// assets/generated-assets.ts (auto-generated)
export const logos = {
  primaryLogo: {
    src: '/assets/branding/primary_logo.png',
    fallback: '/fallback.png',
    alt: 'Company logo',
    aspectRatio: '1:1',
    _meta: {
      prompt: 'Modern minimalist logo for tech company',
      model: 'recraft-v3',
      cost: 0.04
    }
  }
};

export const socialCards = {
  ogCard: {
    src: '/assets/social/og_card.png',
    fallback: '/fallback.png', 
    alt: 'Social media card',
    aspectRatio: '16:9',
    _meta: {
      prompt: 'Open Graph card with company branding',
      model: 'seedream-3',
      cost: 0.03
    }
  }
};

Usage in Code

import { logos, socialCards } from './assets/generated-assets';

// React component
function Header() {
  return (
    <img 
      src={logos.primaryLogo.src}
      alt={logos.primaryLogo.alt}
      onError={(e) => e.target.src = logos.primaryLogo.fallback}
    />
  );
}

// Next.js meta tags
export const metadata = {
  openGraph: {
    images: [socialCards.ogCard.src]
  }
};

API Token Setup

Get your token from Replicate:

# Method 1: Export environment variable
export REPLICATE_API_TOKEN="r8_your_token_here"

# Method 2: Create .env file
echo "REPLICATE_API_TOKEN=r8_your_token_here" > .env

# Method 3: Add to shell profile (persistent)
echo 'export REPLICATE_API_TOKEN="r8_your_token_here"' >> ~/.bashrc
source ~/.bashrc

Model Selection Strategy

Choose models based on asset type:

# Logos & Brand Assets → Use recraft-v3 or recraft-v3-svg
[assets.logos]
generation_model = "recraft-v3"        # Best brand quality

# Social Media Cards → Use seedream-3 or ideogram-v3-turbo  
[assets.social]
generation_model = "seedream-3"        # Best text rendering

# Documentation → Use flux-pro or stable-diffusion-3.5-large
[assets.docs] 
generation_model = "flux-pro"          # High quality

# Simple Graphics → Use flux-schnell or imagen-4-fast
[assets.badges]
generation_model = "flux-schnell"      # Fastest/cheapest

Aspect Ratios

Supported aspect ratios by model:

# Universal (all models)
1:1, 16:9, 9:16, 4:3, 3:4

# Extended support (most models)  
3:2, 2:3, 4:5, 5:4, 21:9, 9:21, 2:1, 1:2

# SVG models
recraft-v3-svg supports all ratios

Troubleshooting

Common Issues

# API token not found
export REPLICATE_API_TOKEN="your_token"

# Invalid aspect ratio
# Check model supports the ratio in dry-run mode

# Model execution failed  
# Verify API token and model availability

# Permission denied
chmod +x node_modules/.bin/assetmax

Debug Mode

# Verbose output
assetmax generate --dry-run  # See costs and models
assetmax validate            # Check manifest validity

Templates

React Template

assetmax init --template react --name my-react-app

Creates:

• asset-manifest.toml with React-optimized settings
• src/assets/ directory structure
• TypeScript definitions
• Component usage examples

Next.js Template

assetmax init --template nextjs --name my-next-app

Creates:

• Next.js-specific asset paths
• Metadata integration
• Public directory setup
• Image optimization config

Programmatic Usage

import { AssetCLI, AssetCompiler } from 'assetmax';

// Generate assets programmatically
const cli = new AssetCLI();
await cli.run({
  manifestFile: 'asset-manifest.toml',
  dryRun: false,
  force: false
});

// Compile manifest
const compiler = new AssetCompiler();
await compiler.compile('asset-manifest.toml', 'assets/generated.ts');

Performance

• Generation time: 10-60 seconds per asset depending on model
• Cost range: $0.003-$0.08 per asset
• Batch optimization: Automatic model selection minimizes costs
• Caching: Skips existing assets unless forced

License

MIT

Install: npm install -g assetmax