PrintPal 3D Model Generator

Generate 3D models from images or text prompts for 3D printing.

Quick Start

From an image path or URL:

python3 {baseDir}/scripts/generate_3d.py --image /path/to/image.png

From text prompt:

python3 {baseDir}/scripts/generate_3d.py --prompt "a cute robot toy"

Installation

Required Python packages:

pip install printpal requests

For text-to-image and SEO features:

pip install wavespeed

Configure API keys in your OpenClaw settings (~/.openclaw/openclaw.json under env):

• PRINTPAL_API_KEY - required for 3D generation
• WAVESPEED_API_KEY - for text-to-image and product photos
• OPENROUTER_API_KEY - for SEO metadata generation

Workflow

1. Get the image:

   • If user provides a file path → use it directly
   • If user provides a URL → download it
   • If user pastes an image → use it directly (it will be available as a file path or URL in context)
   • If user provides text → generate image via WaveSpeed first

2. Generate 3D model:

   • Use PrintPal API with super quality (768 cubed)
   • Default output format: STL
   • Save to printpal-output/ directory in workspace

3. Provide downloads:

   • Start file server if needed
   • Return clickable URLs

Default Settings

Setting	Default	Options
Quality	super	default, high, ultra, super, super_texture, superplus, superplus_texture
Format	stl	stl, glb, obj, ply, fbx

Scripts

generate_3d.py

Main script for generating 3D models.

python3 scripts/generate_3d.py [OPTIONS]

Options:
  -i, --image PATH      Input image file path or URL
  -p, --prompt TEXT     Text prompt (uses WaveSpeed to generate image first)
  -q, --quality TEXT    Quality level (default: super)
  -f, --format TEXT     Output format (default: stl)
  -o, --output-dir DIR  Output directory
  --json                Output results as JSON

serve_files.py

Start HTTP server for file downloads.

python3 scripts/serve_files.py [OPTIONS]

Options:
  -d, --directory DIR   Directory to serve (default: printpal-output/)
  -p, --port PORT       Port number (default: 8765)
  --host HOST           Host to bind to (default: 127.0.0.1)
  --public              Bind to 0.0.0.0 to allow network access
  --url-only            Just print URL without starting server

Quality Levels

Quality	Resolution	Credits	Est. Time
default	256³	4	20 sec
high	384³	6	30 sec
ultra	512³	8	60 sec
super	768³	20	3 min
superplus	1024³	30	4 min

Output Formats

Format	Best For
STL	3D printing (default)
GLB	Web/games
OBJ	Universal compatibility
PLY	Point clouds
FBX	Autodesk software

API Keys

Required environment variables (configure in ~/.openclaw/openclaw.json under env):

• PRINTPAL_API_KEY - Get from https://printpal.io/api-keys (required for 3D generation)
• WAVESPEED_API_KEY - Get from https://wavespeed.ai/accesskey (optional, for text-to-image)
• OPENROUTER_API_KEY - Get from https://openrouter.ai/keys (optional, for SEO generation)

Output Directory

Default output is printpal-output/ in the skill's workspace. Override with:

• Environment variable: PRINTPAL_OUTPUT_DIR=/path/to/output
• Command option: --output-dir /path/to/output

Security Notes

• File server: The serve_files.py script binds to localhost (127.0.0.1) only. Use --host 0.0.0.0 if you need network access, but be aware this exposes the server to your network.
• Third-party packages: Scripts import printpal, wavespeed, and requests packages. Review these packages before installing.
• Downloaded content: The skill downloads images from user-supplied URLs. Treat as untrusted input.

Error Handling

Error	Solution
WAVESPEED_API_KEY not set	Provide image directly or configure API key
PRINTPAL_API_KEY not set	Configure in OpenClaw settings
Insufficient credits	Purchase at printpal.io/buy-credits
Package not installed	Run pip install printpal wavespeed

---

SEO Product Listing Generator

Generate SEO-optimized metadata and product photos for selling 3D models/prints on marketplaces like Etsy, TikTok Shop, etc.

