printpal 1.0.4

Python client for the PrintPal 3D Generation API

PrintPal Python Client

AI-Powered Image to 3D Model Generation for 3D Printing

Website | API Docs | Get API Key | Buy Credits

---

The official Python client for the PrintPal 3D Generation API. Convert images and text into high-quality, print-ready 3D models using state-of-the-art AI technology.

Perfect for:

• 3D Printing Businesses automating custom model creation
• E-commerce Platforms offering personalized 3D printed products
• Game Developers generating 3D assets from concept art
• Product Designers rapidly prototyping from sketches
• Makers and Creators bringing ideas to life
• Manufacturing Companies streamlining CAD model generation

Why PrintPal?

• Image to 3D in Seconds: Convert any image into a printable 3D model
• Text to 3D: Describe what you want and get a 3D model
• Print-Ready Formats: Export directly to STL, OBJ, GLB, PLY, or FBX
• Multiple Quality Tiers: From quick previews to ultra-high resolution (1024 cubed)
• Texture Support: Generate textured models for realistic renders
• Simple API: Get started with just a few lines of code
• Scalable: Process thousands of models programmatically

Installation

pip install printpal

Or install from source:

git clone https://github.com/printpal-io/printpal-python.git
cd printpal-python
pip install -e .

Quick Start

1. Get Your API Key

Sign up at printpal.io and get your API key from the API Keys dashboard.

2. Set Your API Key

Set your API key as an environment variable:

export PRINTPAL_API_KEY="pp_live_your_api_key_here"

Or pass it directly to the client:

from printpal import PrintPal

client = PrintPal(api_key="pp_live_your_api_key_here")

Note: You can also use PrintPalClient or printpal as aliases if you prefer.

3. Generate a 3D Model

from printpal import PrintPal

# Initialize client
client = PrintPal()

# Generate a 3D model from an image (simplest method)
output_path = client.generate_and_download(
    image_path="my_image.png",
    output_path="my_model.stl"
)

print(f"3D model saved to: {output_path}")

Features

• Image to 3D model generation
• Text to 3D model generation
• Multiple quality levels (default, high, ultra, super, superplus)
• Multiple output formats (STL, GLB, OBJ, PLY, FBX)
• Texture support for high-resolution models
• Async/polling-based workflow for long-running generations
• Credit balance and usage tracking
• Comprehensive error handling

Usage Examples

Basic Image to 3D

from printpal import PrintPal, Quality, Format

client = PrintPal()

# One-liner: generate and download
path = client.generate_and_download("image.png", "model.stl")

Step-by-Step Generation

For more control over the process:

from printpal import PrintPal, Quality, Format

client = PrintPal()

# Step 1: Submit generation request
result = client.generate_from_image(
    image_path="my_image.png",
    quality=Quality.DEFAULT,
    format=Format.STL,
)

print(f"Generation UID: {result.generation_uid}")
print(f"Estimated time: {result.estimated_time_seconds} seconds")

# Step 2: Wait for completion
status = client.wait_for_completion(result.generation_uid)

# Step 3: Download the model
if status.is_completed:
    path = client.download(result.generation_uid, "my_model.stl")
    print(f"Downloaded to: {path}")

High-Resolution Generation

Generate ultra-high-quality models with super resolution:

from printpal import PrintPal, Quality, Format

client = PrintPal()

# Super resolution (768 cubed) - geometry only
result = client.generate_from_image(
    image_path="my_image.png",
    quality=Quality.SUPER,
    format=Format.STL,
)

# Super+ resolution (1024 cubed) - highest quality
result = client.generate_from_image(
    image_path="my_image.png",
    quality=Quality.SUPERPLUS,
    format=Format.STL,
)

# With textures (GLB or OBJ only)
result = client.generate_from_image(
    image_path="my_image.png",
    quality=Quality.SUPERPLUS_TEXTURE,
    format=Format.GLB,
)

Text to 3D

Generate 3D models from text descriptions:

from printpal import PrintPal, Quality, Format

client = PrintPal()

result = client.generate_from_prompt(
    prompt="a cute robot toy",
    quality=Quality.HIGH,
    format=Format.GLB,
)

path = client.wait_and_download(result.generation_uid, "robot.glb")

Note: Text to 3D is only available for default, high, and ultra quality levels.

Check Credits

from printpal import PrintPal

client = PrintPal()

# Get credit balance
credits = client.get_credits()
print(f"Available credits: {credits.credits}")

# Get pricing info
pricing = client.get_pricing()
for name, tier in pricing.credits.items():
    print(f"{name}: {tier.cost} credits")

Async/Polling Workflow

For long-running generations or web applications:

from printpal import PrintPal, Quality

client = PrintPal()

# Submit and get the UID
result = client.generate_from_image("image.png", quality=Quality.SUPER)
uid = result.generation_uid

# Save UID somewhere (database, file, etc.)
print(f"Started generation: {uid}")

# Later, check status
status = client.get_status(uid)
if status.is_completed:
    client.download(uid, "model.stl")
elif status.is_processing:
    print("Still processing...")
elif status.is_failed:
    print("Generation failed")

With Progress Callback

