# Submit an image for scoring

`POST /v1/images/score`

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 return a `score_metadata` breakdown alongside the
composite `vizit_score`; carousel images return `vizit_score` only.

## Request Body

### application/json

- **object**
  - `image_url` (string, required) — Publicly accessible image URL (HTTP/HTTPS, jpeg/png/webp, ≤6 MB)
  - `product_category_id` (string, required) — Category UUID the image belongs to. Must be one returned by
[List product categories](/api/product-details/listProductCategories) —
if it doesn't exist or the organization lacks ICP access, the
request is rejected with `CATEGORY_NOT_IN_ORG_ICP`.

  - `image_type` (enum: "hero" | "carousel", required) — Role the image plays in a listing. `hero` images return an additional
`score_metadata` breakdown; `carousel` images return only
`vizit_score`.


## Responses

### 202 — Image accepted for scoring

**application/json**

- **object** — Image scoring status. When `status` is `"processing"` or `"error"`,
score fields may be absent. When `status` is `"scored"`, `vizit_score`
is populated and `score_metadata` is populated for hero images.

  - `image_id` (string, required) — Internal identifier for the image. Pass it to [Retrieve an image score](/api/images/getImageScore) to poll for results.
  - `status` (enum: "processing" | "scored" | "error", required)
  - `vizit_score` (any) — Composite image score (0–100). For hero images this is the hero
score; for carousel images this is the carousel `vizit_score`.

  - `conversion_ready` (any) — Whether the image meets the conversion-readiness bar. `null` until
the image is `scored`.

  - `score_metadata` (any) — Hero-image score breakdown. `null` for carousel images.
  - `hero_gs1_components` (any) — Per-component GS1 hero sub-scores. Populated for hero images, `null`
for carousel images.

  - `mobile_readiness` (any) — Hero-image mobile-readiness clarity scores. `null` for carousel images.
  - `classification` (any) — Image classification label (normalized to the canonical vocabulary).

### 400 — Validation or image-download error. Check `error_code` to
distinguish:
  - NO_DEFAULT_PORTFOLIO — org has no default portfolio
  - CATEGORY_NOT_IN_ORG_ICP — product_category_id is outside the org's ICP
  - EMPTY_IMAGE — downloaded image body was empty
  - IMAGE_DOWNLOAD_FAILED — the image URL could not be downloaded


**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)

### 401 — Missing or invalid Bearer token

### 404 — product_category_id does not exist

**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)

### 429 — Rate limit exceeded for this organization

### 502 — Image upload to S3 failed

**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)