Vizit Public APIAPI
Images

Retrieve an image score

Poll for the result of a previously submitted image.

GET/v1/images/{image_id}/score

Returns the current scoring state of an image previously sent to Submit an image for scoring. Poll until status leaves PROCESSING; ERROR responses carry error_code and error_detail.

Hero images with GS1 hero analysis available additionally return hero_gs1_components alongside vizit_score. GS1 component scoring finishes shortly after the base score, so such a hero stays PROCESSING until both are available. A COMPLETED hero can still carry hero_gs1_components: null when GS1 analysis is not available for its organization or product category, or did not finish within the scoring window; treat null as "no breakdown", not as an error.

Carousel images classified as an informational asset type (Alternate Product Views, Certification Mark, Included Items, Info Panel, Multi-Pack, Product Facts Panel, Size and Scale) are not scored and resolve to error_code: IMAGE_OMITTED_FROM_SCORING, with classification naming the type. Standalone product shots on a plain background may classify as Alternate Product Views; hero submissions are always scored.

Authorization

bearerAuth
Authorization<token>

Short-lived access token issued by Create a token. Send it on every request as Authorization: Bearer <token>.

In: header

Path Parameters

image_id*string

The image_id returned by Submit an image for scoring.

Formatuuid

Response Body

application/json

application/json

application/json

curl -X GET "https://ext.vizit.com/v1/images/497f6eca-6276-4993-bfeb-53cbbbba6f08/score"
{  "image_id": "84c230fd-5520-4984-8119-37365b66fd80",  "status": "PROCESSING",  "error_code": "IMAGE_OMITTED_FROM_SCORING",  "error_detail": "string",  "vizit_score": 0,  "vizit_certified": true,  "hero_gs1_components": {    "four_ws.brand": 92,    "four_ws.product_type": 88,    "four_ws.variant": 74,    "four_ws.size_and_count": 75,    "image_quality.background_separation": 95,    "image_quality.product_centered": 90,    "image_quality.product_prominent": 93,    "image_quality.product_cropping": 97,    "image_quality.product_tilt": 98,    "image_quality.no_off_pack_text": 100,    "composition": 84,    "layout_staging": 81  },  "hero_gs1_component_statuses": {    "four_ws.brand": "PASS",    "four_ws.product_type": "REVIEW",    "four_ws.variant": "REVIEW",    "four_ws.size_and_count": "REVIEW",    "image_quality.background_separation": "REVIEW",    "image_quality.product_centered": "REVIEW",    "image_quality.product_prominent": "REVIEW",    "image_quality.product_cropping": "REVIEW",    "image_quality.product_tilt": "REVIEW",    "image_quality.no_off_pack_text": "PASS",    "composition": "HIGH",    "layout_staging": "HIGH"  },  "hero_gs1_group_statuses": {    "shopper_clarity": "REVIEW",    "image_quality": "REVIEW",    "composition": "HIGH",    "product_staging": "HIGH"  },  "agent_ready": true,  "mobile_ready": true,  "classification": "Lifestyle"}
Empty
{  "detail": "string",  "status_code": 0,  "error_code": "IMAGE_DOWNLOAD_FAILED",  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",  "extra": {    "failed_urls": [      {        "url": "https://cdn.example.com/broken.jpg",        "reason": "IMAGE_DOWNLOAD_TIMEOUT"      },      {        "url": "https://cdn.example.com/icon.svg",        "reason": "UNSUPPORTED_IMAGE_FORMAT"      }    ]  },  "timestamp": "2019-08-24T14:15:22Z"}
{  "detail": "string",  "status_code": 0,  "error_code": "IMAGE_DOWNLOAD_FAILED",  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",  "extra": {    "failed_urls": [      {        "url": "https://cdn.example.com/broken.jpg",        "reason": "IMAGE_DOWNLOAD_TIMEOUT"      },      {        "url": "https://cdn.example.com/icon.svg",        "reason": "UNSUPPORTED_IMAGE_FORMAT"      }    ]  },  "timestamp": "2019-08-24T14:15:22Z"}

POSTSubmit an image for scoring

Submits a standalone image for asynchronous scoring. The response returns immediately with an `image_id` and `status: PROCESSING`; use [Retrieve an image score](/api/images/getImageScore) to poll for the result. Hero images additionally return `hero_gs1_components` alongside the composite `vizit_score`. Carousel images classified as an informational asset type are not scored — they resolve to `error_code: IMAGE_OMITTED_FROM_SCORING` (see [Retrieve an image score](/api/images/getImageScore)). Hero submissions are always scored.

POSTRequest a Spark Idea

Queues a Spark Idea for the image and returns immediately with `status: PROCESSING` — a fresh request starts in flight, and an idempotent reuse only ever matches an in-flight Idea. Use [Retrieve a Spark Idea](/api/spark-ideas/getSparkIdea) to poll for terminal states (`COMPLETED` / `ERROR`). Idempotent on `image_id`: while an Idea is in flight for the image, subsequent calls return the existing Idea with `200 OK` instead of creating a new one. A fresh create returns `202 Accepted`. The organization check runs before the idempotent lookup, so callers from a different organization cannot reuse another org's in-flight Idea — they get `404 IMAGE_NOT_FOUND` instead. Hero images with GS1 hero analysis available are only accepted once their GS1 component scores are stored; until then the request returns `409 HERO_GS1_SCORES_MISSING`. Wait for [Retrieve an image score](/api/images/getImageScore) to report `COMPLETED` with `hero_gs1_components` populated before requesting Spark work. The 409 `detail` says whether the scores are still being computed or will never be available for the image.