Read status and images

Read a vehicle's image status and its finished images. Instant images are read with the same vehicle endpoint you use for photographed vehicles, Retrieve a vehicle.

GEThttps://api.spyne.ai/api/pv1/merchandise

AuthBearer token

Poll it every 30 to 60 seconds after a generate until every image has an output URL.

Before you call it

This endpoint answers with the vehicle object itself, without the success / data envelope.

Query parameters

Only onesend exactly one from the group

Parameter	Type	Required	Description
`vin`	string	Only one	The vehicle's VIN (recommended).
`stockNumber`	string	Only one	Look the vehicle up by the dealer's stock number instead.
`registrationNumber`	string	Only one	Look it up by registration (plate) number instead.

Sample request

curl --request GET \
  --url 'https://api.spyne.ai/api/pv1/merchandise?vin=4T1BZ1HK5KU012345' \
  --header 'Authorization: Bearer YOUR_API_KEY'

import requests

url = "https://api.spyne.ai/api/pv1/merchandise"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"vin": "4T1BZ1HK5KU012345"}

response = requests.get(url, headers=headers, params=params)
print(response.status_code, response.json())

const url = "https://api.spyne.ai/api/pv1/merchandise?vin=4T1BZ1HK5KU012345";
const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
console.log(response.status, await response.json());

Sample response

A trimmed example once the set is ready:

{
  "vin": "4T1BZ1HK5KU012345",
  "stockNumber": "A12345",
  "source": "API",
  "mediaData": {
    "image": {
      "aiStatus": "DONE",
      "imageData": [
        {
          "imageName": "front_left.jpg",
          "category": "Exterior",
          "frameNo": 1,
          "status": "Done",
          "outputImage": "https://…/front_left.jpg"
        }
      ]
    },
    "spin": {
      "aiStatus": "DONE",
      "qcStatus": "qc_unassigned",
      "thumbnailUrl": "https://…/thumbnail.jpg"
    }
  }
}

Response parameters (200)

The fields to watch:

Parameter	Values	Description
`mediaData.image.aiStatus`	`YET_TO_START`, `IN_PROGRESS`, `DONE`	Progress of the whole image set.
`mediaData.image.imageData[].status`	`Yet to Start`, `In Progress`, `Done`, `Failed`	Progress of one image.
`mediaData.image.imageData[].outputImage`	URL	The finished, listing-ready image. Missing until that image is `Done`. Publish these.
`mediaData.image.imageData[].category`	for example `Exterior`, `Interior`	Which part of the car the image shows.
`mediaData.image.imageData[].frameNo`	number	The image's position in the set; use it to order the gallery.
`mediaData.spin.aiStatus` / `qcStatus`	for example `DONE` / `qc_unassigned`	Progress of the 360 spin, when there is one.
`stockNumber`, `source`	text	The stock number you sent, and `API` for vehicles added through this API.

The set is ready when aiStatus is DONE and every image has an outputImage. Publish only outputImage URLs: the answer also lists each image's inputImage, the raw photo it was built from, which is not for listings.

This endpoint doesn't mark a set as Instant. To ask whether a VIN's images came from Studio Instant, send a check: it answers "This VIN already has a Studio Instant image set".

Errors

Status	Body	When it happens
`404`	`{ "message": "Dealer vin not found" }`	Spyne doesn't have this VIN.
`500`	—	Rare while images are processing, and temporary: retry on your next poll.

What happens next

Publish the outputImage URLs. When you later send the vehicle's real photos through Spyne's API, they replace the Instant set on the same VIN.