Car images in React and Next.js

npm install @meterapp/car-image-sdk

CAR_IMAGE_API_KEY=cimg_your_key_here

import "server-only";
import { CarImageClient } from "@meterapp/car-image-sdk";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

/** "2018 Mazda MX-5 Miata" to "veh_…", or null when a person should choose. Free. */
export async function vehicleIdFromText(text: string): Promise<string | null> {
  const { data } = await client.resolve(text);
  const askedYear = data.extracted?.year;
  if (data.confidence === "low" || (askedYear && askedYear !== data.params.year)) {
    return null; // show data.candidates and let a person pick
  }
  return data.params.vehicle_id;
}

/** A full or partial VIN to "veh_…", or null when it maps to no catalog vehicle. Free. */
export async function vehicleIdFromVin(vin: string): Promise<string | null> {
  const { data } = await client.decodeVin(vin);
  return data.vehicle?.id ?? null;
}

/** "2024 Porsche 911" for alt text and headings: GET /api/v1/vehicles/{id}, public and free. */
export async function vehicleName(id: string): Promise<string> {
  const { data } = await client.vehicle(id);
  return `${data.year} ${data.make.name} ${data.model.name}`;
}

import "server-only";
import { CarImageClient, isCarImageError, type ImageParams } from "@meterapp/car-image-sdk";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

/** 7 days, the longest a signed URL lives. */
export const IMAGE_URL_TTL_SECONDS = 604800;

/**
 * Signed URLs for a batch of images, in one call and one debit: 1 credit per URL,
 * charged now; loading them is free until they expire. Null when the account cannot pay.
 */
export async function signedCarImages(images: ImageParams[]): Promise<string[] | null> {
  try {
    const { data } = await client.createImageUrls(images, { ttlSeconds: IMAGE_URL_TTL_SECONDS });
    return data.map((item) => item.url);
  } catch (error) {
    // 402: the balance is empty or the plan's monthly vehicle cap is reached. A retry cannot
    // fix either, and nothing was charged: show a placeholder and tell a person.
    if (isCarImageError(error) && error.status === 402) {
      console.error(`Car Image API: ${error.detail} (request ${error.requestId})`);
      return null;
    }
    throw error; // anything else fails this render; an ISR page keeps its last good version
  }
}

import type { View } from "@meterapp/car-image-sdk";
import { signedCarImages } from "@/lib/car-images";

export async function CarImage({
  vehicle,
  view = "front-3-4",
  alt,
  width = 600,
  height = 400,
}: {
  vehicle: string; // a veh_… id
  view?: View;
  alt: string;
  width?: number;
  height?: number;
}) {
  const urls = await signedCarImages([{ vehicle, view, width, height, trim: true, format: "auto" }]);
  if (!urls) {
    return <div role="img" aria-label={alt} style={{ width, height, background: "#f4f4f5" }} />;
  }
  // eslint-disable-next-line @next/next/no-img-element -- the API already sized and encoded it
  return <img src={urls[0]} alt={alt} width={width} height={height} loading="lazy" decoding="async" />;
}

import { CarImage } from "@/components/car-image";
import { vehicleName } from "@/lib/vehicles";

// Regenerate at most once a day, well inside the 7 days the URLs live.
export const revalidate = 86400;

// No paths at build time: each page is rendered on its first visit, then cached.
// Without generateStaticParams the route renders, and mints, on every request.
export async function generateStaticParams() {
  return [];
}

export default async function VehiclePage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params; // a veh_… id you stored
  const name = await vehicleName(id);
  return (
    <main>
      <h1>{name}</h1>
      <CarImage vehicle={id} view="side" alt={`${name}, side view`} />
    </main>
  );
}

// For HTML that outlives the TTL: the URLs keep loading after they expire.
const { data } = await client.createImageUrls(images, {
  ttlSeconds: IMAGE_URL_TTL_SECONDS,
  renew: true, // 1 more credit for each further window in which a URL is opened
});

import type { View } from "@meterapp/car-image-sdk";
import { signedCarImages } from "@/lib/car-images";
import { ViewPicker } from "./view-picker";

const GALLERY_VIEWS: View[] = ["front-3-4", "side", "rear-3-4", "front"];

// A Server Component: one call mints every view (1 credit each); the picker only switches.
export async function CarGallery({ vehicle, alt }: { vehicle: string; alt: string }) {
  const urls = await signedCarImages(
    GALLERY_VIEWS.map((view) => ({ vehicle, view, width: 800, height: 500, trim: true, format: "auto" })),
  );
  if (!urls) return null;
  return <ViewPicker alt={alt} images={GALLERY_VIEWS.map((view, i) => ({ view, url: urls[i] }))} />;
}

"use client";

import { useState } from "react";

export function ViewPicker({ alt, images }: { alt: string; images: { view: string; url: string }[] }) {
  const [current, setCurrent] = useState(images[0]);
  return (
    <figure>
      {/* eslint-disable-next-line @next/next/no-img-element -- a signed URL, sized by the API */}
      <img src={current.url} alt={`${alt}, ${current.view} view`} width={800} height={500} />
      {images.map((image) => (
        <button key={image.view} type="button" aria-pressed={image === current} onClick={() => setCurrent(image)}>
          {image.view}
        </button>
      ))}
    </figure>
  );
}