Introduction to the PrintPal API
The PrintPal web app is great for generating 3D models one at a time. But what if you want to generate hundreds of models from a folder of product photos? Or build a web app that lets your customers turn their images into 3D printable objects? Or integrate 3D model generation into an automated pipeline?
That's what the API is for.
The PrintPal API gives you programmatic access to the same AI-powered 3D generation engine that powers the web app. Everything you can do on printpal.io - image-to-3D, text-to-3D, choosing quality levels, downloading in different formats - you can do through the API with code.
What Can You Build?
Here are some real-world things people build with the PrintPal API:
Batch processing - Convert an entire folder of images into 3D models overnight, without clicking a single button.
E-commerce integration - Let customers upload a photo and automatically generate a 3D model for a custom 3D-printed product.
Content pipelines - Feed AI-generated images into the 3D generation pipeline to create large libraries of printable models.
Internal tools - Build a dashboard or command-line tool that your team uses to generate models as part of a manufacturing or prototyping workflow.
Educational platforms - Integrate 3D generation into a learning management system so students can create models programmatically.
How the API Works
The API follows a simple request-response pattern built around a few core concepts:
1. Authentication - Every request includes your API key, which identifies your account and tracks your usage.
2. Credits - Each generation costs a certain number of credits depending on the quality level. You can check your balance and purchase more credits at any time.
3. Async generation - When you submit a generation request, the API returns immediately with a unique generation ID. The model is built in the background. You poll for status until it's complete, then download the result.
Here's the flow in plain English:
- You send a request with an image (or text prompt) and your desired settings
- The API responds immediately with a generation UID and an estimated time
- You check the status periodically until it says "completed"
- You download the finished 3D model file
This async pattern means your code doesn't have to sit and wait. You can submit multiple generations at once and check on them later - which is exactly how batch processing works.
The Official Client Libraries
While you can call the API directly with HTTP requests, PrintPal provides official client libraries that handle authentication, polling, error handling, and file downloads for you:
Python - pip install printpal
Best for scripts, batch processing, data pipelines, and backend services. Works with Python 3.7+.
JavaScript/TypeScript - npm install printpal
Best for Node.js backends, serverless functions, and web applications. Full TypeScript type definitions included. Works with Node.js 14+.
Both libraries provide the same core functionality:
- Submit image-to-3D and text-to-3D generation requests
- Poll for completion with configurable intervals and timeouts
- Download completed models to disk
- Check credit balances and usage statistics
- Handle all error types with specific exception classes
- Convenience methods that combine multiple steps into a single call
Throughout this course, we'll show examples in both Python and JavaScript so you can follow along in whichever language you prefer.
What You'll Need
Before we start coding, make sure you have:
- A PrintPal account at https://printpal.io/register
- Some API credits (new accounts may come with free credits, or you can purchase them at https://printpal.io/buy-credits)
- Python 3.7+ or Node.js 14+ installed on your computer
- A terminal or command prompt you're comfortable using
- An image file (PNG, JPG, or WebP) you'd like to convert to 3D
If you've never used a terminal or written code before, this course may be challenging. We recommend starting with our "3D Design with AI" course first, which teaches you how to use the web app.