@meterapp/car-image-sdk 1.4.0 → 1.5.0

package/dist/mcp/index.js

@@ -10,8 +10,11 @@
  * entry point of the SDK has no runtime dependencies.
  */
 import * as z from "zod";
-import { CATALOG, COLORS, CREDITS_PER_DOLLAR, CREDITS_PER_IMAGE, DEFAULT_BASE_URL, FITS, FORMATS, FREE_CREDITS, IDEMPOTENCY_KEY_PATTERN, MAX_DIMENSION, MAX_PADDING_PERCENT, MIN_YEAR, REFERRAL_SOURCES, REQUEST_FORMATS, REQUEST_KINDS, REQUEST_SORTS, REQUEST_STATUSES, SIZES, VIEWS, } from "../types.js";
+import { isColor } from "../params.js";
+import { CATALOG, COLORS, CREDITS_PER_3D_MODEL, CREDITS_PER_DOLLAR, CREDITS_PER_IMAGE, DEFAULT_BASE_URL, FITS, FORMATS, FREE_CREDITS, IDEMPOTENCY_KEY_PATTERN, MAX_DIMENSION, MAX_PADDING_PERCENT, MIN_YEAR, MODEL_3D_FILE_KINDS, REFERRAL_SOURCES, REQUEST_FORMATS, REQUEST_KINDS, REQUEST_SORTS, REQUEST_STATUSES, SIZES, VEHICLE_ID_PATTERN, VIEWS, } from "../types.js";
 import { SDK_VERSION } from "../version.js";
