Quickstart · Printy3D

1. Create an account and a key#

Sign up. You get a personal Printy3D account; there is nothing else to set up.
Open the console. A new account shows waiting for approval: the Printy3D team reviews every account before it runs live GPU jobs. You do not need to wait to start building.
Choose Create key, mode Test, access Run jobs. Copy the secret (p3d_test_…): it is shown once. Keep it in an environment variable, never in source code.

2. Upload a model#

Uploads go straight to storage. You reserve the file with its name, size and SHA-256, PUT the bytes to the presigned URL with the headers you were given, then complete the file. This simple upload takes files up to 10 MiB; larger files use the resumable upload.

export PRINTY3D_API_KEY=p3d_test_...   # from the console
API=https://printy3d-api-staging.onrender.com
FILE=model.stl
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA=$(sha256sum "$FILE" | cut -d' ' -f1)   # macOS: shasum -a 256

# 1. Reserve the file: you get a File and a presigned upload.
curl -sS "$API/v1/files" \
  -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"filename\": \"$FILE\", \"size_bytes\": $SIZE, \"sha256\": \"$SHA\"}" \
  > reserved.json

# 2. PUT the bytes to storage with the returned headers (no API key here).
H=(); while IFS= read -r line; do H+=(-H "$line"); done \
  < <(jq -r '.upload.headers | to_entries[] | "\(.key): \(.value)"' reserved.json)
curl -sS -T "$FILE" "${H[@]}" "$(jq -r .upload.url reserved.json)"

# 3. Complete it: the API checks the bytes and answers ready or rejected.
FILE_ID=$(jq -r .file.id reserved.json)
curl -sS -X POST "$API/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $PRINTY3D_API_KEY" | jq '{id, status, kind, rejected_reason}'

A ready file can be used by jobs. A rejected one carries a rejected_reason, for example obj_materials_unsupported for an OBJ that names materials: upload a ZIP with the OBJ, its MTL and its textures instead.

3. Run an inspect job#

inspect analyses the model and renders thumbnails and a preview (with a test key: simulated values and placeholder images). Create the job, then poll it until it reaches a final state.

# Start an inspect job on the ready file.
curl -sS "$API/v1/jobs" \
  -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"input_file_id\": \"$FILE_ID\", \"recipe\": \"inspect\"}" > job.json
JOB_ID=$(jq -r .id job.json)

# Poll every 2 seconds until the job is succeeded, failed or cancelled.
while :; do
  STATUS=$(curl -sS "$API/v1/jobs/$JOB_ID" -H "Authorization: Bearer $PRINTY3D_API_KEY" \
    | tee job.json | jq -r .status)
  echo "$STATUS"
  case "$STATUS" in succeeded|failed|cancelled) break;; esac
  sleep 2
done
jq '.analysis | {dimensions_mm, volume_mm3, is_watertight, shells}' job.json

4. Download the outputs#

A succeeded job lists its artifacts. Each download link is temporary: ask for a new one when you need it, and check the bytes against the artifact's sha256.

# List the artifacts, then fetch a temporary URL for one of them.
curl -sS "$API/v1/jobs/$JOB_ID/artifacts" -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  | jq -r '.data[] | "\(.id)  \(.label)  \(.media_type)  \(.size_bytes)"'

ART_ID=$(curl -sS "$API/v1/jobs/$JOB_ID/artifacts" -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  | jq -r '.data[] | select(.label == "preview") | .id')
URL=$(curl -sS "$API/v1/artifacts/$ART_ID/download" \
  -H "Authorization: Bearer $PRINTY3D_API_KEY" | jq -r .url)
curl -sS -o preview.glb "$URL"

5. Repair it#

Change the recipe to repair to get a print-ready mesh. With no params, every setting comes from the engine's recommendation for your file; the Repair page explains each one.

curl -sS "$API/v1/jobs" \
  -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"input_file_id\": \"$FILE_ID\", \"recipe\": \"repair\", \"params\": {\"printer\": \"fdm\"}}"

Credits#

Once your account is approved, the console shows your credits. A live job holds credits while it runs and is charged its run time when it finishes (1 credit = 1 second of GPU run time); queue time is free. Credits & billing