Introduction

Studio Instant gives a vehicle listing-ready studio images before anyone photographs it. You send a VIN; if the rooftop already has a photographed vehicle with the same year, make, model, trim, colours and condition, Spyne builds a full image set for your VIN from it.

Step	Page
1. Check for a match (optional)	Check for a match `POST`
2. Generate the image set	Generate the Instant set `POST`
3. Read status and images	Read status and images `GET`
Reference	Errors and FAQs

The check is optional: a generate runs it too. If no identical vehicle exists, nothing is created and you plan a photo shoot as usual.

Before you start

You need an API key for the rooftop (one dealership location) from Developer Hub in the Spyne Console. Keep it on your server: never put it in a browser, an app or a support ticket.
Studio Instant must be switched on for the rooftop. It is set separately for new and used vehicles, by Spyne or by the dealer in the Console.

Base URL and headers

Every path starts with https://api.spyne.ai/api/pv1. Send these headers on every call:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Content-Type is needed on POST requests. See Authentication.

Response shape

Every answer from POST /api/pv1/instant uses the same envelope:

{ "success": true, "statusCode": 200, "message": "A Studio Instant match exists for this VIN", "data": { } }

{ "success": false, "statusCode": 400, "code": "INVALID_REQUEST", "message": "…", "details": { "errors": ["…"] } }

Field	Meaning
`success`	`true` when the request worked, `false` on an error.
`statusCode`	The same number as the HTTP status.
`message`	A plain-English sentence you can log or show to your team.
`data`	The result, on success only.
`code`	On errors only: a stable code to branch on, such as `INSTANT_NOT_ENABLED`.
`details.errors`	On validation errors only: one message per problem.

Branch on statusCode, data.status and code, never on the wording of message: messages may be improved over time.

Which vehicle details to send

A match needs all seven details: year, make, model, trim, exterior colour, interior colour and condition. Spyne fills in what it already knows:

VIN already in the rooftop's Spyne inventory: the stored details are used, so vin alone is often enough.
New VIN: year, make, model and trim come from decoding the VIN, but colours and condition can't. Send exteriorColor, interiorColor and condition at least.
Anything still missing: the call answers 400 and lists exactly which fields to add.

Details you send replace stored ones for the match, with one exception: if the rooftop already holds the vehicle as new or used, that condition stands.

Matching is exact. Spyne looks for a vehicle on the same rooftop (or, if the rooftop allows it, elsewhere in its dealer group) with the same seven details and its own finished, quality-checked photos. Spell colours and trims the way the dealer's inventory does.

Rate limits

120 requests a minute per rooftop key (per dealer group for a group-level key), shared by checks and generates. Going over returns 429 RATE_LIMITED; wait the seconds in the Retry-After header, then retry.