Prepared-image caching

Prepared-image caching reuses an intermediate image, such as a cleaned garment or prepared customer photo. It does not reuse the final try-on result. A new generation still runs the remaining workflow and follows the normal billing rules.

This guide covers POST /v1/orgs/:orgId/template/:templateId/run. Do not assume the same request fields apply to asynchronous job creation or storefront APIs.

Start with an ordinary request

Use the Run a template example with your assigned input keys and original images. No separate preparation request, client-generated hash, garment ID, or customer ID is required for automatic cache lookup. The endpoint’s normal authentication and request fields still apply.

Before testing, confirm with the person configuring your template that:

• The workflow declares preparation slots for the intended person or garment inputs.
• Each slot has a preparation version and matching output and availability configuration.
• The workflow can skip preparation when a compatible prepared input is available.
• Your organization’s storage policy permits retaining that type of image.

Templates without preparation slots continue running normally, without this cache optimization. Do not set internal availability variables yourself to force a cache hit.

How images are matched

The lookup key combines:

organization + asset kind + SHA-256 of original image bytes + preparation version

Change	Effect
Same bytes, organization, asset kind, and version	Eligible for reuse if a valid retained entry exists
Different URL serving identical bytes	Can reuse the same prepared image
Same URL serving changed bytes	Different cache identity
Recompressed, cropped, or resized original	Different bytes mean a different identity
Different organization or asset kind	Separate cache identity
Changed preparation version	Previous version is not used for that lookup

Aabhas reads the input and calculates its content hash. Caching does not eliminate source downloads, uploads, or hashing. Keep source URLs accessible for the request; an old cache entry does not make an inaccessible source URL valid.

Source identifiers supplied for provenance are not a replacement for the content hash. Do not use email addresses as cache identifiers.

Storage and privacy

Effective storage mode	Customer preparation	Garment preparation
persist	Eligible for server-side retention and reuse, subject to retention policy	Eligible for retention and reuse
no_store	Not retained in the server-side prepared-image cache	Can still be retained and reused

Customer retention limits still apply. Do not persist inline customer media in your own application simply to work around no_store. Follow the agreed consent and retention policy for any caller-managed images.

Preparation caching is separate from output retrieval. A cache hit does not mean a final result is retained or can be retrieved later.

Check the response

The synchronous result can include a preparedMedia array. Each entry identifies inputKey, outputKey, assetKind, and preparationVersion, with these statuses:

cacheStatus	Meaning
created	The request took the preparation path rather than reusing an existing prepared input
hit	A retained prepared image was reused
provided	A compatible prepared input was supplied to the execution

Read delivery separately: stored, inline_base64, or caller_provided. created alone does not promise durable storage. Optional image metadata may include mimeType, dimensions, byte size, and sha256. That sha256 describes the prepared image, not necessarily the original source bytes.

Do not assume a preparation entry is a final output or that it contains a reusable URL. Use the documented final-output contract for display. Avoid logging media data, signed URLs, or customer photos.

Verify your integration

1. Run the configured template with an original garment and customer image. Record the non-sensitive preparation statuses and effective version.
2. Make a deliberate new execution with the same original bytes and a fresh request identity. Eligible retained inputs should report hit once the first preparation has been stored.
3. Change only the garment bytes. The garment should prepare again; an eligible unchanged customer image can still hit.
4. Test your effective storage mode. Under no_store, do not expect a server-cached customer image on the next execution.
5. Ask your template administrator to change the preparation version in a test configuration. The previous version should no longer satisfy the lookup.

Run these checks in a test organization; they are real generations and may consume credits. Concurrent first requests can both miss, so use sequential requests when verifying reuse. Compare preparation status rather than expecting a fixed latency reduction.

Version changes and deletion

The effective preparation version comes from the preparation configuration, including an organization override when configured. Changing unrelated template text or settings does not automatically guarantee invalidation. When the preparation algorithm or its expected output changes, coordinate an explicit version change with your template administrator.

A version change prevents matching old entries; it is not physical deletion. For removal of retained media, follow Deletion requests. This guide does not expose a public cache-purge endpoint or promise automatic invalidation for every template edit.

Advanced: caller-provided preparation

Most integrations should use automatic caching. If you already hold a compatible prepared image, the synchronous request also accepts preparedInputs, keyed by the original template input key. Keep the original image in inputs so its source hash can be checked.

{
  "preparedInputs": {
    "<GARMENT_INPUT_KEY>": {
      "value": "https://example.com/prepared-garment.png",
      "preparationVersion": "<ASSIGNED_PREPARATION_VERSION>",
      "sourceSha256": "<64_HEX_CHARACTERS_HASH_OF_ORIGINAL_BYTES>",
      "sha256": "<64_HEX_CHARACTERS_HASH_OF_PREPARED_BYTES>"
    }
  }
}

This is a request fragment, not a complete request. Replace every placeholder and merge it with the normal template-run request. value, preparationVersion, and sourceSha256 are required for each supplied entry; sha256 is optional and checked when present. The expected MIME type must also match the preparation slot. Only supply outputs from a compatible preparation process, not arbitrary images labeled as prepared.

An incompatible candidate is not a way to force reuse. Invalid request fields or an unreadable candidate can fail the request; do not rely on fallback for malformed input. You do not need preparedInputs or preparedMediaSources for the ordinary automatic-cache path.

Troubleshooting misses

Check the effective preparation version, organization, asset kind, and exact source bytes first. Also check retention expiry and whether preparation is enabled for that input. A missing or unusable retained entry cannot provide a cache hit. If the cause is unclear, share the trace ID, template ID, input key, and preparation status with support, without sending credentials or customer media.