Generate the Instant set

Build a Studio Instant image set for a VIN. On a match, Spyne adds the vehicle to the rooftop's Spyne inventory if it isn't there yet, and starts building its images.

POSThttps://api.spyne.ai/api/pv1/instant

AuthBearer tokenRate limit120 requests / min per rooftop keyProcessingAsynchronous

Keep data.requestId from the response with the VIN in your logs: Spyne support uses it to trace a set.

Before you call it

The body is the same as a check, without checkOnly. Add stockNumber if you have it.
Each set uses processing credits, the same as a photographed vehicle.
A generate is safe to retry: a second call for the same VIN answers already_instant instead of creating a second set. Two calls sent at the same moment may answer 503 for one of them; the set is still built once.
The key must be linked to a Spyne user, or the call answers 403 API_KEY_CANNOT_GENERATE.

Counts toward the 120 requests a minute per rooftop key, shared with checks.

Request body

Requiredalways sendRequired ifrequired only in the case describedOptionalcan be left out

Request checklist

Name the vehicle: send vin, and stockNumber if you have it.
Generate: leave out checkOnly.
Fill the gaps: send all seven details whenever you have them. It avoids a 400 and gives the most accurate match.
Group key: add rooftopId.

Parameter	Type	Required	Description
`vin`	string	Required	The 17-character VIN of the vehicle that needs images. Letters and digits only, never I, O or Q. Lower case is accepted and upper-cased for you.
`checkOnly`	boolean	Optional	Leave it out, or send `false`, to generate the image set. `true` only checks; see Check for a match. Default: `false`.
Vehicle details	—	Required if	Required when Spyne doesn't know the vehicle. A match needs all seven; see Which details to send.
`year`	number, or a 4-digit string	Required if	Model year, from 1981 to two years ahead. Filled from the VIN when it can be decoded.
`make`	string	Required if	For example `Toyota`. Filled from the VIN when it can be decoded.
`model`	string	Required if	For example `Camry`. Filled from the VIN when it can be decoded.
`trim`	string	Required if	For example `XLE`. Filled from the VIN when the decode has it.
`exteriorColor`	string	Required if	The body colour as the dealer names it, for example `Midnight Black Metallic`.
`interiorColor`	string	Required if	The interior colour, for example `Black`.
`condition`	string	Required if	`new` or `used`. Send `used` for certified pre-owned, demo and rental units too.
`stockNumber`	string	Optional	The dealer's stock number. Saved on the vehicle when the generate adds it to the rooftop's inventory, so it is easy to find later.
`rooftopId`	string	Required if	Group-level keys only: which rooftop the vehicle belongs to. Leave it out with a rooftop key.

Text fields take at most 255 characters.

Sample request

curl --request POST \
  --url 'https://api.spyne.ai/api/pv1/instant' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "vin": "4T1BZ1HK5KU012345",
    "stockNumber": "A12345",
    "year": 2024,
    "make": "Toyota",
    "model": "Camry",
    "trim": "XLE",
    "exteriorColor": "Midnight Black Metallic",
    "interiorColor": "Black",
    "condition": "used"
  }'

import requests

url = "https://api.spyne.ai/api/pv1/instant"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "vin": "4T1BZ1HK5KU012345",
    "stockNumber": "A12345",
    "year": 2024,
    "make": "Toyota",
    "model": "Camry",
    "trim": "XLE",
    "exteriorColor": "Midnight Black Metallic",
    "interiorColor": "Black",
    "condition": "used",
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.json())

const response = await fetch("https://api.spyne.ai/api/pv1/instant", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    vin: "4T1BZ1HK5KU012345",
    stockNumber: "A12345",
    year: 2024,
    make: "Toyota",
    model: "Camry",
    trim: "XLE",
    exteriorColor: "Midnight Black Metallic",
    interiorColor: "Black",
    condition: "used",
  }),
});
console.log(response.status, await response.json());

Sample response

{
  "success": true,
  "statusCode": 202,
  "message": "Studio Instant images are being generated for this VIN. Read them and their status with GET /api/pv1/merchandise",
  "data": {
    "requestId": "f26f2094-6825-4b6a-80af-799311eb4104",
    "vin": "4T1BZ1HK5KU012345",
    "matched": true,
    "status": "processing",
    "vehicle": {
      "year": 2024,
      "make": "Toyota",
      "model": "Camry",
      "trim": "XLE",
      "exteriorColor": "Midnight Black Metallic",
      "interiorColor": "Black",
      "condition": "used"
    }
  }
}

What happened decides the status code:

`data.status`	HTTP	What happened	What to do
`processing`	`202`	A match was found and the image set has started.	Poll Read status and images until the images are ready.
`already_instant`	`200`	This VIN already has an Instant set; nothing new was started.	Read the existing images with Read status and images.
`no_match`	`200`	No matching vehicle; nothing was created.	Plan a photo shoot, or try again later as inventory changes.

Response parameters (202, 200)

Parameter	Type	Description
`data.requestId`	string	A reference for this request. Keep it: Spyne support uses it to trace a set.
`data.vin`	string	The VIN, upper-cased.
`data.matched`	boolean	Whether a match was found.
`data.status`	string	`processing`, `already_instant` or `no_match`.
`data.vehicle`	object	Your vehicle's seven details as used for the match.

Errors

Status	Code	When it happens
`400`	`INVALID_REQUEST`	A field is missing or invalid. Each problem is listed in `details.errors`.
`400`	`INVALID_REQUEST`	"stockNumber is already used by another vehicle at this rooftop".
`401`	`UNAUTHORIZED`	The key is missing, wrong or expired.
`403`	`INSTANT_NOT_ENABLED`	Studio Instant is off for this rooftop and vehicle condition (new or used).
`403`	`API_KEY_CANNOT_GENERATE`	The key isn't linked to a Spyne user, so it can check but not generate.
`404`	`ROOFTOP_NOT_FOUND`	`rooftopId` isn't a rooftop this key can use.
`409`	`VEHICLE_HAS_PHOTOS`	The vehicle already has its own processed photos (or the dealer declined Instant for it).
`409`	`VEHICLE_IN_OTHER_ROOFTOP`	The VIN belongs to another rooftop's inventory.
`429`	`RATE_LIMITED`	More than 120 requests in a minute.
`503`	`SERVICE_UNAVAILABLE`	A Spyne service was briefly unavailable, or a generate for this VIN is already running.

Every code is explained in Errors and FAQs.

What happens next

The images go through Spyne's normal AI processing, the same as photographed vehicles, so there is no fixed turnaround; in Spyne's production test, 20 images were ready in about 45 minutes. A 360 spin, when the source vehicle has one, is processed too and then waits for quality checks.

Read status and images every 30 to 60 seconds until every image has an outputImage. When you later send the vehicle's real photos through Spyne's API, they replace the Instant set on the same VIN.