Print-Ready Agent Workflows
How agents check a file, make a verified production file at a physical size, and keep logos and products exact.
Check first, then make the production file
designgen_print_prep has three entry points. Pick by what the user needs.
- preflight (free): DPI at the print size, the largest size the file holds at 300 DPI, transparency, color count, edge halos, thin lines, and DTF press checks. Pass garmentColors ("black", "navy") to catch ink that disappears on the blank. Run it on every customer file before production and show the user the summary.
- print_file: the production path. A transparent 600-DPI PNG at targetWidthIn (max 24 in), plus an SVG when the artwork is a vector fit, made by an Operator run. Pass idempotencyKey so a timed-out retry returns the same run instead of paying twice. Poll designgen_operator operation get by replaying nextCall, then fetch production_package.
- prepare: a quick cleanup (background removal, upscale, vectorize via flags) when no physical size is involved. It does not verify a print size.
Following a run: wait, do not guess
A print-file fix spends most of its time inside one step. Step counts standing still is normal and is not evidence of a stall.
- Replay nextCall. It carries waitSeconds, so each call holds open for up to 55 seconds and returns the moment the run moves. Never sleep between polls, and never start a second run for the same job.
- Read heartbeatAt / heartbeatAgeSeconds, substep and etaSeconds when you report progress to the user: "still upscaling, about two minutes left" beats "step 2 of 11" repeated four times.
- A run is only stuck when get returns stalled: true (no worker has touched it for longer than stalledAfterSeconds). Then tell the user and offer the cancel operation; the watchdog also stops and refunds lost runs on its own.
- creditsUsed on get and production_package is what the run has actually spent; creditEstimate on the start result is the range to quote before it begins.
Use reference files deliberately
For apparel and logo fidelity, pass each important reference as a separate reference image with role metadata.
- Use role=logo for exact customer logo assets.
- Use role=product for garment or product photos that should drive color and shape accuracy.
- Use role=style or role=layout for inspiration that should not override logos or product references.
Never overclaim
A production_package with ready: true passed mechanical checks; the artwork still needs a human look.
- If production_package returns needs_review, show its warnings and do not call the files print-ready.
- Read skipped[] before you describe the delivery: gradient-heavy artwork ships as an upscaled PNG with no SVG, and that is the right call, not a failure.
- Show reviewCrops (the risk areas at 100%) and the previewUrl rather than claiming fidelity you have not seen; the download link is short-lived and named, so give it to the user rather than storing it.
- Use Ultra Max (High detail for small type) when small details, logo fidelity, or final customer-facing artwork matter; the Ultra default suits polished previews, and Light or Standard suit drafts.