Build a Product-Photo Shortlist With Jev

Start with one product and one judgement: how clearly can someone see it?

1. The workflow

Photo → vision description → Jev visibility score → shortlist in your code → human choice.

Use a vision-capable model to inspect each photo. Give Jev the resulting text and a scoring rubric. Your application then ranks the candidates and displays the original photos for someone to choose from.

The split exists because of a hard constraint: Jev takes text only — a string, JSON object or array of text values, with no image, audio or video input. TypeSafe’s own docs tell you to pre-process non-text inputs into text or structured fields before sending them. That’s all this recipe is. The upside is that descriptions can be reused against different decision rules; a vision model could also judge suitability directly, so treat this as one possible architecture rather than a proven faster or cheaper one.

Start with 10–20 photos you can inspect yourself. Assign stable IDs such as PHOTO-001, and keep the ID-to-file mapping outside the model. Keep the original photo beside every result, so a person can check the evidence.

2. Copy this image-description prompt

Attach one photo at a time to your chosen vision model. Replace the product reference with your own.

Describe the target product's visible appearance in this photo.
Target product: a violet LOOP bottle with a lime cap.

Return JSON with these text fields:
- image_id: use the supplied ID unchanged
- product_present: present, absent, or uncertain
- visible_extent: what parts of the product can be seen
- obstruction: anything covering the product and where
- crop: any product parts cut off by the image boundary
- focus: whether product details can be distinguished
- evidence_summary: one short factual description
- assessment_status: assessable or review
- unknowns: anything you cannot reliably determine

Describe only what is visible. Do not infer hidden parts.
Do not predict ad performance or give a score.
If the photo is ambiguous, set assessment_status to review
and explain the uncertainty in unknowns.

Check the output against the photo before scoring your first batch. A fluent description can still miss an obstruction. Treat a failed request, a missing field or an uncertain product identity as Review — never as a zero score.

3. Define one visibility rubric

The question: how clearly can someone see the target product, based on the supplied description?

This is a visibility scale and nothing else. It does not combine sharpness, setting, brand fit or expected sales. Add separate criteria later if the campaign needs them, and test each one on its own. These five anchors are a starting point; refine the ambiguous boundaries using your own photos.

Worked example, fictional. PHOTO-001: “The bottle is in focus, but a hand covers most of its body.” That fits the low anchor even though the image is sharp. PHOTO-002: “The entire bottle and cap are in frame, with no object covering them.” That fits the high anchor. Real scores fall between levels — keep the raw number when ranking, and show one decimal if it helps.

4. Send the description to Jev

This uses the documented request structure for POST https://api.typesafe.ai/v1/systemone. Supply your TypeSafe API key through your application’s secret configuration — never inside the prompt or a public file. It’s a starting request, not a tested end-to-end integration.

{
  "model": "jev-latest",
  "state": {
    "image_id": "PHOTO-001",
    "target_product": "Violet LOOP bottle with lime cap",
    "evidence_summary": "The bottle is sharp, but a hand covers most of its body."
  },
  "questions": {
    "product_visibility": {
      "type": "score",
      "instructions": "How clearly can someone see the target product? Judge only the supplied visibility evidence, not aesthetics or sales potential.",
      "criteria": [
        "The target product is absent.",
        "The target is present, but most of it is hidden or cropped out.",
        "A substantial portion is hidden or cropped, although the product is recognisable.",
        "Most of the product is visible, with a small obstruction or crop.",
        "The complete product is visible and unobstructed."
      ]
    }
  }
}

Read answers.product_visibility.score, and keep its probabilities and confidence alongside the description and image ID. Confidence describes the answer distribution; it is not a promise that the description or the decision is correct.

Two things from the docs worth knowing. The response reports the versioned model that actually answered, so record it — or pin a version like jev-1.13.0 instead of the jev-latest alias if you need runs to stay comparable. And a score question takes between 2 and 10 criteria, with a 64k context budget covering the state plus all questions combined, which matters if you start batching many photos into one request.

5. Build the shortlist in your application

Use this logic as a starting point:

for each photo:
    obtain and validate its vision description
    if missing or uncertain: send to Review
    otherwise: request the visibility score
    if the request fails or result is invalid: send to Review
    otherwise: save ID, description, score and model version

sort assessed photos by visibility score, highest first
show the first three candidates with their original photos
show ties at the cutoff together for human selection
keep Review items visible in a separate queue

A top-three list is a selection rule, not proof that three photos are good enough. If every candidate is weak, ask for better inputs rather than approving the least poor photo. Don’t silently discard near-ties, missing descriptions or failed requests. Duplicate detection is a separate step — this rubric won’t remove repeated shots.

6. Test before you rely on it

• Label a small batch yourself: clear, mostly hidden, cropped, absent and uncertain.
• Compare every extracted description against its original photo.
• Compare the ranking with your own shortlist, and investigate the disagreements.
• Check that an uncertain or failed item reaches Review instead of disappearing.
• Run the same saved descriptions again after changing only the rubric.
• Keep the prompt, rubric and model version with each run. Expand the batch only once you understand the errors.

What you get is a first-pass queue for a person to inspect. Product visibility on its own does not predict which ad will perform best.

Sources

• TypeSafe — ScoreThe request and response shape, including probabilities and confidence.
• TypeSafe — StateWhat to put in the state field.
• TypeSafe — ModelsModel identifiers, and the text-only input constraint.

Documentation checked 30 September 2026. No live API run, benchmark or campaign result is claimed. The LOOP product, its photos and every score shown here are fictional teaching material.