Images API

Overview

Use the Images API when your commerce system needs SuperSeeded-hosted product imagery for plant catalog items. Your backend sends product and plant identifiers to SuperSeeded. The API returns image availability and, when an image is available, a public image URL that can be stored on the product or rendered in a storefront.

Backend-first

Keep your API key on your server or plugin backend.

Storefront-ready

Return ordinary image URLs for product pages, grids, and feeds.

Site allowlist

No generation trigger

The endpoint only returns images that are already available.

This is a generic Images API. SuperSeeded commerce plugins may use it internally, but the API is not tied to any one platform.

How it works

Store the API key server-side

Configure your SuperSeeded API key in your backend, integration service, or server-side commerce plugin settings. Do not expose it in browser JavaScript.

Resolve product images

Send product IDs, SKUs, and plant identifiers to the resolve endpoint.

Use public image URLs

If an image is available, store or render the returned image_url. If it is missing, keep your existing product image.

Authentication

All Images API calls use your SuperSeeded API key:

X-API-Key: sk-sup-v1*****************************************

Store the API key only on your server. Public storefront pages should receive only the returned image URLs.

Register a storefront origin

Register each site that may resolve images for your account. The API normalizes the origin, so paths and query strings are ignored.

curl -X POST https://api.superseeded.ai/v1/retail-images/sites \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-sup-v1*****************************************" \
  -d '{
    "site_url": "https://example-garden-centre.com",
    "label": "Example Garden Centre"
  }'

Example response:

{
  "site_url": "https://example-garden-centre.com",
  "normalized_origin": "https://example-garden-centre.com",
  "active": true
}

Resolve images

Send a batch of product items. Each item should include either species_key or botanical_name; product_id and sku are echoed back so you can map results to your catalog rows.

curl -X POST https://api.superseeded.ai/v1/retail-images/resolve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-sup-v1*****************************************" \
  -d '{
    "site_url": "https://example-garden-centre.com",
    "items": [
      {
        "product_id": 15133,
        "sku": "ACM-200",
        "botanical_name": "Acacia melanoxylon"
      }
    ]
  }'

Example response:

{
  "site_url": "https://example-garden-centre.com",
  "normalized_origin": "https://example-garden-centre.com",
  "results": [
    {
      "product_id": 15133,
      "sku": "ACM-200",
      "species_key": "Acacia melanoxylon",
      "species_hash": "opaque-image-id",
      "status": "available",
      "image_url": "https://images.example.com/catalog/image.png",
      "thumbnail_url": null,
      "version": "current",
      "source_status": "published",
      "message": null
    }
  ]
}

Result statuses

Status	Meaning	Suggested integration behavior
`available`	A public image URL is available.	Save or render `image_url`.
`missing`	No image is available for that item yet.	Keep the existing product image.
`invalid`	The source image could not be used.	Keep the existing product image and log the item for review.

Public image URLs

The returned image_url is intended for public storefront display. Anyone with the URL can request that image, so do not treat it as a private download link. Public URLs are suitable for:

Product detail pages
Category grids
Search results
Merchant-controlled product feeds

They are not suitable for:

Hiding unreleased products
Enforcing customer-specific access
Storing private assets

Integration notes

Keep the API key server-side.
Register every storefront origin before resolving images for that site.
Batch requests when syncing product catalogs.
Treat missing as a normal response and fall back to your existing product image.
Do not call the Images API from unauthenticated browser code.

See Images API for request and response fields.

Getting Started

Frontend Integration

Backend Integration

Commerce Integration

Examples

Overview

Backend-first

Storefront-ready

Site allowlist

No generation trigger

How it works

Authentication

Register a storefront origin

Resolve images

Result statuses

Public image URLs

Integration notes

​Overview

Backend-first

Storefront-ready

Site allowlist

No generation trigger

​How it works

​Authentication

​Register a storefront origin

​Resolve images

​Result statuses

​Public image URLs

​Integration notes

​Related reference

Overview

How it works

Authentication

Register a storefront origin

Resolve images

Result statuses

Public image URLs

Integration notes

Related reference