Request a Spark Images batch
Ask Spark to generate a batch of images from a root image.
/v1/images/{image_id}/spark/imagesQueues 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
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.
Authorization
bearerAuth Short-lived access token issued by Create a token.
Send it on every request as Authorization: Bearer <token>.
In: header
Path Parameters
Root image to request a Spark Images batch for. Must belong to the caller's organization and must not itself be Spark-generated.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://ext.vizit.com/v1/images/497f6eca-6276-4993-bfeb-53cbbbba6f08/spark/images"{ "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20", "image_id": "84c230fd-5520-4984-8119-37365b66fd80", "status": "processing", "result_url": "/v1/images/8f3e0d1a-1b2c-4f5e-9a3b-9c8d7e6f5a4b/spark/images/3e2a7c91-4b6d-4d8a-9c1e-7d5f0a1b2c3d", "created_at": "2019-08-24T14:15:22Z"}{ "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20", "image_id": "84c230fd-5520-4984-8119-37365b66fd80", "status": "processing", "result_url": "/v1/images/8f3e0d1a-1b2c-4f5e-9a3b-9c8d7e6f5a4b/spark/images/3e2a7c91-4b6d-4d8a-9c1e-7d5f0a1b2c3d", "created_at": "2019-08-24T14:15:22Z"}{ "detail": "string", "status_code": 0, "error_code": "INVALID_GTIN", "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": "INVALID_GTIN", "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": "INVALID_GTIN", "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"}GETRetrieve a Spark Idea
Returns the current state of a Spark Idea. Poll until `status` moves from `processing` to `completed` or `failed`. `data` carries the suggestion markdown only when `status` is `completed`. Ideas that have been non-terminal for longer than the 5-minute timeout are reported as `failed` here even when the database row still reads as `processing`.
GETRetrieve a Spark Images batch
Returns the current state of a Spark Images batch. Poll until `status` moves from `processing` to `completed` or `failed`. `data` is empty until `status` is `completed`. The batch only completes once every prompt is terminal and Spark Cull has resolved every child image; while cull is settling it stays `processing` with empty `data`. Once `completed`, `data` holds the visible children only — each with a short-lived pre-signed download URL that a fresh request refreshes. A batch that has been non-terminal for longer than the 5-minute timeout is reported as `failed` here even when the database rows still read as in-flight.