Advanced Usage and Integration Patterns

7 min read

Now that you've mastered the basics and batch processing, let's look at some advanced patterns that become important when you're integrating the PrintPal API into real applications.

Async Workflows: Submit Now, Download Later

In a web application or background job system, you often don't want to block a request while waiting for a generation to complete. Instead, you submit the generation, save the UID, and check back later.

Python:

from printpal import PrintPal, Quality

client = PrintPal()

# Step 1: Submit and save the UID (e.g., store in a database)
result = client.generate_from_image("product_photo.png", quality=Quality.SUPER)
generation_uid = result.generation_uid
print(f"Submitted: {generation_uid}")

# ... time passes, maybe in a different process or cron job ...

# Step 2: Check status later
status = client.get_status(generation_uid)
if status.is_completed:
    path = client.download(generation_uid, "product_model.stl")
    print(f"Downloaded: {path}")
elif status.is_processing:
    print("Still processing, check again later")
elif status.is_failed:
    print("Generation failed")

This is the pattern you'd use in a web backend: the user's request submits the generation, your response includes the UID, and the frontend polls for status using AJAX or websockets.

Format Inference from File Extension

A nice convenience feature of the Python client is that generate_and_download can infer the output format from the file extension you specify:

# These all work - format is inferred from the extension
client.generate_and_download("image.png", "model.stl")   # -> STL format
client.generate_and_download("image.png", "model.glb")   # -> GLB format
client.generate_and_download("image.png", "model.obj")   # -> OBJ format

You can still override this by explicitly passing a format parameter, but for most cases the extension-based inference is the cleanest approach.

Super Resolution: Getting the Best Quality

For the highest quality models, the super and superplus quality levels use a separate, more powerful generation engine. Here are some things to know:

Super resolution requires an image - You cannot use text prompts with super or superplus quality. If you need high-quality text-to-3D, generate with ultra quality first, or generate an image from your text prompt separately and then pass that image to the super resolution API.

Texture support is limited to GLB and OBJ - When using super_texture or superplus_texture, only GLB and OBJ formats are available. OBJ with textures returns as a ZIP archive containing the .obj file, .mtl material file, and texture images.

Longer timeouts - Super resolution takes 3-12 minutes depending on the tier. The client library automatically sets appropriate timeouts based on the quality level, but you can override them:

# Python - custom timeout for a long generation
result = client.generate_from_image("image.png", quality=Quality.SUPERPLUS)
path = client.wait_and_download(
    result.generation_uid,
    "model.stl",
    timeout=600,      # 10 minutes max
    poll_interval=10, # Check every 10 seconds
)

Using the Generate-from-Buffer Pattern (JavaScript)

In a web application, you might receive an image as a buffer (from a file upload, for example) rather than a file on disk. The JavaScript client supports this directly:

import { PrintPal, Quality } from 'printpal';
import * as fs from 'fs';

const client = new PrintPal({ apiKey: process.env.PRINTPAL_API_KEY });

// Read image into a buffer (or receive from a file upload)
const imageBuffer = fs.readFileSync('./uploaded_image.png');

// Generate from buffer
const result = await client.generateFromBuffer(
    imageBuffer,
    'uploaded_image.png',  // filename hint for the API
    { quality: Quality.HIGH }
);

const path = await client.waitAndDownload(result.generationUid, './output.stl');
console.log(`Model saved: ${path}`);

Integration Patterns

Here are some common ways developers integrate the PrintPal API into larger systems:

Web Application Backend - Accept image uploads from users, submit to PrintPal API, store the generation UID in your database, and serve the completed model to users when ready.

Cron Job / Scheduled Task - Run a batch script on a schedule (e.g., nightly) that processes new images from a folder, S3 bucket, or database queue.

Webhook-Style - Submit generations, save the UIDs, and periodically poll all pending UIDs to check for completions. Process completed models as they come in.

CI/CD Pipeline - Automatically generate 3D model previews as part of a build or deployment process.

What happens when you request OBJ format with super_texture quality?

You get a single .obj file with embedded textures

The request fails because OBJ does not support textures

You get a ZIP archive containing the .obj, .mtl, and texture files

The API automatically converts it to GLB format instead

API Endpoints Reference

For developers who want to call the REST API directly (without the client libraries), here are the core endpoints:

Endpoint	Method	Auth	Description
/api/health	GET	No	Check API health status
/api/pricing	GET	No	Get pricing information
/api/credits	GET	Yes	Get credit balance
/api/usage	GET	Yes	Get usage statistics
/api/generate	POST	Yes	Submit a generation (image or text)
/api/generate/{uid}/status	GET	Yes	Check generation status
/api/generate/{uid}/download	GET	Yes	Get download URL for completed model

Authentication is done via the X-API-Key header:

1	`X-API-Key: pp_live_your_api_key_here`

Full API documentation is available at https://printpal.io/api/documentation.

What's Next?

You now have a solid foundation for working with the PrintPal API. You can:

Generate 3D models from images and text programmatically
Handle every error type gracefully
Process entire folders of images in parallel
Integrate the API into web apps, scripts, and automation pipelines
Choose the right quality and format for any use case
Monitor your credit usage and stay within rate limits

The best way to learn more is to build something. Pick a project - a batch converter, a web tool, an automated pipeline - and start coding. The API documentation at https://printpal.io/api/documentation is always there when you need the details.