# Request a Spark Images batch

`POST /v1/images/{image_id}/spark/images`

Queues a Spark Images batch 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 batch. Use
[Retrieve a Spark Images batch](/api/spark-images/getSparkImagesBatch)
to poll for terminal states (`completed` / `failed`).

Idempotent on `image_id`: while a batch is in flight for the image,
subsequent calls return the existing batch 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 batch — they
get `404 IMAGE_NOT_FOUND` instead.

## Responses

### 200 — A batch was already in flight for this image; the existing one is returned.

**application/json**

- **object**
  - `batch_id` (string, required) — Identifier of the Spark Images batch. Pass it to [Retrieve a Spark Images batch](/api/spark-images/getSparkImagesBatch) to poll for the result.
  - `image_id` (string, required) — Root image the batch was requested for.
  - `status` (enum: "processing" | "failed" | "completed", required) — Lifecycle status of a Spark request, shared by Spark Ideas and Spark
Images.

- `processing` — non-terminal; the request is queued or running.
- `completed` — terminal success; the response payload is populated.
- `failed` — terminal failure. Also reported for a request that stayed
  non-terminal past the 5-minute processing timeout, even when the
  underlying record still reads as in-flight, so a stuck request is
  always observable here.

  - `result_url` (string, required) — Relative path to poll for the batch result.
  - `created_at` (string, required)

### 202 — New batch accepted for processing.

**application/json**

- **object**
  - `batch_id` (string, required) — Identifier of the Spark Images batch. Pass it to [Retrieve a Spark Images batch](/api/spark-images/getSparkImagesBatch) to poll for the result.
  - `image_id` (string, required) — Root image the batch was requested for.
  - `status` (enum: "processing" | "failed" | "completed", required) — Lifecycle status of a Spark request, shared by Spark Ideas and Spark
Images.

- `processing` — non-terminal; the request is queued or running.
- `completed` — terminal success; the response payload is populated.
- `failed` — terminal failure. Also reported for a request that stayed
  non-terminal past the 5-minute processing timeout, even when the
  underlying record still reads as in-flight, so a stuck request is
  always observable here.

  - `result_url` (string, required) — Relative path to poll for the batch result.
  - `created_at` (string, required)

### 400 — Validation error. Check `error_code` to distinguish:
  - GENERATED_IMAGE_NOT_ALLOWED — the image is itself Spark-generated; only root images may seed Spark
  - MISSING_PRODUCT_CATEGORY — the image has no `product_category_id` assigned


**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 — Image not found for this id in the caller's organization
(`error_code: IMAGE_NOT_FOUND`). Returned both when the image does
not exist and when it belongs to a different organization.


**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)

### 500 — Failed to enqueue the batch for processing
(`error_code: SQS_ENQUEUE_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)