Images and uploads

A generation needs a publicly retrievable customer-photo URL. The upload endpoint creates a signed storage target; it does not upload an image or start a generation.

Upload sequence

1. Prepare image bytes and choose the exact MIME type.
2. POST { "contentType": "image/jpeg" } to /uploads.
3. PUT the raw image bytes to the returned uploadUrl.
4. Include the same image Content-Type on the PUT.
5. Check the PUT succeeded.
6. Send the returned imageUrl as the generation’s imageUrl.

const target = await client.createUpload(file.type, signal);
await client.uploadBytes(target.uploadUrl, file, file.type, signal);
// target.imageUrl is now the URL to use in POST /generations.

Do not send the SDK key, JSON envelope or multipart body to the signed upload URL. Do not pass uploadUrl itself as the generation photo URL.

Accepted API MIME values

image/jpeg, image/png, image/webp, image/heic, image/heif, image/avif.

The upload target expires after 600 seconds. Upload promptly. If it expires, request a new target. Do not edit the signed URL.

customKey is an optional object-key prefix containing 1-100 letters, digits, underscores or hyphens. It is not a custom bucket, arbitrary path, access control or destination URL.

SDK preprocessing versus API validation

Layer	Current behavior
Browser SDK	Rejects empty files and files larger than 10 MiB; checks formats by model; decodes/orients the image; resizes images over approximately one million pixels.
Upload endpoint	Validates MIME selection and optional prefix, then creates a signed PUT URL. It does not inspect bytes in that request.
Generation request	Validates that imageUrl is a URL string. Actual image retrieval and generation happen later.

Do not describe the SDK’s 10 MiB limit as a verified universal API upload limit. Native and custom API clients own their own size, decoding and preprocessing checks.

SDK format selection by model

Funnel model	SDK accepted formats
ANTLA_PRO	JPEG, PNG, WebP, AVIF, HEIC/HEIF
ANTLA_FAST	JPEG, PNG, WebP
ANTLA_LIGHT	JPEG, PNG, WebP, AVIF

Allowed HEIC/HEIF input still depends on the browser decoding it. MIME acceptance alone is not universal device support. Use normalized, correctly oriented JPEG for a broadly interoperable photo flow where possible.

When resizing a large image, the SDK uses JPEG output. A custom client should use the prepared file’s actual MIME type, not the original file extension, for its upload.

Use your own storage

You may supply an existing public image URL instead of using Antla storage. It must remain accessible to the generation service for the full processing period, without requiring browser cookies, a private bearer token or a local-device path.

Use HTTPS and a supported image format. Avoid short-lived URLs that can expire before the worker retrieves the image. A syntactically valid URL can still fail later if inaccessible or not decodable.

The API does not accept a garment-image override: it selects the product image from Shopify.

Result image lifecycle

displayUrl can be temporary. Show it as a preview only while storageStatus is PENDING. Continue polling for a permanent result.

At READY, use permanentUrl, then imageUrl. Permanent here means Antla has stored the image. It does not promise that the URL lasts forever. A storage failure is a job with status: "ERROR".

A legacy success with no storage status and a usable imageUrl can be treated as complete. All other unknown or unusable combinations need error handling rather than silent success.