Saving & retrieving outputs

Understand temporary generation, optional private saved artifacts and later downloads. Saving media is a separate request from generating it.

On this page

Generate, save, retrieve
Save a supported artifact
List, download and delete
Retention and safe recovery

Generate, save, retrieve

PDF and code generation return transient output bytes. Image transformations follow their requested storage mode. Download those bytes into your application, or explicitly Save a supported output to a project artifact. The Customer Outputs library brings saved media together.

Saving consumes storage, not another generation credit. Later downloads consume bandwidth. Feature entitlements, active-project ownership, rate limits and available capacity still apply. A saved file has no anonymous public URL or customer signed delivery URL.

Save a supported artifact

POST multipart data to /v1/projects/{projectId}/tools/artifacts. Send one file and the fields below; duplicates and unknown fields are rejected. This route does not use the original-image upload X-Upload-Length contract. Do not manually set the multipart boundary.

Field	Meaning
`file`	Required output bytes; real file type is validated.
`kind`	qr \| barcode \| pdf_render \| pdf_merge \| pdf_extract \| image_transform
`displayName`	Required non-empty label; trimmed, control characters removed and truncated to 255 characters. Not an object key.
`contentType`	Send the actual MIME type, matching the kind and file.
`requestSnapshot`	Optional JSON string of allowlisted generation hints. Unknown fields, including credential/header/storage fields, and arbitrary nested data are rejected. Never include secrets in allowed content either.
`sourceImageId`	Optional ready source UUID in this project; only image_transform supports it.

The file must fit the smallest of your assigned upload limit, the deployment’s image upload limit and 25 MiB. Each multipart text field is limited to 64 KiB. Check your actual assigned limits before uploading; these ceilings do not reserve storage capacity.

Kind	Accepted content types
qr / barcode	`image/png` or `image/svg+xml`
pdf_merge / pdf_extract	`application/pdf`
pdf_render / image_transform	`image/png`, `image/jpeg` or `image/webp`

Save generated QR bytes · cURL / Bash

curl --fail-with-body "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/tools/artifacts" \
  -H "X-API-Key: $IMAZEO_API_KEY" \
  -F "kind=qr" -F "displayName=Catalog QR" -F "contentType=image/png" \
  -F "file=@qr.png;type=image/png"

This assumes you already generated a PNG as qr.png. A successful save returns HTTP 201 and JSON data._id, projectId, kind, displayName, status, bytes, contentType and timestamps. Retain that ID. Large or invalid files, incompatible types, unsupported options and exhausted quotas can fail before acceptance.

List, download and delete

Method / path	Response
`GET` `/tools/artifacts`	Paginated data array; page/limit/total/pages in meta. Optional q and kind filters.
`GET` `/tools/artifacts/{id}`	JSON artifact metadata.
`GET` `/tools/artifacts/{id}/content`	Private file bytes with the actual `Content-Type`; check status before decoding.
`DELETE` `/tools/artifacts/{id}`	JSON confirmation; removes the saved file and releases its storage accounting.
`GET` `/outputs/summary`	Counts across originals, transformations and saved artifacts.
`GET` `/outputs`	Unified paginated output rows; optional q/type filters. See the limitation below.

Artifact lists default to page 1 and limit 20; limit is 1–100. The q filter accepts up to 100 characters and kind uses the save values above. Unified type values are all, original, transform, qr, barcode and pdf. Original and pipeline-transform content still uses the image and transformation routes, respectively.

Retention and safe recovery

Saving persists the file you submit; it does not regenerate missing sources. Keep your own source backups, check assigned source-retention terms and limits, and review what a Portal Save action will retain before removing originals. Cached transformations have a separate expiry policy.

A lost save response does not prove failure. Review the artifact list before retrying so you do not create duplicate files or storage charges. Deleting an output does not refund generation credits or previously used bandwidth. See errors and recovery and the Privacy Notice.

Documentation reviewed 2026-10-03 against development backend e298ec7. Verify your deployment’s API origin and limits before integrating.