Listings

Generate one listing from photos (async)

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.

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)

Headers

Idempotency-Keystring

Unique client-generated key (1-255 chars from A-Za-z0-9_-:.; a UUID works well), scoped to the seller and the operation. The first successful (2xx) response is stored for 24h; retrying the identical request with the same key replays it instead of re-executing, so network-failure retries never create duplicates. A duplicate that arrives while the first is still running gets 409 idempotency_conflict. The same key with a different body (byte for byte) or a different kind of credential gets 422 idempotency_key_reuse and leaves the original record in place: send a new key. An error the operation itself returns is never stored and releases the key.

Request body

photoUrlsstring[] required

Photos of one item, different angles. Only the first 5 are sent to the model.

sellerContextstring

Free-text notes from the seller. Photo evidence wins on conflict unless isCorrection is true.

isCorrectionboolean

True when sellerContext is an explicit correction of a previous result, which makes the model defer to the seller instead of the photo.

groupLabelstring
isBundleboolean
bundleComponentsstring[]

Response

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

successboolean
status'processing'
job_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.