Quick Start

python3 scripts/seo_product_photos.py \
  --image /path/to/model_photo.jpg \
  --description "A cute dragon figurine" \
  --purpose "Collectible toy for fantasy fans" \
  --audience "Fantasy enthusiasts, collectors, parents buying for kids"

Workflow

1. Input: User provides an image of their 3D model/print + description, purpose, and target audience
2. SEO Generation: OpenRouter MiniMax generates optimized title, description, tags
3. Photo Generation: WaveSpeed nano-banana/edit creates 5 polished product photos
4. Output: ZIP file with metadata + photos, served via local HTTP server

Required Environment Variables

# OpenRouter (for SEO generation)
OPENROUTER_API_KEY=your_openrouter_key

# WaveSpeed (for product photos)
WAVESPEED_API_KEY=your_wavespeed_key

Get OpenRouter key: https://openrouter.ai/keys Get WaveSpeed key: https://wavespeed.ai/accesskey

Options

Option	Short	Description	Default
--image	-i	Path or URL to input image	(required)
--description	-d	Description of the 3D model/print	(required)
--purpose	-p	What the item is for/its use	(required)
--audience	-a	Target audience/customers	(required)
--num-photos	-n	Number of photos to generate	5
--port	-	Download server port	8766
--json	-	Output results as JSON	false

Output

The script generates:

• seo_metadata.txt - Full metadata (title, description, tags, features, etc.)
• product_photo_01.png through product_photo_05.png - Generated product photos
• seo_product_listing.zip - All files packaged for download

Download URL is provided at the end (e.g., http://hostname:8766/seo_product_listing.zip)

SEO Metadata Fields

The generated metadata includes:

• title: Full SEO title (max 140 chars, keywords included)
• short_title: Catchy thumbnail title (max 40 chars)
• description: Detailed listing description (500-1000 words)
• tags: 15 optimized tags for search
• category: Primary marketplace category
• search_terms: 5 high-value search terms
• key_features: 4 key product features
• target_marketplace: Recommended platform

Example

python3 scripts/seo_product_photos.py \
  --image /workspace/my_mug_holder.jpg \
  --description "A custom 3D printed mug holder with dragon design" \
  --purpose "Keeps mugs organized on desk or kitchen, great gift" \
  --audience "Office workers, coffee lovers, home office enthusiasts"

Troubleshooting

Error	Solution
OPENROUTER_API_KEY not set	Configure in OpenClaw settings
Photo generation fails	Check WAVESPEED_API_KEY and credits
Port in use	Use --port to specify different port

Reference

For detailed API documentation, see api-reference.md. For Bambu Lab printer control (printing generated models, monitoring, hardware management), see bambu-printer-guide.md.

---

Bambu Lab Printer Integration (Reference Guide)

This section documents how to use the separate @versatly/bambu CLI to send PrintPal-generated models to Bambu Lab printers. This skill does not include built-in printer integration code — you must install and configure the Bambu CLI yourself.

Prerequisites

• Install the CLI: npm i -g @versatly/bambu
• Printer in Developer Mode (Settings → LAN Only → Enable Developer Mode)
• One-time setup: bambu setup <ip> <serial> <access_code>

When to Use

Use the bambu CLI when the user wants to:

• Send a generated model to the printer
• Monitor an active print job
• Check printer status, temperatures, or filament info
• Control the printer hardware (fans, lights, movement)
• Run calibration routines

Quick Reference

# Upload and start printing a generated model
bambu job upload-and-print ./printpal-output/model.3mf

# Monitor until done
bambu watch

# Check printer readiness
bambu status --json | jq '.gcode_state'
# IDLE = ready, RUNNING = busy, FAILED = needs attention

Typical End-to-End Flow

1. Generate model via PrintPal → output lands in printpal-output/
2. Upload to printer: bambu job upload-and-print <file>
3. Monitor: bambu watch or bambu status
4. When done: bambu cooldown && bambu light off

For full command reference, temperature presets, AMS management, calibration, and troubleshooting, see bambu-printer-guide.md.