Reference Images

A workflow can hold reference images: pictures of what a correct result looks like, such as the approved sticker layout for a product. Steve sends them to the model together with the submission's photos and asks it to compare.

When one workflow covers many products, sending every reference with every photo costs more and confuses the model. Instead, tag each reference with the product keys it applies to, and send the product key with each submission. Steve then compares the submission only with the references for that key, plus any shared references.

The reference library

Reference images are set in the platform workflow builder, on the workflow's Reference images step. Upload several images at once; each one becomes a row with:

• Label: the name the model and reviewers see, for example RT641 door sticker.
• Product keys: the keys this reference applies to. Leave empty for a shared reference.
• Note: optional guidance sent to the model with this image, for example The sticker sits on the left door, 5 cm below the handle.

Turn on Choose references by product key to use keys. When you upload with it on, Steve fills each image's key from its file name (RT641N4AFE1.jpg gets the key RT641N4AFE1); check and edit the keys before saving.

Preview a product key shows which references a submission with that key would get, using the same rules as a real run.

Keys

Keys are not case-sensitive: Steve trims spaces and stores them in upper case, and does the same with the key a submission sends. A key starts with a letter or digit and may contain letters, digits, ., _, / and -, up to 64 characters. A reference can have up to 20 keys.

Exact keys and prefixes

A key ending in * is a prefix: RT641* applies to every key that starts with RT641, such as RT641N4AFE1 and RT641N4ACA. The * is only allowed at the end, and a bare * is not a key.

For a submission with key K, Steve picks:

1. every reference with the exact key K, if there is one;
2. otherwise, every reference with the longest prefix that K starts with;
3. and then, in both cases, every shared reference (one with no keys).

An exact key always beats a prefix. With references keyed RT641* and RT641N4AFE1, a submission with RT641N4AFE1 gets only the exact one, and RT641N4ACA gets the prefix one. References keep their library order within each group.

Shared references

A reference with no keys is shared: it is added to every submission's references, after the keyed ones. Use shared references for things that apply to every product, such as a promotion sticker that must appear on every unit.

Sending the key

The integration sends the key in the API session's metadata, under the field set in Metadata field (default model). Use a top-level field; nested values such as product.model are not read.

curl "$BASE_URL/api/v1/workflows/sticker-check/sessions" \
  -X POST \
  -H "Authorization: Bearer $STEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileCount": 1,
    "contentTypes": ["image/jpeg"],
    "clientSubmissionId": "visit-2211-unit-4",
    "metadata": {
      "model": "RT641N4AFE1",
      "store": "WAW-02"
    }
  }'

The value must be a non-empty string or a number. Steve reads it once, when the submission is first processed, and keeps it on the submission.

When no reference matches

If the submission sends no key, or no reference matches its key, Steve never falls back to sending all references. The workflow's When no reference matches setting decides what happens:

• Send to review without AI analysis (default): Steve makes no AI analysis call. The photos still go through the image quality and moderation checks, then the submission goes to review with empty fields for a person to fill in.
• Analyse with shared references only: Steve analyses the photos with the shared references alone.

A submission whose key selects more references than one analysis allows (see below) also goes to review without an AI analysis call. Reviewers see why in the review screen.

Limits

Steve checks the limits when you save, for every key and every prefix on its own, and refuses a library where any key would go over them. References are never dropped at run time: when a submission's references plus the photos it actually has come to more than 8, for example an older submission reprocessed with more photos than the workflow now allows, it goes to review without an AI analysis.

Choosing references by product key works on photo extraction workflows that use vision. It cannot be turned on for audio, Shelf Watcher or multi-page PDF workflows. Product keys on a reference also need selection by product key turned on, so a tagged library is never sent whole by accident.

Only submit the photos you want analysed

Steve analyses every photo in the session. If your app also takes photos the model should not check, such as a wide shot of the shelf or the price label, do not upload them to this workflow. Each photo you upload adds to the cost and counts towards the limit of 8 images above.

Review

The submission review screen shows only the references that were used for the submission, with the product key and whether each matched by exact key, key prefix or as a shared reference. When the AI analysis was skipped, it shows the reason instead. See Submission review.

Reprocessing

Reprocessing a submission keeps the product key it was first processed with, even if the workflow now reads a different metadata field. Steve picks the references again from the workflow version used for the new run, so reprocessing after you add a reference for that key sends the new reference.

API compatibility

Reference images change no API request or response, and no webhook payload. The product key travels in the existing free-form metadata. The chosen references and the reason a run skipped its analysis are visible in the Steve admin, not in /api/v1. See the API changelog.