+/** The 3D price as agents read it: "1,000 credits ($1.00)". */
+const MODEL_3D_PRICE = `${CREDITS_PER_3D_MODEL.toLocaleString("en-US")} credits ($${(CREDITS_PER_3D_MODEL / CREDITS_PER_DOLLAR).toFixed(2)})`;
 /**
  * Catalog size as agents read it in the instructions and tool descriptions.
  * Derived from CATALOG so the figures cannot drift from the database; agents
@@ -39,9 +42,12 @@ export const MCP_TOOLSETS = {
         "create_car_image_urls",
         "search_vehicles",
         "resolve_vehicle",
+        "decode_vin",
         "list_image_options",
         "get_account",
         "rate_image",
+        "create_3d_model",
+        "get_3d_model",
         "describe_api",
     ],
     all: [
@@ -49,9 +55,12 @@ export const MCP_TOOLSETS = {
         "create_car_image_urls",
         "search_vehicles",
         "resolve_vehicle",
+        "decode_vin",
         "list_image_options",
         "get_account",
         "rate_image",
+        "create_3d_model",
+        "get_3d_model",
         "describe_api",
         "list_requests",
         "request_vehicle",
@@ -68,11 +77,11 @@ export const MCP_TOOLSET_NAMES = Object.keys(MCP_TOOLSETS);
 export function isMcpToolset(value) {
     return typeof value === "string" && MCP_TOOLSET_NAMES.includes(value);
 }
-const INSTRUCTIONS_COMMON = `Car Image API by Meter: studio-quality, transparent-background renders of any vehicle in the open @meterapp/vehicle-db catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, model years ${CATALOG_YEARS}). Six camera views, fifteen preset colors, PNG/WebP/JPG up to 1024 px, any width and height (fit contain|cover|inside), transparent or a solid background color.
+const INSTRUCTIONS_COMMON = `Car Image API by Meter: studio-quality, transparent-background renders of any vehicle in the open @meterapp/vehicle-db catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, model years ${CATALOG_YEARS}). Six camera views, any paint color (fifteen named presets or any hex such as #1a2b3c), PNG/WebP/JPG up to 1024 px, any width and height (fit contain|cover|inside), transparent or a solid background color. Every catalog vehicle has a stable id (veh_ followed by 13 characters) that search_vehicles, resolve_vehicle and decode_vin return and every image or 3D tool accepts as \`vehicle\` in place of make, model and year.
 
-Costs: every delivered image costs exactly ${CREDITS_PER_IMAGE} credit ($1 = ${CREDITS_PER_DOLLAR.toLocaleString("en-US")} credits; ${FREE_CREDITS} free credits per account), cold or CDN hit. create_car_image_urls charges 1 credit per URL when the URL is created; redemptions are free. search_vehicles, resolve_vehicle, list_image_options, get_account, rate_image and describe_api are free.
+Costs: every delivered image costs exactly ${CREDITS_PER_IMAGE} credit ($1 = ${CREDITS_PER_DOLLAR.toLocaleString("en-US")} credits; ${FREE_CREDITS} free credits per account), cold or CDN hit. create_car_image_urls charges 1 credit per URL when the URL is created; redemptions are free. create_3d_model costs ${MODEL_3D_PRICE} per model, charged when the request is made: confirm with the human before calling it. search_vehicles, resolve_vehicle, decode_vin, list_image_options, get_account, rate_image, get_3d_model and describe_api are free.
 
-Workflow: (1) resolve_vehicle turns free text such as "red 2024 porsche 911 side view" into exact parameters; search_vehicles browses the catalog. (2) Call get_car_image when the image itself is needed in the conversation. (3) For web pages, emails, documents or anything a browser will load, call create_car_image_urls and embed the signed URLs; they need no key.
+Workflow: (1) resolve_vehicle turns free text such as "red 2024 porsche 911 side view" into exact parameters; search_vehicles browses the catalog; decode_vin turns a VIN into the catalog vehicle and its id. (2) Call get_car_image when the image itself is needed in the conversation. (3) For web pages, emails, documents or anything a browser will load, call create_car_image_urls and embed the signed URLs; they need no key. (4) For a textured 3D model (GLB, USDZ, FBX), call create_3d_model once the human has agreed to the cost, then poll get_3d_model every few seconds until status is ready and hand over files.<kind>.url; a model takes one to five minutes.
 
 Security: never place the API key in URLs, HTML, logs, screenshots or client-side code. Signed delivery URLs are the only thing that should ever reach a browser.
 
@@ -92,16 +101,38 @@ const yearSchema = z.coerce
     .int()
     .min(MIN_YEAR)
     .max(2100)
-    .describe(`Model year, e.g. 2024. The catalog covers ${MIN_YEAR} through next year.`);
-export const imageInputSchema = z.object({
-    make: z.string().min(1).max(80).describe('Manufacturer, e.g. "Porsche", "BMW", "Toyota". Case and punctuation do not matter.'),
-    model: z.string().min(1).max(80).describe('Model as listed in the catalog, e.g. "911", "M3", "Corolla".'),
-    year: yearSchema,
+    .describe(`Model year, e.g. 2024. The catalog covers ${MIN_YEAR} through next year. Omit when vehicle is given.`);
+/** A paint color: a preset name, or a hex such as `#1a2b3c` (`1a2b3c` and `#rgb` are accepted too). */
+export const colorSchema = z
+    .string()
+    .min(1)
+    .max(20)
+    .refine(isColor, { message: `color must be one of ${COLORS.join(", ")}, or a hex like #1a2b3c` })
+    .describe(`Paint color: one of the presets (${COLORS.join(", ")}) or a hex like #1a2b3c. Responses echo a hex as #rrggbb.`);
+/** A stable catalog vehicle id, as every catalog tool returns it. */
+export const vehicleIdSchema = z
+    .string()
+    .regex(VEHICLE_ID_PATTERN, "vehicle must be a vehicle id: veh_ followed by 13 characters")
+    .describe("Stable vehicle id such as veh_395yw8tn73ff8 (from search_vehicles, resolve_vehicle or decode_vin). Names the make, model and year, so omit those when it is given.");
+const vehicleFields = {
+    vehicle: vehicleIdSchema.optional(),
+    make: z.string().min(1).max(80).optional().describe('Manufacturer, e.g. "Porsche", "BMW", "Toyota". Case and punctuation do not matter. Omit when vehicle is given.'),
+    model: z.string().min(1).max(80).optional().describe('Model as listed in the catalog, e.g. "911", "M3", "Corolla". Omit when vehicle is given.'),
+    year: yearSchema.optional(),
+};
+/** Either the vehicle id or all three of make, model and year; the server rejects both together. */
+function namesOneVehicle(input) {
+    return input.vehicle !== undefined || (input.make !== undefined && input.model !== undefined && input.year !== undefined);
+}
+const ONE_VEHICLE = { message: "Give either vehicle (a veh_… id) or all of make, model and year" };
+export const imageInputSchema = z
+    .object({
+    ...vehicleFields,
     view: z
         .enum(VIEWS)
         .default("front-3-4")
         .describe("Camera angle: front (0°), front-3-4 (35°, the classic hero angle), side (profile, nose left), side-right (profile, nose right), rear (180°), rear-3-4 (145°)."),
-    color: z.enum(COLORS).default("silver").describe("Paint color; one of the fifteen presets."),
+    color: colorSchema.default("silver"),
     size: z
         .enum(["thumb", "small", "medium", "large"])
         .optional()
@@ -129,7 +160,8 @@ export const imageInputSchema = z.object({
         .enum(REQUEST_FORMATS)
         .default("png")
         .describe("png keeps the transparent background (default); webp is smallest; jpg is flattened onto white; auto lets each viewer's Accept header choose webp or png, negotiated on every load of a signed URL. An inline image (get_car_image) is delivered as png for auto."),
-});
+})
+    .refine(namesOneVehicle, ONE_VEHICLE);
 /**
  * The encoding an inline image (`get_car_image`) is delivered in. `auto` is
  * negotiated from an HTTP `Accept` header, which a tool call does not carry,
@@ -204,11 +236,12 @@ export const MCP_TOOL_SCHEMAS = {
             .max(128)
             .optional()
             .describe("The request_id returned by get_car_image or create_car_image_urls (preferred way to identify the image)."),
-        make: z.string().min(1).max(80).optional().describe("Alternative to request_id: identify the image by vehicle."),
+        vehicle: vehicleIdSchema.optional(),
+        make: z.string().min(1).max(80).optional().describe("Alternative to request_id: identify the image by vehicle (make, model, year, or a vehicle id)."),
         model: z.string().min(1).max(80).optional(),
         year: z.coerce.number().int().min(MIN_YEAR).max(2100).optional(),
         view: z.enum(VIEWS).optional(),
-        color: z.enum(COLORS).optional(),
+        color: colorSchema.optional(),
         rating: z.number().int().min(1).max(5).optional().describe("1 (unusable) to 5 (perfect)."),
         verdict: z.enum(["good", "bad"]).optional().describe("Quick thumbs up/down; provide this or rating."),
         reason: z.string().max(500).optional().describe("What was wrong or right, e.g. 'wrong body style', 'perfect angle'."),
@@ -218,7 +251,36 @@ export const MCP_TOOL_SCHEMAS = {
             .string()
             .max(120)
             .optional()
-            .describe('Filter by path fragment or keyword, e.g. "images/car", "image-urls", "feedback". Omit for the full compact reference.'),
+            .describe('Filter by path fragment or keyword, e.g. "images/car", "image-urls", "vin", "3d". Omit for the full compact reference.'),
+    }),
+    decode_vin: z.object({
+        vin: z
+            .string()
+            .min(5)
+            .max(40)
+            .describe("A full 17-character VIN, or a partial VIN of at least 5 characters with * for each unknown position. Case, spaces and dashes do not matter."),
+        year: z.coerce.number().int().min(1900).max(2100).optional().describe("Model-year hint for the decoder; it flags a mismatch with the VIN's own year position."),
+    }),
+    create_3d_model: z
+        .object({
+        ...vehicleFields,
+        color: colorSchema.default("silver"),
+        webhook_url: z
+            .string()
+            .url()
+            .max(2048)
+            .optional()
+            .describe("Public https URL that receives one POST {event: '3d_model.ready' | '3d_model.failed', data, sent_at} when the model settles; retried with backoff up to five times."),
+        webhook_secret: z.string().min(1).max(256).optional().describe("With webhook_url: the POST body is signed as X-CarImage-Signature: sha256=<hex HMAC of the raw body>."),
+        idempotency_key: z
+            .string()
+            .regex(/^[A-Za-z0-9._:-]{1,255}$/, "idempotency_key must be 1-255 characters of letters, digits, '.', '_', ':' or '-'")
+            .optional()
+            .describe("A retry with the same key replays the first answer instead of charging again (24 h); use it when a call may be repeated."),
+    })
+        .refine(namesOneVehicle, ONE_VEHICLE),
+    get_3d_model: z.object({
+        id: z.string().uuid().describe("The 3D request id returned by create_3d_model."),
     }),
     list_requests: z.object({
         kind: z.enum(REQUEST_KINDS).optional().describe("Only vehicle requests or only feature requests. Omit for both."),
@@ -281,11 +343,14 @@ export const MCP_TOOL_SCHEMAS = {
  */
 /** The vehicle echoed back with an image: exactly what would render it again. */
 const vehicleDescriptorSchema = z.looseObject({
+    /** Stable id of the catalog vehicle; null when the catalog cannot name one. */
+    vehicle_id: z.string().nullable(),
     make: z.string(),
     model: z.string(),
     year: z.number().int(),
     view: z.enum(VIEWS),
-    color: z.enum(COLORS),
+    /** A preset name, or a hex paint as #rrggbb. */
+    color: z.string(),
     width: z.number().int().optional(),
     height: z.number().int().optional(),
     fit: z.enum(FITS).optional(),
@@ -355,6 +420,82 @@ const createdRequestResult = z.looseObject({
     deduplicated: z.boolean(),
     request_id: z.string(),
 });
+/** The response of GET /api/v1/vin/{vin}: every key present, unknown values null. */
+const vinResultSchema = z.looseObject({
+    vin: z.string(),
+    valid: z.boolean(),
+    errors: z.array(z.looseObject({ code: z.number().int(), text: z.string() })),
+    suggested_vin: z.string().nullable(),
+    year: z.number().int().nullable(),
+    make: z.string().nullable(),
+    model: z.string().nullable(),
+    trim: z.string().nullable(),
+    series: z.string().nullable(),
+    body_class: z.string().nullable(),
+    vehicle_type: z.string().nullable(),
+    doors: z.number().int().nullable(),
+    drive_type: z.string().nullable(),
+    fuel_type: z.string().nullable(),
+    engine: z.looseObject({
+        cylinders: z.number().int().nullable(),
+        displacement_l: z.number().nullable(),
+        hp: z.number().nullable(),
+        model: z.string().nullable(),
+    }),
+    transmission: z.looseObject({ style: z.string().nullable(), speeds: z.number().int().nullable() }),
+    manufacturer: z.string().nullable(),
+    plant: z.looseObject({ city: z.string().nullable(), state: z.string().nullable(), country: z.string().nullable() }),
+    gvwr: z.string().nullable(),
+    /** Every decoded vPIC variable verbatim. */
+    attributes: z.record(z.string(), z.string()),
+    /** The catalog vehicle the VIN maps to, with the id and path that render it; null when the catalog lacks it. */
+    vehicle: z.looseObject({ id: z.string(), make: z.string(), model: z.string(), year: z.number().int(), image_path: z.string() }).nullable(),
+    source: z.enum(["vpic-db", "vpic-api"]),
+});
+const model3dFileSchema = z.looseObject({
+    /** API URL that redirects to a short-lived signed download; needs the key. */
+    url: z.string(),
+    bytes: z.number().int(),
+    content_type: z.string(),
+});
+/** A 3D request as POST /api/v1/3d and GET /api/v1/3d/{id} return it. */
+const model3dSchema = z.looseObject({
+    id: z.string(),
+    object: z.literal("3d_model"),
+    status: z.enum(["queued", "processing", "ready", "failed"]),
+    /** 0-100. */
+    progress: z.number(),
+    stage: z.string().nullable(),
+    vehicle: z.looseObject({ id: z.string().nullable(), make: z.string(), model: z.string(), year: z.number().int() }),
+    /** A preset name, or a hex paint as #rrggbb. */
+    color: z.string(),
+    generator: z.string(),
+    /** Present once status is ready. */
+    files: z
+        .looseObject({
+        glb: model3dFileSchema.optional(),
+        usdz: model3dFileSchema.optional(),
+        fbx: model3dFileSchema.optional(),
+        thumbnail: model3dFileSchema.optional(),
+    })
+        .nullable(),
+    polycount: z.number().int().nullable(),
+    /** Set when status is failed; the request was refunded. */
+    error: z.looseObject({ code: z.string(), message: z.string() }).nullable(),
+    estimated_seconds_remaining: z.number().nullable(),
+    webhook: z
+        .looseObject({
+        url: z.string(),
+        status: z.string().nullable(),
+        attempts: z.number().int(),
+        last_status: z.number().int().nullable(),
+        delivered_at: z.string().nullable(),
+    })
+        .nullable(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    ready_at: z.string().nullable(),
+});
 export const MCP_TOOL_OUTPUT_SCHEMAS = {
     get_car_image: z.looseObject({
         credits_charged: z.number().nullable(),
@@ -396,11 +537,13 @@ export const MCP_TOOL_OUTPUT_SCHEMAS = {
         data: z.looseObject({
             /** Ready to pass straight to get_car_image. */
             params: z.looseObject({
+                /** Stable id of the resolved vehicle; pass it as `vehicle` to render it again. */
+                vehicle_id: z.string().nullable(),
                 make: z.string(),
                 model: z.string(),
                 year: z.number().int(),
                 view: z.enum(VIEWS),
-                color: z.enum(COLORS),
+                color: z.string(),
             }),
             display: z.looseObject({ make_name: z.string(), model_name: z.string() }).optional(),
             /** Other catalog vehicles that fit the phrase; ask when confidence is low. */
@@ -465,6 +608,17 @@ export const MCP_TOOL_OUTPUT_SCHEMAS = {
         }),
         request_id: z.string(),
     }),
+    decode_vin: z.looseObject({ data: vinResultSchema, request_id: z.string() }),
+    create_3d_model: z.looseObject({
+        data: model3dSchema,
+        billing: z.looseObject({
+            charged_on: z.literal("creation"),
+            credits_charged: z.number(),
+            credits_remaining: z.number(),
+        }),
+        request_id: z.string(),
+    }),
+    get_3d_model: z.looseObject({ data: model3dSchema, request_id: z.string() }),
     list_requests: requestListResult,
     request_vehicle: createdRequestResult,
     request_feature: createdRequestResult,
@@ -526,11 +680,37 @@ export function toImageOptions(data) {
         },
     };
 }
+/** The one-line summary both servers put above a decoded VIN. */
+export function vinSummary(result) {
+    const car = [result.year ?? "?", result.make ?? "unknown make", result.model ?? "", result.trim ?? ""].filter(Boolean).join(" ");
+    const notes = result.errors.length ? ` Decoder notes: ${result.errors.map((error) => error.text).join("; ")}.` : "";
+    if (result.vehicle) {
+        return `${result.vin}: ${car}. Catalog vehicle ${result.vehicle.id} (${result.vehicle.year} ${result.vehicle.make} ${result.vehicle.model}): pass it as vehicle to get_car_image, create_car_image_urls or create_3d_model.${notes}`;
+    }
+    return `${result.vin}: ${car}. Not in the image catalog; search_vehicles may find the model under another spelling.${notes}`;
+}
+/** The one-line summary both servers put above a 3D model, with the charge when it was just created. */
+export function model3dSummary(model, billing) {
+    const car = `${model.vehicle.year} ${model.vehicle.make} ${model.vehicle.model} in ${model.color}`;
+    const charge = billing ? `Charged ${billing.credits_charged.toLocaleString("en-US")} credits, ${billing.credits_remaining.toLocaleString("en-US")} remaining. ` : "";
+    if (model.status === "ready") {
+        const files = Object.entries(model.files ?? {})
+            .filter((entry) => Boolean(entry[1]))
+            .map(([kind, file]) => `${kind} (${(file.bytes / 1_048_576).toFixed(1)} MB)`)
+            .join(", ");
+        return `${charge}3D model ${model.id} is ready: ${car}; files ${files || "none"}. Each files.<kind>.url redirects to a signed download valid for an hour (the API key is needed on the first hop only).`;
+    }
+    if (model.status === "failed") {
+        return `${charge}3D model ${model.id} failed: ${model.error?.message ?? "the model could not be generated"}. The credits were refunded; try again later or with another color.`;
+    }
+    const eta = model.estimated_seconds_remaining === null ? "" : `, about ${model.estimated_seconds_remaining} s left`;
+    return `${charge}3D model ${model.id} is ${model.status} (${model.progress}%${model.stage ? `, ${model.stage}` : ""}${eta}): ${car}. Poll get_3d_model(id) again in a few seconds; do not create it twice.`;
+}
 export const MCP_TOOLS = {
     get_car_image: {
         name: "get_car_image",
         title: "Get car image",
-        description: `Render or fetch a studio-quality, transparent-background image of a specific vehicle (make, model, year) from one of six camera angles in one of fifteen preset colors, at any width and height up to ${MAX_DIMENSION} px (fit contain|cover|inside), transparent or on a solid background, optionally trimmed to the car. Returns the image inline (PNG/WebP/JPG; format auto delivers PNG here) plus usage metadata (credits_charged, credits_remaining, source cache|generated, request_id). COSTS ${CREDITS_PER_IMAGE} CREDIT per call, cached or generated. Use resolve_vehicle first when the request is free text; use create_car_image_urls instead when the image must be embedded in a web page or document.`,
+        description: `Render or fetch a studio-quality, transparent-background image of a specific vehicle (make, model and year, or its vehicle id) from one of six camera angles in any paint color (fifteen named presets or any hex such as #1a2b3c), at any width and height up to ${MAX_DIMENSION} px (fit contain|cover|inside), transparent or on a solid background, optionally trimmed to the car. Returns the image inline (PNG/WebP/JPG; format auto delivers PNG here) plus usage metadata (credits_charged, credits_remaining, source cache|generated, request_id, the vehicle with its vehicle_id). COSTS ${CREDITS_PER_IMAGE} CREDIT per call, cached or generated. Use resolve_vehicle first when the request is free text; use create_car_image_urls instead when the image must be embedded in a web page or document.`,
         inputSchema: MCP_TOOL_SCHEMAS.get_car_image,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_car_image,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
@@ -538,7 +718,7 @@ export const MCP_TOOLS = {
     create_car_image_urls: {
         name: "create_car_image_urls",
         title: "Create signed car image URLs",
-        description: "Create 1-50 signed, key-free delivery URLs that browsers, emails or documents can load directly (<img src>). Each URL costs 1 credit at creation; redemptions within the TTL are free and publicly cacheable. Each image takes the same sizing options as get_car_image (width, height, fit, background, trim, padding); format auto makes the URL serve webp or png per viewer. For email, CMS pages or documents that outlive a TTL, set renew: true with ttl_seconds 604800: the URL keeps serving past expiry at one more credit per opened week, for up to renew_days. Pass idempotency_key when the call might be repeated: a retry with the same key and arguments replays the first result instead of billing again. Returns id, url, expires_at, max_uses, renews_until and the normalized vehicle for each image. Prefer this over get_car_image whenever the output is HTML, Markdown, a document or a website.",
+        description: "Create 1-50 signed, key-free delivery URLs that browsers, emails or documents can load directly (<img src>). Each URL costs 1 credit at creation; redemptions within the TTL are free and publicly cacheable. Each image names its vehicle like get_car_image (make, model, year, or a vehicle id), takes any paint color (a preset or a hex) and the same sizing options (width, height, fit, background, trim, padding); format auto makes the URL serve webp or png per viewer. For email, CMS pages or documents that outlive a TTL, set renew: true with ttl_seconds 604800: the URL keeps serving past expiry at one more credit per opened week, for up to renew_days. Pass idempotency_key when the call might be repeated: a retry with the same key and arguments replays the first result instead of billing again. Returns id, url, expires_at, max_uses, renews_until and the normalized vehicle for each image. Prefer this over get_car_image whenever the output is HTML, Markdown, a document or a website.",
         inputSchema: MCP_TOOL_SCHEMAS.create_car_image_urls,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.create_car_image_urls,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
@@ -546,7 +726,7 @@ export const MCP_TOOLS = {
     search_vehicles: {
         name: "search_vehicles",
         title: "Search the vehicle catalog",
-        description: `Free. Fuzzy-search the open vehicle catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, ${CATALOG_YEARS}) by make and/or model with typo tolerance. Returns canonical make/model names, available years and match kind, ready to pass to get_car_image. Use it to confirm a vehicle exists or to list a make's models before rendering.`,
+        description: `Free. Fuzzy-search the open vehicle catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, ${CATALOG_YEARS}) by make and/or model with typo tolerance. Returns canonical make/model names, available years and match kind, ready to pass to get_car_image (a model hit also carries stable vehicle ids per year, usable as \`vehicle\`). Use it to confirm a vehicle exists or to list a make's models before rendering.`,
         inputSchema: MCP_TOOL_SCHEMAS.search_vehicles,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.search_vehicles,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -554,7 +734,7 @@ export const MCP_TOOLS = {
     resolve_vehicle: {
         name: "resolve_vehicle",
         title: "Resolve free text to image parameters",
-        description: 'Free. Turn a natural-language request such as "red 2024 porsche 911 side view" into exact get_car_image parameters (make, model, year, view, color) plus alternative candidates and a confidence of high, medium or low. Call this before rendering when the user did not spell out the parameters; ask the user to choose when confidence is low or several candidates fit.',
+        description: 'Free. Turn a natural-language request such as "red 2024 porsche 911 side view" into exact get_car_image parameters (vehicle_id, make, model, year, view, color) plus alternative candidates and a confidence of high, medium or low. Call this before rendering when the user did not spell out the parameters; ask the user to choose when confidence is low or several candidates fit.',
         inputSchema: MCP_TOOL_SCHEMAS.resolve_vehicle,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.resolve_vehicle,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -562,7 +742,7 @@ export const MCP_TOOLS = {
     list_image_options: {
         name: "list_image_options",
         title: "List image options",
-        description: "Free. List the supported camera views (with yaw angles and aliases), the fifteen preset colors with hex swatches, size presets, output formats, current pricing and catalog coverage. Use it when you need to validate or explain what can be requested.",
+        description: "Free. List the supported camera views (with yaw angles and aliases), the fifteen preset colors with hex swatches (any other paint is a hex color), size presets, output formats, current pricing and catalog coverage. Use it when you need to validate or explain what can be requested.",
         inputSchema: MCP_TOOL_SCHEMAS.list_image_options,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_image_options,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -578,7 +758,7 @@ export const MCP_TOOLS = {
     rate_image: {
         name: "rate_image",
         title: "Rate a delivered image",
-        description: "Free. Record quality feedback on a delivered image, either by the request_id returned with it or by vehicle (make, model, year, view, color). Provide verdict good|bad or rating 1-5 and an optional reason. Feedback drives re-renders and prompt improvements.",
+        description: "Free. Record quality feedback on a delivered image, either by the request_id returned with it or by vehicle (make, model, year, or a vehicle id, plus view and color). Provide verdict good|bad or rating 1-5 and an optional reason. Feedback drives re-renders and prompt improvements.",
         inputSchema: MCP_TOOL_SCHEMAS.rate_image,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.rate_image,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
@@ -590,6 +770,30 @@ export const MCP_TOOLS = {
         inputSchema: MCP_TOOL_SCHEMAS.describe_api,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    decode_vin: {
+        name: "decode_vin",
+        title: "Decode a VIN",
+        description: "Free. Decode a full 17-character VIN, or a partial VIN of at least 5 characters with * for unknown positions, with NHTSA vPIC data: year, make, model, trim, series, body class, engine, transmission, manufacturer, plant and every decoded attribute. `vehicle` is the catalog vehicle it maps to, with the stable id to pass as `vehicle` to get_car_image, create_car_image_urls or create_3d_model, or null when the catalog does not carry that car. Use it whenever the human gives a VIN instead of a make and model.",
+        inputSchema: MCP_TOOL_SCHEMAS.decode_vin,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.decode_vin,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    create_3d_model: {
+        name: "create_3d_model",
+        title: "Create a 3D model",
+        description: `COSTS ${MODEL_3D_PRICE} PER CALL, charged when the request is made whether the model is cached, in progress or new: confirm with the human before creating one. Build a textured 3D model (GLB, USDZ, FBX and a PNG thumbnail) of one catalog vehicle (make, model and year, or a vehicle id) in one paint color (a preset or any hex), from the same renders the images use, so it matches the pictures. A failed model is refunded. Returns the request at once with status queued, processing or ready (cached), progress 0-100 and estimated_seconds_remaining; poll get_3d_model every few seconds until status is ready, then hand over files.<kind>.url (API URLs that redirect to short-lived signed downloads), or pass webhook_url to be POSTed the same JSON when it settles. A model takes one to five minutes.`,
+        inputSchema: MCP_TOOL_SCHEMAS.create_3d_model,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.create_3d_model,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    get_3d_model: {
+        name: "get_3d_model",
+        title: "Get a 3D model",
+        description: "Free. The state of one 3D request by id: status (queued, processing, ready, failed), progress 0-100, stage, estimated_seconds_remaining, the vehicle and color, and once ready the files (glb, usdz, fbx, thumbnail) with their download URLs, byte sizes and content types. Poll it every few seconds after create_3d_model; a processing model is re-checked with the provider on each call. A failed model carries error and was refunded.",
+        inputSchema: MCP_TOOL_SCHEMAS.get_3d_model,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_3d_model,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
     list_requests: {
         name: "list_requests",
         title: "List vehicle and feature requests",
@@ -665,11 +869,12 @@ export const API_REFERENCE = [
         auth: "bearer",
         credits: "1 per call (cached or generated)",
         params: [
-            "make (required)",
-            "model (required)",
-            `year (required, ${CATALOG_YEARS})`,
+            "make (required unless vehicle is given)",
+            "model (required unless vehicle is given)",
+            `year (required unless vehicle is given, ${CATALOG_YEARS})`,
+            "vehicle (a stable vehicle id such as veh_395yw8tn73ff8, from /api/v1/vehicles, /api/v1/vin or resolve; replaces make, model and year, never alongside them)",
             `view (${VIEWS.join("|")}; default front-3-4)`,
-            `color (${COLORS.join("|")}; default silver)`,
+            `color (${COLORS.join("|")}, or any hex paint written bare in URLs such as 1a2b3c; default silver; JSON echoes a hex as #1a2b3c)`,
             "size (thumb=256|small=512|medium=768|large=1024)",
             `w, h (1-${MAX_DIMENSION} px; both -> the output is exactly w x h)`,
             `fit (${FITS.join("|")}; default contain; only matters with both w and h)`,
@@ -677,11 +882,11 @@ export const API_REFERENCE = [
             `trim (1 crops to the car's alpha bounds before sizing), padding (0-${MAX_PADDING_PERCENT} percent, only with trim)`,
             `format (${FORMATS.join("|")}|auto; default png; auto negotiates webp/png from Accept)`,
         ],
-        returns: "image bytes; headers X-Credits-Charged, X-Credits-Remaining, X-Image-Source (cache|generated), X-Image-Width, X-Image-Height, ETag, X-Request-Id (Vary: Accept with format=auto). With Accept: application/json: {data:{url,expires_at,vehicle,width,height,format}, billing:{credits_charged,credits_remaining}, request_id}",
-        errors: ["400 invalid params", "401 missing/invalid key", "402 insufficient credits (balance, required_credits)", "404 vehicle not in catalog", "429 rate limited (Retry-After)", "502 render failed (refunded)"],
+        returns: "image bytes; headers X-Credits-Charged, X-Credits-Remaining, X-Image-Source (cache|generated), X-Image-Width, X-Image-Height, ETag, X-Request-Id (Vary: Accept with format=auto). With Accept: application/json: {data:{url,expires_at,vehicle:{vehicle_id,make,model,year,view,color,…},width,height,format}, billing:{credits_charged,credits_remaining}, request_id}",
+        errors: ["400 invalid params (also vehicle together with make/model/year)", "401 missing/invalid key", "402 insufficient credits (balance, required_credits)", "404 vehicle not in catalog or unknown vehicle id", "429 rate limited (Retry-After)", "502 render failed (refunded)"],
         notes: "Do not purchase credits automatically on 402; ask the human. Respect Retry-After on 429.",
-        sdk: "client.getImage({ make, model, year, view, color, size, width, height, fit, background, trim, padding, format }) / client.getImageUrl(...)",
-        cli: "car-image get --make Porsche --model 911 --year 2024 --view side --color red --out car.png",
+        sdk: "client.getImage({ make, model, year, view, color, size, width, height, fit, background, trim, padding, format }) / client.getImage({ vehicle: 'veh_…', color: '#1a2b3c' }) / client.getImageUrl(...)",
+        cli: "car-image get --make Porsche --model 911 --year 2024 --view side --color red --out car.png · car-image get --vehicle veh_395yw8tn73ff8 --color 1a2b3c",
     },
     {
         method: "POST",
@@ -689,10 +894,10 @@ export const API_REFERENCE = [
         summary: "Create 1-50 signed delivery URLs for browsers (no key needed to load them).",
         auth: "bearer",
         credits: "1 per URL, charged at creation; redemptions are free",
-        params: ["images: [{make, model, year, view?, color?, size?, width?, height?, fit?, background?, trim?, padding?, format?}] (or a single image object)", "ttl_seconds (60-604800; default 3600)", "max_uses (0 = unlimited; default 0)", "renew (auto-renew past the TTL at 1 credit per opened window; requires max_uses 0)", "renew_days (1-365; default 365)", "header Idempotency-Key (optional; a retry with the same key and body replays the first response instead of billing again)"],
-        returns: "201 {data:[{id,url,expires_at,max_uses,renews_until,vehicle}], billing:{charged_on:'creation',credits_charged,credits_remaining,credits_per_url,renewal?}, request_id}; a replay carries Idempotent-Replayed: true",
+        params: ["images: [{make, model, year | vehicle, view?, color? (preset or hex), size?, width?, height?, fit?, background?, trim?, padding?, format?}] (or a single image object)", "ttl_seconds (60-604800; default 3600)", "max_uses (0 = unlimited; default 0)", "renew (auto-renew past the TTL at 1 credit per opened window; requires max_uses 0)", "renew_days (1-365; default 365)", "header Idempotency-Key (optional; a retry with the same key and body replays the first response instead of billing again)"],
+        returns: "201 {data:[{id,url,expires_at,max_uses,renews_until,vehicle:{vehicle_id,…}}], billing:{charged_on:'creation',credits_charged,credits_remaining,credits_per_url,renewal?}, request_id}; a replay carries Idempotent-Replayed: true",
         errors: ["400 invalid body or batch > 50", "401", "402", "404 vehicle not in catalog", "409 same Idempotency-Key still in flight", "422 same Idempotency-Key with a different body", "429"],
-        sdk: "client.createImageUrls([{ make, model, year, ...sizing }], { ttlSeconds, maxUses, renew, renewDays, idempotencyKey })",
+        sdk: "client.createImageUrls([{ make, model, year, ...sizing }, { vehicle: 'veh_…' }], { ttlSeconds, maxUses, renew, renewDays, idempotencyKey })",
         cli: "car-image url --make BMW --model M3 --year 2022 --ttl 86400 [--renew] [--idempotency-key <key>]",
     },
     {
@@ -710,7 +915,7 @@ export const API_REFERENCE = [
         summary: "Views, colors, sizes, formats, pricing and catalog coverage.",
         auth: "public",
         credits: "free",
-        returns: "{data:{views:[{id,label,yaw_degrees,description,aliases}], colors:[{name,hex}], sizes:{presets,max,source}, fits, default_fit, backgrounds, trim, formats, pricing:{credits_per_image,credits_per_dollar,free_credits}, catalog:{makes,models,years,sources}}}",
+        returns: "{data:{views:[{id,label,yaw_degrees,description,aliases}], colors:[{name,hex}], paint:{parameter,custom,example}, sizes:{presets,max,source}, fits, default_fit, backgrounds, trim, formats, pricing:{credits_per_image,credits_per_dollar,free_credits}, catalog:{makes,models,years,sources}, vehicle_ids:{description,example,lookup,parameter}}}",
         sdk: "client.options()",
         cli: "car-image options",
     },
@@ -721,28 +926,100 @@ export const API_REFERENCE = [
         auth: "bearer",
         credits: "free",
         params: ['query: "red 2024 porsche 911 side view"'],
-        returns: "{data:{params:{make,model,year,view,color}, display:{make_name,model_name}, candidates:[...], confidence:high|medium|low, image_path}}",
+        returns: "{data:{params:{vehicle_id,make,model,year,view,color}, display:{make_name,model_name}, candidates:[...], confidence:high|medium|low, image_path}}",
         sdk: "client.resolve(query)",
         cli: "car-image resolve red 2024 porsche 911 side view",
     },
     {
         method: "GET",
         path: "/api/v1/vehicles",
-        summary: "Browse or search the catalog.",
+        summary: "Browse or search the catalog; every model in a known year carries its stable vehicle id.",
         auth: "public",
         credits: "free",
-        params: ["(none) -> years", "year -> makes [{id,name}]", "year + makeId -> models", "q (+ limit) -> fuzzy search results"],
-        returns: "{data:{years}} | {data:{year,makes}} | {data:{year,make_id,models}} | {data:{results}}",
-        sdk: "client.vehicles({ year, makeId }) / client.searchVehicles(q, { limit })",
+        params: ["(none) -> years", "year -> makes [{id,name,slug}]", "year + makeId -> models [{name,slug,vehicle_type,id}]", "make (slug) [+ year] -> that make's models", "make + model (slugs) -> the model's years, each with its id", "q (+ limit, year) -> fuzzy search results; a model hit carries ids {year: id} and id for the year the query named"],
+        returns: "{data:{years}} | {data:{year,makes}} | {data:{year,make_id,models}} | {data:{make,models}} | {data:{make,model,years,year_ranges,vehicles:[{year,id}]}} | {data:{query,results:[{kind,make_name,make_slug,model_name,model_slug,vehicle_type,years,year_ranges,match_kind,id?,ids?}]}}",
+        sdk: "client.vehicles({ year, makeId }) / client.vehicles({ make, model }) / client.searchVehicles(q, { limit, year })",
         cli: "car-image search porsche 911",
     },
+    {
+        method: "GET",
+        path: "/api/v1/vehicles/{id}",
+        summary: "The catalog vehicle a stable id names, with its years and the image URLs that render it.",
+        auth: "public",
+        credits: "free",
+        returns: "{data:{id, make:{id,name,slug}, model:{name,slug,vehicle_type}, year, years, year_ranges, image_path, images:{front,front-3-4,side,side-right,rear,rear-3-4}}, request_id}",
+        errors: ["400 not a vehicle id", "404 unknown id"],
+        notes: "Ids are a pure function of the catalog spelling and never change; store them instead of make/model/year strings.",
+        sdk: "client.vehicle('veh_395yw8tn73ff8')",
+        cli: "car-image get --vehicle veh_395yw8tn73ff8",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/vin/{vin}",
+        summary: "Decode a full or partial VIN (NHTSA vPIC) and name the catalog vehicle it maps to.",
+        auth: "bearer",
+        credits: "free",
+        params: ["vin in the path: 17 characters, or a partial VIN of 5+ characters with * for each unknown position (case, spaces and dashes ignored)", "year (optional model-year hint)"],
+        returns: "{data:{vin, valid, errors:[{code,text}], suggested_vin, year, make, model, trim, series, body_class, vehicle_type, doors, drive_type, fuel_type, engine:{cylinders,displacement_l,hp,model}, transmission:{style,speeds}, manufacturer, plant:{city,state,country}, gvwr, attributes:{…every decoded variable}, vehicle:{id,make,model,year,image_path}|null, source:vpic-db|vpic-api}, request_id}",
+        errors: ["400 invalid VIN or year", "401", "404 VIN not recognized", "502 both decoders unavailable"],
+        notes: "vehicle.id is a stable vehicle id: pass it as vehicle= to /api/v1/images/car, /api/v1/image-urls or /api/v1/3d. vehicle is null when the catalog does not carry the car.",
+        sdk: "client.decodeVin('1HGCM82633A004352', { year: 2003 })",
+        cli: "car-image vin 1HGCM82633A004352",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/3d",
+        summary: "Create a textured 3D model (GLB, USDZ, FBX and a thumbnail) of one vehicle in one paint color.",
+        auth: "bearer",
+        credits: `${MODEL_3D_PRICE} per model at launch (credits_per_model, reported by GET /api/v1/3d), charged at creation whether the model is cached, in progress or new; a failed model is refunded; polls and downloads are free`,
+        params: ["make, model, year — or vehicle (a veh_… id), never both", "color (preset or hex such as #1a2b3c; default silver)", "webhook_url (https, public host; receives one POST {event:'3d_model.ready'|'3d_model.failed', data, sent_at} with X-CarImage-Event and X-CarImage-Delivery, retried up to five times)", "webhook_secret (with webhook_url: X-CarImage-Signature: sha256=<hex HMAC of the raw body>)", "header Idempotency-Key (optional; same rules as /api/v1/image-urls)"],
+        returns: "202 while queued or processing, 200 when already ready: {data:{id, object:'3d_model', status:queued|processing|ready|failed, progress:0-100, stage, vehicle:{id,make,model,year}, color, generator, files:{glb|usdz|fbx|thumbnail:{url,bytes,content_type}}|null, polycount, error, estimated_seconds_remaining, webhook, created_at, updated_at, ready_at}, billing:{charged_on:'creation',credits_charged,credits_remaining}, request_id}; Location: /api/v1/3d/{id}",
+        errors: ["400 invalid body or webhook URL", "401", "402 insufficient credits", "404 vehicle not in catalog", "409/422 Idempotency-Key conflicts", "503 3D models disabled or at daily capacity (Retry-After; nothing charged)"],
+        notes: "Ask the human before spending. A model takes one to five minutes: poll GET /api/v1/3d/{id} every few seconds or use the webhook; never re-POST to check progress.",
+        sdk: "client.create3dModel({ make, model, year } | { vehicle }, { color, webhookUrl, webhookSecret, idempotencyKey }) then client.wait3dModel(id)",
+        cli: "car-image 3d create --make Toyota --model Camry --year 2025 --color 1a2b3c --wait --out ./models",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/3d",
+        summary: "The caller's recent 3D requests, newest first, with the current price per model.",
+        auth: "bearer",
+        credits: "free",
+        params: ["limit (1-50; default 20)"],
+        returns: "{data:[3d_model…], pricing:{credits_per_model}, request_id}",
+        sdk: "client.list3dModels({ limit: 20 })",
+        cli: "car-image 3d list",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/3d/{id}",
+        summary: "Status, progress and files of one 3D request; a processing model is re-checked with the provider.",
+        auth: "bearer",
+        credits: "free",
+        returns: "{data: 3d_model, request_id}",
+        errors: ["404 unknown id (ids are scoped to the account)"],
+        sdk: "client.get3dModel(id) / client.wait3dModel(id, { intervalMs, timeoutMs, onProgress })",
+        cli: "car-image 3d get <id> --wait",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/3d/{id}/files/{kind}",
+        summary: `One file of a ready model (kind: ${MODEL_3D_FILE_KINDS.join("|")}): a 302 to a signed URL valid for an hour.`,
+        auth: "bearer",
+        credits: "free",
+        returns: "302 Location: <signed storage URL>; X-Content-Length, X-File-Content-Type",
+        errors: ["404 unknown id or kind", "409 model not ready yet (Retry-After: 15)"],
+        notes: "Follow the redirect without the Authorization header; the signed URL needs no key. files.<kind>.url on the model JSON is this endpoint.",
+        sdk: "client.download3dModel(id, 'glb') // { bytes, contentType }",
+        cli: "car-image 3d download <id> --format glb --out model.glb",
+    },
     {
         method: "POST",
         path: "/api/v1/feedback",
         summary: "Rate a delivered image.",
         auth: "bearer",
         credits: "free",
-        params: ["request_id OR make, model, year (+ view, color)", "rating 1-5 and/or verdict good|bad", "reason (optional)"],
+        params: ["request_id OR make, model, year (+ view, color as a preset or hex)", "rating 1-5 and/or verdict good|bad", "reason (optional)"],
         returns: "201 {data:{...}, request_id}",
         sdk: "client.feedback({ requestId, verdict: 'good' })",
         cli: "car-image feedback --request-id <id> --good",
@@ -907,7 +1184,8 @@ export function formatApiReference(filter) {
     const header = [
         `Car Image API — base URL ${DEFAULT_BASE_URL}`,
         `Auth: Authorization: Bearer cimg_… (never in URLs). Errors: application/problem+json {type,title,status,detail,request_id}.`,
-        `Pricing: ${CREDITS_PER_IMAGE} credit per delivered image, $1 = ${CREDITS_PER_DOLLAR} credits, ${FREE_CREDITS} free credits, no subscription.`,
+        `Pricing: ${CREDITS_PER_IMAGE} credit per delivered image, $1 = ${CREDITS_PER_DOLLAR} credits, ${FREE_CREDITS} free credits, no subscription; a 3D model is ${MODEL_3D_PRICE}.`,
+        `Vehicles: make + model + year, or vehicle=<stable id such as veh_395yw8tn73ff8> (from /api/v1/vehicles, /api/v1/vin or resolve), never both. Colors: ${COLORS.length} presets or any hex paint (URLs: color=1a2b3c bare; JSON: "#1a2b3c" or "1a2b3c"; responses echo #1a2b3c).`,
         "",
     ];
     if (endpoints.length === 0) {
@@ -954,9 +1232,13 @@ export function nextStepFor(status) {
         case 403:
             return "This key lacks the required scope. Ask the human to create a key with the right scopes in the dashboard.";
         case 404:
-            return "The vehicle is not in the catalog. Use search_vehicles or resolve_vehicle to find the canonical make/model/year.";
+            return "The vehicle is not in the catalog (or the id is unknown). Use search_vehicles, resolve_vehicle or decode_vin to find the canonical make/model/year or its vehicle id.";
+        case 409:
+            return "Not ready or still in progress (a 3D model still being made, or an Idempotency-Key request still running). Wait the retry_after seconds, then poll again; do not create a second one.";
         case 429:
             return "Rate limited. Wait the retry_after seconds before retrying; do not hammer the API.";
+        case 503:
+            return "Temporarily unavailable (a feature is switched off or at its daily capacity); nothing was charged. Wait the retry_after seconds before trying again, and tell the human if it persists.";
         default:
             return "Retry once if this looks transient; otherwise report the detail and request_id to the human.";
     }