Vizit Public APIAPI
Spark Ideas

Request a Spark Idea

Ask Spark for written suggestions on a root image.

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

Queues a Spark Idea 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 Idea. Use Retrieve a Spark Idea to poll for terminal states (completed / failed).

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

Authorization

bearerAuth
Authorization<token>

Short-lived access token issued by Create a token. Send it on every request as Authorization: Bearer <token>.

In: header

Path Parameters

image_id*string

Root image to request a Spark Idea for. Must belong to the caller's organization and must not itself be Spark-generated.

Formatuuid

Response 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/ideas"
{  "idea_id": "513dcbd6-3206-4305-8a7e-8651161eebfb",  "image_id": "84c230fd-5520-4984-8119-37365b66fd80",  "status": "processing",  "result_url": "/v1/images/8f3e0d1a-1b2c-4f5e-9a3b-9c8d7e6f5a4b/spark/ideas/3e2a7c91-4b6d-4d8a-9c1e-7d5f0a1b2c3d",  "created_at": "2019-08-24T14:15:22Z"}
{  "idea_id": "513dcbd6-3206-4305-8a7e-8651161eebfb",  "image_id": "84c230fd-5520-4984-8119-37365b66fd80",  "status": "processing",  "result_url": "/v1/images/8f3e0d1a-1b2c-4f5e-9a3b-9c8d7e6f5a4b/spark/ideas/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"}
Empty
{  "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 an image score

Returns the current scoring state of an image previously sent to [Submit an image for scoring](/api/images/scoreImage). Poll until `status` moves from `processing` to `scored`. Hero images return a `score_metadata` breakdown alongside `vizit_score`; carousel images return `vizit_score` only.

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`.