🖼️ Product Cutout Images

Stable public image URLs on images.orbital.vision that always resolve to the latest generated cutout for a product and variant combination.

Every cutout image OV25 generates for your catalogue gets a stable, human-readable public URL on images.orbital.vision. The URL never changes — when the underlying image is re-rendered (new model, new materials, quality improvements), the same URL simply starts redirecting to the new file. Use these URLs directly in <img> tags, product feeds, emails, or anywhere else you need product imagery.

https://images.orbital.vision/{account}/{image-key}.webp

A real example:

https://images.orbital.vision/darlings-of-chelsea/fabian~hatton~chair-small~watson-silver~dark-oak.webp

These URLs are public and unauthenticated — no API key goes in the URL. The first path segment identifies your account by name, and everything after it identifies the image.

The easy way: every generated image's exact URL can be copied from your dashboard — open the Products page, open the Product setup panel, and browse the generated cutout images. Use the copied URL as-is. The rest of this page explains how the URL is structured so you can also construct them programmatically.

URL structure

1. The account segment

The first segment is your organization name, slugified:

lowercase, accents removed
& becomes and
hyphens, underscores, and slashes are treated as spaces
all other punctuation is dropped
spaces become single hyphens

So "Darlings of Chelsea" → darlings-of-chelsea, and "Smith & Sons Ltd." → smith-and-sons-ltd.

2. The image key

The canonical key joins the range, product, and each variant selection with a tilde (~), each segment slugified with the same rules as above:

{range}~{product}~{variant}~{variant}.webp

Variant segments are the selection names of the options that vary for that product (for example a fabric and a wood finish), in the order shown in the dashboard.
Products whose images don't vary by option use default as the single variant segment.
The .webp extension is optional — .png and .jpg spellings are also accepted (the served file is WebP either way).
Slashes work in place of tildes, so range/product/variant.webp resolves too.
Matching is case-insensitive and URL-encoding is handled for you.

How a URL is resolved

When a request comes in, the resolver works through these steps:

Exact match — the key is compared against the canonical paths of your generated images (ignoring case, extension, and tilde-vs-slash differences). A hit redirects immediately.
Interpreted match — the key is split into segments and tried as range/product/variants, product/variants, and variants only. Each segment is matched against range names, product names, variant selection names, and their SKUs — so a key built from your own SKU codes can resolve as well.
Fuzzy match — near-miss spellings and partial names are tolerated and scored. The best-scoring ready image wins, provided it clears a minimum confidence; otherwise the request is a 404.

This means you don't have to reproduce our slugs perfectly — reasonable names or SKUs for the range, product, and variants will usually land on the right image. That said, exact canonical keys (or URLs copied from the dashboard) are always the safest.

The response

A successful lookup returns a 307 redirect to the current rendered file — a transparent-background WebP cutout on our CDN. Two debug headers ride along:

Header	Meaning
`X-Org-Auto-Cutout-Asset`	The ID of the image the URL resolved to.
`X-Org-Auto-Cutout-Match`	How it matched: `exact-output-path`, `range-product-variants`, `product-variants`, or `variants`.

Redirects are cached at the edge for a few minutes, so a re-render or catalogue change shows up in your storefront quickly without hammering the resolver.

Never store the redirected CDN URL. It points at a specific rendered file and goes stale whenever the image is re-generated. Store and render the images.orbital.vision URL — following the redirect is the browser's job.

Errors

Failed lookups return JSON with an error message and a code:

Status	Code	Meaning
`404`	`invalid_image_path`	The path is missing the account or image segment.
`404`	`organization_not_found`	The first segment didn't match any account name.
`404`	`image_not_found`	Nothing ready matched the key with enough confidence.

Images can disappear when a product, range, or variant is discontinued — if a URL that used to work starts returning 404, hide that image in your storefront rather than showing a broken image.

Looking up URLs programmatically (JSON API)

If you're building an integration and want the match metadata — or want to verify a match before publishing it — there's an authenticated JSON endpoint that runs the same resolver but returns the result instead of redirecting:

GET https://app.orbital.vision/api/product-cutouts?image={image-key}
Authorization: Bearer {privateApiKey}

This is where your API key comes in. Use a Private Api Key, generated at app.orbital.vision/auth/api-keys — note this is a different key type from the Product Configurator Access key used for embeds, and it's a secret: call this endpoint from your server, not the browser.

curl -H "Authorization: Bearer YOUR_PRIVATE_API_KEY" \
  "https://app.orbital.vision/api/product-cutouts?image=fabian~hatton~chair-small~watson-silver~dark-oak"

A successful response:

{
  "url": "https://…/….webp",
  "image": {
    "id": "…",
    "format": "webp",
    "outputPath": "fabian~hatton~chair-small~watson-silver~dark-oak.webp",
    "status": "ready",
    "readyAt": "2026-06-30T…",
    "updatedAt": "…",
    "createdAt": "…"
  },
  "matched": {
    "inputPath": "fabian~hatton~chair-small~watson-silver~dark-oak",
    "canonicalOutputPath": "fabian~hatton~chair-small~watson-silver~dark-oak.webp",
    "strategy": "exact-output-path",
    "confidence": 100,
    "range": { "name": "Fabian", "rangeId": 123 },
    "product": { "name": "Hatton", "productId": 456 },
    "variants": [ { "optionName": "Fabric", "selectionName": "Watson Silver" }, … ]
  }
}

matched.strategy and matched.confidence tell you how the resolver got there — an exact-output-path at confidence 100 is a canonical hit; lower-confidence fuzzy matches may be worth reviewing. url here is the direct CDN file, which is fine for immediate use but subject to the same staleness warning as above — persist the public images.orbital.vision form instead.

Errors follow the same { "error": …, "code": … } shape: 400 for a missing/garbled key or image parameter (missing_api_key, invalid_api_key_format, missing_image), 401 for a key that doesn't authenticate (invalid_api_key), and 404 (image_not_found) when nothing matched.

Behaviour notes

Only generated, ready images resolve. Images still queued or rendering for the first time 404 until they're done; once an image exists, re-renders swap seamlessly behind the same URL.
Which products and variants get cutout images — and how many — is controlled from the Product setup panel in your dashboard, subject to your account's image allowance.
URLs resolve within a single account's images: the account segment scopes the search, so keys only ever match your own catalogue.
The public resolver and the JSON API share the same matching logic — a key that works on one works on the other.

On this page