---
title: "Generate one listing from photos (async)"
method: POST
path: "/api/items/bulk-generate"
tags: ["Listings"]
---

# Generate one listing from photos (async)

`POST /api/items/bulk-generate`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/items/bulk-generate`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

Runs AI generation over up to 10 photos of a SINGLE item (already-uploaded Storage URLs, not base64) and returns a job_id immediately; poll GET /api/ai-jobs/{jobId} for the listing. Pass an Idempotency-Key: a replay returns the ORIGINAL job_id, so the retry polls the generation already in flight instead of paying for a second one.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `photoUrls` string[], required: Photos of one item, different angles. Only the first 5 are sent to the model.
  - `sellerContext` string: Free-text notes from the seller. Photo evidence wins on conflict unless isCorrection is true.
  - `isCorrection` boolean: True when sellerContext is an explicit correction of a previous result, which makes the model defer to the seller instead of the photo.
  - `groupLabel` string
  - `isBundle` boolean
  - `bundleComponents` string[]

## Response `200`

Job accepted (200, not 202). `status` is "processing" and `job_id` is the handle to poll.

- object
  - `success` boolean
  - `status` 'processing'
  - `job_id` string

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `409`: `code: idempotency_conflict`. A request with this Idempotency-Key is still being processed. Retry the same request with the same key after a few seconds: if the first request succeeded the retry replays its response; if it failed, or has been pending for over a minute, the retry runs the operation again.
- `422`: `code: idempotency_key_reuse`. While an earlier request with this Idempotency-Key is still running or succeeded within the last 24h, the key was sent to the same operation with a different body (compared byte for byte) or from a different kind of credential (signed-in session, API key, or OAuth token). Nothing was executed and the original record is untouched, so retrying with this key repeats the 422. Send the request with a new key.
- `429`: Too many requests.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/clearlist/apis/clearlist-api.md) · [All operations](https://skmtc.dev/clearlist/apis/clearlist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clearlist/apis/clearlist-api/revisions/b1c1c4221cb8?raw)