Car Image API

View saved version →

---
name: car-3d
description: Get a textured 3D model (GLB, USDZ, FBX and a thumbnail) of any real vehicle in any paint color from the Car Image API, for AR views, configurators, game assets, product pages and 3D scenes, and put it on a web page with a two-line embed that Car Image hosts. Covers the order of work (look the vehicle up, confirm the price, create by vehicle id), what a model costs (100 credits, charged at creation, free once the account owns that vehicle in that color), how long it takes and how to wait in a conversation, polling versus webhooks, verifying the webhook signature, downloading the files, publishing a model and the <car-3d> element. Use when the user wants a 3D model, a GLB, a USDZ, an FBX, an AR-ready asset of a car, or a 3D car on a page; do not use for 2D renders (car-image), signed image URLs (car-image-urls) or finding which vehicle to model (vehicle-catalog).
---

# 3D models of real vehicles

`POST /api/v1/3d` turns any catalog vehicle, in any paint, into a textured 3D model: **GLB, USDZ, FBX, a thumbnail and `glb_web`**, a smaller browser build of the GLB. Models are built from the same renders the image API serves, so a model matches the pictures the user already shows, and every color of a vehicle is one mesh with a different texture.

With MCP connected the tools are `create_3d_model`, `get_3d_model` and `publish_3d_model`; they are on `?toolset=all`, which the plugin configures, and a connection on the bare URL has the core twelve only (the `car-image-mcp` skill). Over REST: `POST /api/v1/3d`, `GET /api/v1/3d/{id}`, `GET /api/v1/3d/{id}/files/{kind}`, `GET /api/v1/3d?limit=`, `POST|DELETE /api/v1/3d/{id}/publish`, and the key-free `GET /api/v1/3d/public/{public_id}`. The CLI has `car-image 3d create|get|download|list|publish`; the SDK has `create3dModel`, `get3dModel`, `list3dModels`, `download3dModel`, `publish3dModel` and `unpublish3dModel`. Full reference: [`/docs/3d`](https://carimage.dev/docs/3d?ref=plugin).

## The order of work

1. **Look the vehicle up** (free; the `vehicle-catalog` skill): `resolve_vehicle` for a name, `decode_vin` for a VIN. Keep the vehicle id. A model of the wrong car costs 100 credits, so this step is never skipped, and a lookup that is not `high` confidence in the year asked for goes back to the user first.
2. **Say what it is and what it costs, and wait for a yes**: the year, make and model the lookup named, the paint, 100 credits unless the account already owns it, and ten to twenty minutes for a first model. A preview image of that vehicle in that paint (one vehicle image of the plan's month, no credits; the `car-image` skill shows one in the reply) is a cheap way to agree on both before the charge.
3. **Create it by id**: `create_3d_model({ vehicle: "veh_…", color, publish: true })`. Keep the request `id`.
4. **Wait without hammering**, then hand over the files or the embed.

## What it costs — say this first

- **100 credits per vehicle and color**, charged at creation whether the model is cached, in progress or new. Cache state never changes the price, exactly as with images.
- **Free once owned.** An account that already holds a live request for a vehicle in a color owns it: ordering it again creates a new request for nothing (`billing.credits_charged: 0`, `billing.already_owned: true`), whatever spelling, whether the model is ready or still being made, and even after Car Image rebuilds models with a better recipe. So a re-order is never a second bill; only a failed model (refunded, not owned) makes the next attempt a charged one.
- Polling, listing, downloads, webhook deliveries, **publishing and every load of a published model are free**.
- A model that **fails is refunded** in full. A `503` at capacity charges nothing.
- Credits are not sold: a paid plan includes some each month (Pro 1,000, Business 4,000) and every account gets 100 at signup. **Tell the user the price and confirm before calling `create_3d_model`** for a vehicle and color the accou

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: car-image
description: "Show or fetch a studio-quality, transparent-background image of a real vehicle (any make, model and year from 1990-2027), in a conversation or for a product page, a listing, a comparison, an email or a deck, and fetch catalog make logos with get_make_logo. Every image takes two steps - look the vehicle up first (resolve_vehicle, search_vehicles or decode_vin, free, the vehicle-catalog skill), then show it by its vehicle id (create_car_image_urls for the inline ChatGPT card; get_car_image in other chat hosts; one vehicle image of the plan's month). Covers the Car Image API by Meter - the chat workflow, angles, paint, sizing, what a plan counts (vehicle images), and how to handle 402, 404 and 429. Works before sign-in: lookups and a free preview of the picture a vehicle's page already shows (preview_car_image), then the account for the exact image. Use for any request involving a picture of a car, truck, motorcycle or other vehicle, including \"show me a car\" or \"a random car\"; do not use for embedding URLs in a browser or document (car-image-urls), SDK and CLI code (car-image-sdk), 3D models (car-3d), or connection setup (car-image-mcp)."
---

**ChatGPT image card:** For a requested image, after the free vehicle lookup, use `create_car_image_urls` with the returned `vehicle` id, `ttl_seconds: 604800`, `max_uses: 0`, and renewal off. ChatGPT displays the returned images in an inline card. Do not call `get_car_image` first or make another image call to fix display. Reuse an unexpired URL. If the card is unavailable, show the exact returned URL as a clickable link and state expiry. These ChatGPT instructions take precedence over the general chat examples below. Other hosts keep their own display workflow.

When no view is specified, use **Front three-quarter (facing left)**, `view=front-3-4` (35°). Preserve any view the user explicitly requests.

# Car Image API

Studio-quality, transparent-background renders of any vehicle in the open [`@meterapp/vehicle-db`](https://github.com/MeterApp/vehicle-db) catalog — 1,608 makes, 42,334 models, model years 1990-2027. Nine camera views, any paint color, PNG/WebP/JPG up to 1024 px.

## Check readiness and quality

When the human asks whether an image is already prepared/cached or what quality it has, resolve the vehicle first, then call `get_image_availability({ vehicle, view, color })`. Omit `view` for all nine. **Prepared means cached and quick to serve from storage without waiting for a new render.** Report `cached` and `quality` (`standard`, `enhanced`, `premium`, or null), and `render_eta` when uncached. The check is free: it renders, queues and counts nothing. Checking never authorizes generating or upgrading. A missing public preview is not proof that an authenticated view needs generation.

## Two steps, every time

**1. Look the vehicle up (free).** Do this before every render, including for a car you know well and a car you picked yourself. If the `vehicle-catalog` skill is available, use it for this step: it covers ambiguity, VINs, years and what to do when nothing matches. The short version:

- `resolve_vehicle({ query })` with the year, make and model, plus the view and paint if the user named them: `"red 2018 Mazda MX-5 Miata, side view"`. It returns `params.vehicle_id` with a `view` and a `color`, `confidence` and up to five `candidates`. `extracted` is what the phrase itself said: where `extracted.view` or `extracted.color` is null, the value in `params` is only the default (`front-3-4`, `silver`), not something the user chose. Leave descriptions out of the phrase ("the electric one", "their sporty model"): it reads names, not descriptions. When the user gave no year, put one in and say which you chose.
- `decode_vin({ vin, year? })` when the user gave a VIN; `search_vehicles({ query, year?, limit? })` to list a make's models or a model's years.

**2. Show it by id (one vehicle image).** `get_car_image` with `vehicle: "veh_…"`, `view` and

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: car-image-mcp
description: Connect an agent, IDE or chat app to the Car Image API over MCP, and fix it when the tools do not appear. Covers the hosted HTTP server, the catalog server that needs no sign-in (lookups and free previews), the local stdio alternative, browser OAuth sign-in for plugin installs and chat-app connectors (the plugin takes no key), API-key setup for connections a person adds themselves in Claude Code, Codex, Cursor, Claude Desktop and generic MCP hosts, what each of the twelve core tools costs (catalog lookups, VIN decoding, images, signed URLs, the account) and which twenty-one more ?toolset=all adds (make logos, 3D models, image options, the API reference, pricing, help and billing links), and how to diagnose a 401, a missing server or an empty tool list. Use for setup, configuration and connection troubleshooting; do not use for calling the API from code (car-image-sdk) or for image workflows once the tools already work (car-image).
---

**ChatGPT image card:** For a requested image, after the free vehicle lookup, use `create_car_image_urls` with the returned `vehicle` id, `ttl_seconds: 604800`, `max_uses: 0`, and renewal off. ChatGPT displays the returned images in an inline card. Do not call `get_car_image` first or make another image call to fix display. Reuse an unexpired URL. If the card is unavailable, show the exact returned URL as a clickable link and state expiry. These ChatGPT instructions take precedence over the general chat examples below. Other hosts keep their own display workflow.

When no view is specified, use **Front three-quarter (facing left)**, `view=front-3-4` (35°). Preserve any view the user explicitly requests.

# Connecting over MCP

Two servers expose the same tools. Prefer the hosted one — there is nothing to install and nothing to keep up to date.

- **Hosted (recommended):** `https://carimage.dev/api/mcp`, Streamable HTTP, with browser OAuth sign-in in supported hosts
- **Local stdio:** `npx @meterapp/car-image@latest mcp`, which uses the key `car-image login` saved for the CLI

A third, the **catalog server** at `https://carimage.dev/api/mcp/catalog`, needs no account at all: `resolve_vehicle`, `search_vehicles`, `list_image_options`, `get_pricing`, `search_help` and `describe_api`, plus `preview_car_image`, the picture a vehicle's page on carimage.dev already shows, free. It renders nothing and reads no account, so it never asks anyone to sign in. The plugin connects it next to the hosted server, so an install can look cars up and show previews before the user signs in.

Both come in two toolsets. The default, `core`, is the twelve core tools an agent needs to find a vehicle, render it and watch the balance: `resolve_vehicle`, `search_vehicles`, `decode_vin`, `check_vehicles`, `get_car_image`, `create_car_image_urls`, `get_account`, `request_feature`, `report_issue`, `upvote_feedback` and `submit_review`. Make logos, 3D models, image options, the API reference, pricing, help and billing links are twenty-one more with `?toolset=all` on the hosted URL or `--toolset all` for `car-image mcp`, forty-one tools in all. Fewer tools cost the agent less context and make the right one easier to pick, so opt in when the agent should also fetch logos, make 3D models or answer product and billing questions; the plugin does.

## Plugin installs: sign in with your browser

The `car-image` plugin configures two hosted servers: **`car-image-catalog`**, the catalog server, which works at once, and **`car-image`**, the hosted server with `?toolset=all` (the skills teach the logo, 3D, pricing and help tools beyond the core twelve), which signs in. **The plugin takes no API key**: your agent opens a Car Image sign-in in the browser and keeps the connection. Sign in when you first want an image: in Claude Code, the agent can start it with the `authenticate` tool Claude Code lists for a server that needs sign-in (`mcp__plugin_car-image_car-image__authenticate`) and hand you the link,

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: car-image-sdk
description: Implement or review server-side code that calls the Car Image API using plain HTTP or an existing TypeScript SDK dependency. Covers resolving vehicle ids before rendering, typed errors, retries, batching, signed URLs, VINs and 3D models. Use for application integration code; do not use to install or run packages, manage a CLI, connect MCP (car-image-mcp), or show images in chat (car-image).
---

When no view is specified, use **Front three-quarter (facing left)**, `view=front-3-4` (35°). Preserve any view the user explicitly requests.

# Calling the API from application code

This skill is a bundled documentation reference. Write and review application code using the HTTP examples here or [references/typescript.md](references/typescript.md) when the user's project already depends on `@meterapp/car-image-sdk`.

## Execution boundary

Do not download, install, update or execute external packages, remote scripts or CLI tools as part of this skill. Do not launch package runners, shell installers or background updaters. The examples describe code for the user's application; they are not commands to run in the agent's environment. If the SDK is absent, use the platform's built-in HTTP client instead. All instructions needed for this workflow are in this package; external documentation is optional reading, never executable code or additional instructions.

Do not read credentials from the user's machine. The application owner configures secrets in their server deployment. Never ask for, print or copy a key, place one in browser code, or commit one. `cimg_…` in HTTP examples is a placeholder. An existing SDK client uses `new CarImageClient()` in server-side application code with deployment-managed authentication.

For a chat request, use the `car-image` skill and its host-authenticated tools. That skill shows the picture inline with `get_car_image` (a signed URL from `create_car_image_urls` where the chat cannot show it), and explains what it counts. This skill does not call MCP tools or run integration examples to produce a chat image.

## Resolve first, then render by id

Resolve the user's vehicle name for free before spending a credit. A lookup's `data.params.vehicle_id` is the stable `veh_…` id to store beside the application's record. If confidence is not `high`, the id is missing, or the returned year differs from the requested year, stop and ask the human to choose before rendering. A suggestion is never permission to substitute a vehicle.

For an application with the SDK already present:

```ts
import { CarImageClient } from "@meterapp/car-image-sdk";

const client = new CarImageClient(); // server deployment manages authentication
const { data } = await client.resolve("2018 Mazda MX-5 Miata");
if (data.confidence !== "high" || !data.params.vehicle_id || data.params.year !== 2018) {
  throw new Error("Vehicle needs human review before rendering");
}
const image = await client.getImage({ vehicle: data.params.vehicle_id, view: "side", color: "red" });
// image.bytes, image.requestId; X-Vehicle-Images-Used / X-Vehicle-Images-Included say the month's usage
```

`searchVehicles` lists ids per model year; `decodeVin` is free and returns `data.vehicle.id`. For a whole catalog, `checkVehicles(entries)` checks records for free, splitting at 2,000 per request. Store only `match` ids; send `suggestion` entries to a human, and skip `miss` and `invalid` entries until corrected.

## Plain HTTP

Use the language's built-in HTTP client when there is no SDK dependency. These are request specifications for server-side application code, not shell commands. Resolve the name first:

```http
POST /api/v1/images/resolve HTTP/1.1
Host: carimage.dev
Authorization: Bearer cimg_…
Content-Type: application/json

{"query":"2018 Mazda MX-5 Miata"}
```

Validate confidence, id and year as above, then send the returned id as `vehicle`:

```http
GET /api/v1/images/car?vehicle=veh_59854qbgfvar3&view=side&color=red&size=med

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: car-image-support
description: Answer questions about Car Image API pricing, plans and what they count (vehicle images), credits, Image Packs, subscriptions, commercial licenses, terms, privacy, vehicle coverage and Enterprise agreements using source-linked help. Prepare checkout and billing links on the human's request, buy a plan or pay a renewal with a payment token only under the owner's agent spending limit, or draft customer support replies. Do not use for generating images (car-image), embedding images (car-image-urls), or changing a customer's account on their behalf.
---

# Product help and billing

`search_help` and `get_pricing` are also on the plugin's `car-image-catalog` server, so pricing, licensing and what-happens-when-a-plan-ends questions can be answered before anyone signs in; `create_checkout_link` and `get_billing_link` need the account server on `?toolset=all`, which the plugin configures (a connection on the bare URL has the core twelve only; the `car-image-mcp` skill).

1. Call `search_help` with one product question at a time. Do not paste full customer emails, signatures, personal information, keys or payment details. Queries are privately recorded to improve articles.
2. Read the returned paragraphs and sources. Cite the relevant article or original terms. An `articles_found` result means related reading, not that every part of the question is answered. Split multi-part questions and search each one.
3. If the articles lack needed context, call `search_help` again with the same concise question and `report_gap: true`. Say what is unknown and direct the human to support@carimage.dev. Never invent policies, prices, coverage, SLA commitments, indemnities or agreement exceptions.
4. Use `get_pricing` for current plan prices, monthly vehicle images, limits per tier, Image Packs (`image_packs`, `add_ons`) and 3D cost; it works before sign-in (the catalog server has it too), and every plan and Image Pack offer carries a `checkout_url` that signs the human in, or up, and opens Stripe Checkout. Use `get_account` only for the connected account's plan, this month's usage against its allowance (`limits_usage.vehicle_images_this_month`), credit balance and next tier (`next_plan`). A support agent's credentials do not identify an email sender's account.
5. When the human asks to subscribe, call `create_checkout_link` with `plan` (pro, business; optional `interval: month|year`). For an Image Pack, hand them the offer's `checkout_url` from `get_pricing`. Return `data.url` and `data.message`. Payment happens in the browser; a link is not a successful purchase. Credits are not sold: when the human asks for more credits or more images, explain what a higher plan or an Image Pack adds instead.
6. `get_billing_link` returns billing settings. Connected apps and keys without billing:write receive a sign-in dashboard link for settings, and `create_checkout_link` gives them a checkout link that signs the human in first. Owner keys with billing:write can receive private Stripe links; never publish or forward those to another customer. Existing subscriptions go to the dashboard for review; no tool switches a plan or charges a saved card.

### When to buy instead of handing over a link

`purchase_plan` (and `pay_invoice` for an open renewal, `billing.renewal_due` in `get_account`) pays with a Stripe Shared Payment Token (`spt_…`) your platform minted from the buyer's card. Use it only when all of these hold; otherwise hand the human `checkout_url`:

- the human asked you to buy, or their agent spending limit (`billing.agent_spend` in `get_account`) covers this plan and amount;
- you hold a payment token for this seller (never ask for, read or type a card number; one is refused);
- you ran it with `dry_run: true` first and told the human the amount, the card and that a token pays once (renewals need a card they save, or `pay_invoice` with a fresh token).

Then call it again with the same `purchase_id` and `dry_run: fal

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: car-image-urls
description: Put a vehicle image into a web page, React component, app, email, Markdown file, PDF or slide deck using signed delivery URLs, so the browser loads the image without ever holding an API key, or share one as a link where a conversation cannot show a tool's image (a terminal such as Claude Code or Codex) or the person asks for a link. Use whenever the output is HTML, JSX, Markdown, CSS, an email template, a document or a spreadsheet rather than a picture shown in the chat; covers looking each vehicle up once and minting by its id, TTL and use caps, batching up to 50, inventory grids from a list of VINs, caching, alt text and expiry. Do not use to show a car in a chat app (car-image shows it inline with get_car_image), for downloading bytes in a script (car-image), or for finding which vehicle to render (vehicle-catalog).
---

**ChatGPT image card:** For a requested image, after the free vehicle lookup, use `create_car_image_urls` with the returned `vehicle` id, `ttl_seconds: 604800`, `max_uses: 0`, and renewal off. ChatGPT displays the returned images in an inline card. Do not call `get_car_image` first or make another image call to fix display. Reuse an unexpired URL. If the card is unavailable, show the exact returned URL as a clickable link and state expiry. These ChatGPT instructions take precedence over the general chat examples below. Other hosts keep their own display workflow.

When no view is specified, use **Front three-quarter (facing left)**, `view=front-3-4` (35°). Preserve any view the user explicitly requests.

# Signed delivery URLs

A signed URL is a key-free link to one rendered vehicle image. You mint it server-side; the browser, email client or PDF reader loads it directly. **The API key never goes where a browser can read it: a page gets a signed URL, or a copy of the file you serve yourself.**

In a conversation, minting goes through the connected `create_car_image_urls` tool. In an application, the server mints with the SDK client the app already has; setting that client up is the `car-image-sdk` skill's job, not this one's.

## Chat replies

To show a vehicle in a chat app, do not mint a URL: `get_car_image` returns the picture and the host displays it inline (the `car-image` skill covers that and random-car selection). Mint a signed URL in a conversation only when the person will not see a tool's image (a terminal such as Claude Code or Codex, or a host that hands tool images to the model alone) or when they ask for a link. Then resolve the vehicle first and mint once with `ttl_seconds: 604800`, `max_uses: 0` and renewal off unless requested.

In Codex, show each exact returned `data[].url` as a normal clickable Markdown link, for example `[View the vehicle image](https://example.com/image.png)` with the returned URL substituted. Do not use Markdown image syntax or paste the tool's image `markdown` into these chats, even if generic tool text recommends it. Open that same URL with an available browser-opening tool, preferably in the in-app browser (for example, `open_in_codex` with a browser target). Retain the clickable link in the final reply whether opening succeeds or not. If no browser tool is available, just provide the link. Do not claim the browser opened unless the tool confirms it.

In a terminal (Claude Code), put the plain `data[].url` on its own line, which the terminal makes clickable; Markdown image syntax does not render there. In Claude's apps, when the person asked for a link, paste each returned `data[].markdown` outside code fences; if only `url` is returned, use `![year make model, view, color](https://example.com/image.png)` with the exact returned URL. Do not automatically open a browser. Other hosts may use inline images when supported, otherwise a clickable link.

Include a short vehicle caption and expiry. Reuse unexpired URLs; do not download the image or make another paid image call to work around chat display. These host-specific rules app

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: vehicle-catalog
description: Look a vehicle up before it is rendered - turn what someone asked for ("a 2018 Miata", "the new 911 GT3", a VIN) into the exact catalog make, model and year the Car Image API can render and the stable vehicle id (veh_…) that names it, or check what a make offers and which years exist, or which of a whole list of vehicles the catalog carries. Covers resolve_vehicle, search_vehicles, check_vehicles for lists and free VIN decoding (full or partial VINs), reading confidence and year mismatches, trims and body styles, picking a car when none was named, missing vehicles, and the open @meterapp/vehicle-db package for offline lookups, dropdowns and validation. Use first, before any image, signed URL or 3D model of a vehicle, and when building a vehicle picker or validating user input; do not use for fetching the image itself (car-image), embedding it in a page (car-image-urls) or making a 3D model (car-3d).
---

**ChatGPT image card:** For a requested image, after the free vehicle lookup, use `create_car_image_urls` with the returned `vehicle` id, `ttl_seconds: 604800`, `max_uses: 0`, and renewal off. ChatGPT displays the returned images in an inline card. Do not call `get_car_image` first or make another image call to fix display. Reuse an unexpired URL. If the card is unavailable, show the exact returned URL as a clickable link and state expiry. These ChatGPT instructions take precedence over the general chat examples below. Other hosts keep their own display workflow.

When no view is specified, use **Front three-quarter (facing left)**, `view=front-3-4` (35°). Preserve any view the user explicitly requests.

# Finding the right vehicle

Renders are addressed by **make, model, year** — or by the one **vehicle id** that stands for the three. The lookup comes first, every time: the catalog files cars under its own names, a render of the wrong car still counts against the plan's month, and a 3D model of the wrong car costs a hundred.

The catalog is the open [`@meterapp/vehicle-db`](https://github.com/MeterApp/vehicle-db) — 1,608 makes and 42,334 models across model years 1990-2027, built from public sources (NHTSA vPIC, UK DfT/DVLA, NZTA, Malaysia JPJ and others). It covers cars, motorcycles, trucks, buses, MPVs and more, internationally — not just the US market. Every make, model and model year also has a public page under the same slugs, from [carimage.dev/cars](https://carimage.dev/cars?ref=plugin) down to `/cars/<make>/<model>/<year>`: link it when a person wants to browse what the catalog holds.

All the lookups below are **free**. Use them liberally.

`resolve_vehicle` and `search_vehicles` also work before anyone signs in: the plugin's `car-image-catalog` server serves them with no account, together with `preview_car_image`, the picture a vehicle's page already shows (the `car-image` skill, "Before the account is connected"). `decode_vin` and `check_vehicles` are on the account server, like every render.

## Check readiness and quality

When the human asks whether an image is already prepared/cached or what quality it has, resolve the vehicle first, then call `get_image_availability({ vehicle, view, color })`. Omit `view` for all nine. **Prepared means cached and quick to serve from storage without waiting for a new render.** Report `cached` and `quality` (`standard`, `enhanced`, `premium`, or null), and `render_eta` when uncached. The check is free: it renders, queues and counts nothing. Checking never authorizes generating or upgrading. A missing public preview is not proof that an authenticated view needs generation.

## Look up, then hand over the id

| You have | Call | Take |
| --- | --- | --- |
| A car named in words ("2018 Mazda MX-5 Miata") | `resolve_vehicle({ query })` | `params.vehicle_id`, plus `params.view` and `params.color` |
| A VIN, full or partial | `decode_vin({ vin, year? })` | `vehicle.id` |
| A make, and a question about what it offers | `search_vehicles({ query, ye

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.