from printpal import PrintPal

client = PrintPal()

def on_status(status):
    print(f"Status: {status.status}")

result = client.generate_from_image("image.png")
path = client.wait_and_download(
    result.generation_uid,
    output_path="model.stl",
    callback=on_status,
)

Context Manager

from printpal import PrintPal

with PrintPal() as client:
    credits = client.get_credits()
    print(f"Credits: {credits.credits}")

Quality Levels

Quality	Resolution	Credits	Est. Time	Texture Support
default	256 cubed	4	20 sec	No
high	384 cubed	6	30 sec	No
ultra	512 cubed	8	60 sec	No
super	768 cubed	20	3 min	No
super_texture	768 cubed	40	6 min	Yes
superplus	1024 cubed	30	4 min	No
superplus_texture	1024 cubed	50	12 min	Yes

Output Formats

Format	Extension	Description	Availability
STL	.stl	3D printing format	All quality levels
GLB	.glb	Binary glTF (web/games)	All quality levels
OBJ	.obj	Wavefront OBJ	All quality levels
PLY	.ply	Polygon file format	default, high, ultra
FBX	.fbx	Autodesk FBX	super, superplus only

Note: Texture generation (super_texture, superplus_texture) only supports GLB and OBJ formats. OBJ with texture returns as a ZIP archive containing the .obj, .mtl, and texture files.

Error Handling

from printpal import (
    PrintPal,
    AuthenticationError,
    InsufficientCreditsError,
    ValidationError,
    GenerationError,
    NotFoundError,
    RateLimitError,
)

client = PrintPal()

try:
    result = client.generate_from_image("image.png")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError as e:
    print(f"Not enough credits. Need {e.credits_required}, have {e.credits_available}")
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except GenerationError as e:
    print(f"Generation failed: {e}")
except NotFoundError:
    print("Resource not found")

API Reference

PrintPal

The main client class for interacting with the PrintPal API.

Aliases: PrintPalClient, printpal (for those who prefer different naming conventions)

Constructor

PrintPal(
    api_key: str = None,      # API key (or set PRINTPAL_API_KEY env var)
    base_url: str = "https://printpal.io",  # API base URL
    timeout: int = 60,        # Request timeout in seconds
)

Methods

Method	Description
get_credits()	Get current credit balance
get_pricing()	Get API pricing information
get_usage()	Get API usage statistics
health_check()	Check API health status
generate_from_image()	Submit image for 3D generation
generate_from_prompt()	Submit text prompt for 3D generation
get_status()	Get generation status
get_download_url()	Get presigned download URL
download()	Download completed model
wait_for_completion()	Poll until generation completes
wait_and_download()	Wait and download in one call
generate_and_download()	Generate and download in one call

Quality Enum

from printpal import Quality

Quality.DEFAULT        # 256 cubed, 4 credits
Quality.HIGH           # 384 cubed, 6 credits
Quality.ULTRA          # 512 cubed, 8 credits
Quality.SUPER          # 768 cubed, 20 credits
Quality.SUPER_TEXTURE  # 768 cubed + texture, 40 credits
Quality.SUPERPLUS      # 1024 cubed, 30 credits
Quality.SUPERPLUS_TEXTURE  # 1024 cubed + texture, 50 credits

Format Enum

from printpal import Format

Format.STL  # .stl
Format.GLB  # .glb
Format.OBJ  # .obj
Format.PLY  # .ply
Format.FBX  # .fbx (super/superplus only)

Example Scripts

The examples/ directory contains ready-to-run scripts:

Script	Description
basic_generation.py	Simple image to 3D
high_quality_generation.py	Super resolution generation
batch_generation.py	Process multiple images
text_to_3d.py	Generate from text prompts
check_credits.py	Check balance and pricing
async_generation.py	Submit/check/download workflow

Run any example:

export PRINTPAL_API_KEY="pp_live_your_api_key_here"
python examples/basic_generation.py path/to/image.png

Rate Limits

• 50 requests per minute per API key
• 10,000 requests per day per account
• 5 concurrent generations maximum

Use Cases

3D Printing Services

Automate custom 3D model creation for your print-on-demand business. Accept customer images and automatically generate print-ready STL files.

E-commerce Product Customization

Let customers upload images and receive custom 3D printed products. Perfect for personalized gifts, figurines, and merchandise.

Game Development and Digital Assets

Convert concept art and sketches into 3D game assets. Generate low-poly to high-poly models with or without textures.

Rapid Prototyping

Transform product sketches and designs into 3D prototypes. Accelerate your design-to-print workflow.

Educational and Maker Projects

Build applications that help students and makers bring their creative ideas into the physical world through 3D printing.

Manufacturing and CAD

Streamline CAD model generation from reference images. Integrate with your existing manufacturing pipeline.

Support

• Email: [e-mail]
• Documentation: https://printpal.io/api/documentation
• Issues: https://github.com/printpal-io/printpal-python/issues

License

MIT License. See LICENSE for details.

---

PrintPal: AI 3D Model Generation API for 3D Printing
Image to 3D | Text to 3D | STL Generator | 3D Printing API | AI 3D Modeling

printpal.io