@meterapp/car-image

CLI and MCP server for the Car Image API by Meter — studio-quality, transparent-background renders of any vehicle in the open @meterapp/vehicle-db catalog (1,607 makes, 46,120 models, 1990–2027). Eight camera views, any paint color (fifteen named presets or any hex), PNG/WebP/JPG up to 1024 px, at any width × height, transparent or on a solid background. Plus stable vehicle ids, free VIN decoding and textured 3D models (GLB, USDZ, FBX).

Pricing: 1 credit per image (cached or generated) · Free 100 credits at signup (evaluation and personal projects) · Pro $29/mo 25,000 credits a month (commercial license while active) · Business $99/mo 150,000 credits · $1 per 100 credits beyond the allowance, purchased credits never expire. A 3D model is 100 credits, once per vehicle and color, and hosting it is free; VIN decoding, catalog lookups, polling and downloads are free.

Install

npx @meterapp/car-image                      # no install
npm install -g @meterapp/car-image           # or pnpm add -g / bun add -g
curl -fsSL https://carimage.dev/install.sh | sh

Node.js 20+.

60-second quickstart

car-image                                  # onboarding: login → account → quick check → next steps
car-image login                            # browser device flow; key stored with mode 0600
car-image get --make Porsche --model 911 --year 2024 --view side --color red --out porsche.png
car-image get --make Audi --model RS6 --year 2023 --width 600 --height 400 --trim --background white --format webp
car-image get --vehicle veh_395yw8tn73ff8 --color 1a2b3c        # by stable vehicle id, in any hex paint
car-image url --make BMW --model M3 --year 2022 --ttl 86400     # signed, key-free URL for a web page
car-image resolve red 2024 porsche 911 side view                # free text → parameters + ready command
car-image vin 1HGCM82633A004352                                 # decode a VIN (free) → the catalog vehicle and its id
car-image 3d create --make Porsche --model 911 --year 2024 --color red --wait --out ./models   # 100 credits
car-image agent-config --host claude-code                       # MCP setup for agents
car-image request vehicle Toyota Sienna --year 2024            # catalog missing a car? ask for it (free)

Commands

| Command | What it does | | --- | --- | | car-image | Interactive onboarding on a TTY (update check → login if needed → whoami → free quick check → next steps). Prints help when not interactive. | | login [--no-browser] [--client-name <name>] | Device-flow sign-in. Opens the browser, shows the code, polls, stores the key at $CAR_IMAGE_CONFIG or $XDG_CONFIG_HOME/car-image-api/config.json (default ~/.config/…) with mode 0600. The key is printed once. | | logout | Removes the stored key. | | whoami (alias status) | Credits (≈ $), auto-reload, payment method, 30-day usage, masked key prefix and scopes, base URL. | | doctor [--json] [--yes] [--no-image] | Smoke-tests every endpoint: health, options, vehicles years/makes/models, search, resolve, account, signed-URL mint (1 credit) + HEAD/GET redeem, optional keyed image GET (1 credit, asks unless --yes), feedback. Prints check / status / latency / cache / credits / notes and fix hints; exit 1 on any failure. | | get (--make --model --year \| --vehicle veh_…) [--view] [--color preset\|<hex>] [--size \| --width [--height] [--fit contain\|cover\|inside]] [--background transparent\|white\|black\|<hex>] [--trim [--padding 0-50]] [--format png\|webp\|jpg\|auto] [--out file\|-] [--url] [--json] | Downloads one image (1 credit). --url prints a signed URL instead. --vehicle takes a stable id from search, resolve or vin; --color takes a preset or any hex (#1a2b3c, 1a2b3c, #abc). See Sizing, backgrounds and trimming. | | url (--make … \| --vehicle …) [--view] [--color] [--size\|--width\|--height] [--fit] [--background] [--trim] [--format] [--ttl 3600] [--max-uses 0] [--renew [--renew-days 365]] [--idempotency-key <key>] [--json] | Creates one signed delivery URL (1 credit). --renew keeps it alive past the TTL at one credit per opened window, for email and documents. | | url --batch images.json [--ttl 3600] [--max-uses 0] [--renew [--renew-days 365]] [--idempotency-key <key>] [--json] | Creates up to 50 signed URLs in one call (1 credit each). Entries name the car by make, model, year or by vehicle, and may carry view, color, size, width, height, fit, background, trim, padding and format. | | 3d create (--make --model --year \| --vehicle veh_…) [--color preset\|<hex>] [--webhook-url <https url> [--webhook-secret <s>]] [--idempotency-key <key>] [--wait] [--out <dir>] [--json] | Builds a textured 3D model (GLB, USDZ, FBX, thumbnail) of one vehicle in one paint: 100 credits at creation, cached or new; a failed model is refunded. Answers at once with the request id; --wait polls with a progress line until it is ready (one to five minutes) and --out then downloads every file into the directory (implies --wait). | | 3d get <id> [--wait] [--json] · 3d list [--limit 20] [--json] | Status, progress, stage, estimate and, once ready, the files of one request (--wait polls until it settles); your recent requests with the current price per model. Free. | | 3d download <id> [--format glb\|usdz\|fbx\|thumbnail] [--out <file> \| --out -] | Saves one file of a ready model (default glb, named after the vehicle and paint). Follows the signed storage redirect itself, without the key. Free. | | search <query…> [--limit] [--year] | Fuzzy catalog search (free, no key). --json shows each model hit's vehicle ids per year. | | resolve <free text…> | Free text → exact parameters (with the vehicle id), candidates, confidence (high, medium or low) and a ready-to-run car-image get …. | | vin <VIN> [--year <year>] [--json] | Decodes a full or partial VIN (* for unknown positions) with NHTSA data: year, make, model, trim, body, engine, transmission, plant, and the catalog vehicle it maps to with a ready car-image get --vehicle …. Free, key required. | | options | Views (with yaw), colors (hex swatches, plus how custom hex paint is spelled), sizes, fit modes, backgrounds, trim limits, formats, pricing, catalog coverage, vehicle ids. | | describe [operationId\|path\|all] [--json] | Explains the REST API from /openapi.json: parameters with enums/defaults, response headers, error codes, agent notes. | | feedback (--request-id ID \| --make … --model … --year … \| --vehicle veh_…) [--view] [--color] (--rating 1-5 \| --good \| --bad) [--reason] | Rates a delivered image. | | request list [--kind vehicle\|feature] [--status open\|planned\|in_progress\|done\|declined] [--sort top\|new] [--limit N] | The public request board: votes, kind, title, id, status. Free, no key. | | request vehicle <make> <model> [--year 2024] [--note "…"] | Asks the team to add a vehicle the catalog lacks; upvotes the existing request if someone already asked. You get an email when it is live. | | request feature "<title>" [--details "…"] | Files a feature idea for the API, CLI, SDK or MCP tools. | | request show <id> · request upvote <id> · request comment <id> "<text>" | Read one request with its comments, add your vote (idempotent), or comment. | | about building "<what you are building>" | Tells the team what you are building. Private: only the Car Image team sees it. | | about referral <search\|ai_assistant\|github\|npm\|twitter_x\|linkedin\|reddit\|hacker_news\|youtube\|friend_or_colleague\|blog_or_article\|other> [--detail "…"] | Tells the team how you found the API. Private. | | billing [--plan pro\|business [--yearly]] [--credits 100\|500\|1000\|2500\|10000] [--portal] [--no-browser] | Opens hosted Stripe Checkout for a plan or extra credits, or the billing portal. An account already on a plan is switched in place. The CLI never touches card data. | | mcp [--toolset core\|all] | Runs the stdio MCP server (see below). core (default) is the twelve image, VIN and 3D tools; all adds the request board. | | agent-config [--host claude-code\|claude-desktop\|cursor\|chatgpt\|generic] [--remote] [--json] | Ready-to-paste MCP configuration. | | update [--check] | Compares with the npm registry and updates via npm/pnpm/bun (detected). | | config path \| get <key> \| set <key> <value> \| list | Keys: autoUpdate (ask|always|never), telemetry (on|off), baseUrl. | | telemetry on\|off\|status | Anonymous usage events (see below). | | help [command] | Help. |

Global options: --json, --quiet, --base-url <url>, --api-key <key>, --no-color, -h/--help, -v/--version. Environment: CAR_IMAGE_API_KEY, CAR_IMAGE_API_URL, CAR_IMAGE_CONFIG, CAR_IMAGE_TELEMETRY=0. Exit codes: 0 ok · 1 failure · 2 usage error. API errors are shown as Title: detail, a fix hint (401 → car-image login, 402 → car-image billing, 429 → wait Retry-After) and the request_id.

Sizing, backgrounds and trimming

get and url (and every entry of a --batch file) take the same sizing options. The source render is a square, and nothing is upscaled past 1024 px.

| Option | Values | Effect | | --- | --- | --- | | --color | white black gray silver blue red green brown beige tan orange yellow gold burgundy purple · hex as #rrggbb, rrggbb, #rgb or rgb | The paint; default silver. Any hex is a real paint, not a nearest preset; the API echoes it as #rrggbb. Quote a leading # in shells that treat it as a comment, or write the hex bare. | | --vehicle | veh_ + 13 characters | Names the make, model and year by their stable id (from search --json, resolve or vin) instead of --make/--model/--year; never both. | | --size | thumb 256 · small 512 · medium 768 · large 1024 | Square presets; shorthand for --width. | | --width, --height | 1–1024 px each | One dimension keeps the aspect ratio. Both together return exactly width × height — --width 600 --height 400 used to come back 400×400; it is now 600×400. | | --fit | contain (default) · cover · inside | Only matters with both dimensions. contain returns exactly the box with the whole car and transparent (or --background) padding; cover fills the box and centre-crops; inside keeps the car within the box and may return a smaller image (the old behaviour). | | --background | transparent (default) · white · black · hex as rrggbb, #rrggbb, rgb or #rgb | A solid background flattens PNG and WebP too. jpg cannot be transparent and defaults to white. | | --trim [--padding 0-50] | flag; padding in percent | Crops to the car's alpha bounds before sizing so it fills the box — recommended for non-square layouts. --padding keeps a margin of 0–50 % of the trimmed car's longer side and only applies with --trim. | | --format | png (default) · webp · jpg · auto | auto lets each client negotiate WebP or PNG from its Accept header (Vary: Accept); a signed URL created with auto negotiates on every load, so one URL serves every browser. |

car-image get --make Porsche --model 911 --year 2024 --view side --width 1024 --height 512 --trim --padding 6 --out hero.png
car-image get --make Porsche --model 911 --year 2024 --width 400 --height 400 --fit cover --background f4f4f4 --format jpg
car-image get --vehicle veh_395yw8tn73ff8 --color 1a2b3c --view rear-3-4 --out custom-paint.png
car-image url --make Porsche --model 911 --year 2024 --width 600 --height 338 --trim --format auto --ttl 604800

A batch file is an array (or {"images": [...]}) of 1–50 entries:

[
  { "make": "Toyota", "model": "RAV4", "year": 2023, "view": "front-3-4", "width": 512, "height": 320, "trim": true, "padding": 5 },
  { "make": "Honda", "model": "CR-V", "year": 2023, "view": "front-3-4", "width": 512, "height": 320, "fit": "cover", "background": "white", "format": "webp" }
]

car-image options prints the fit modes, the background vocabulary and the padding ceiling the server currently advertises.

VIN decoding

car-image vin <VIN> decodes a full 17-character VIN, or a partial one of at least 5 characters with * for each unknown position, with NHTSA vPIC data. It prints the year, make, model, trim, body class, engine, transmission, manufacturer and plant, the decoder's notes (a wrong check digit, a year that disagrees with --year), and the catalog vehicle the VIN maps to with a ready car-image get --vehicle veh_…. Free; needs a key. --json prints the full payload, including every decoded attribute. Invalid VIN means the argument is not a VIN (the message says why); VIN not recognized means NHTSA has no record of it: re-check it, above all the first three characters (the maker code), or put * in each position you are unsure of and add --year. NHTSA's data covers vehicles made for the US market, so for any other car search by name with car-image search.

car-image vin 1HGCM82633A004352
car-image vin "1HGCM826*3A" --year 2003 --json

3D models

car-image 3d create builds a textured 3D model of any catalog vehicle in any paint — GLB, USDZ, FBX, a PNG thumbnail and a browser build (glb_web) — from the same renders the images use. It costs 100 credits when the request is made, whether the model is cached, in progress or new, and nothing for a vehicle and color you already own (a failed model is refunded); polling, downloads and publishing are free. A model takes one to seven minutes.

car-image 3d create --make Toyota --model Camry --year 2025 --color 1a2b3c --wait --out ./models
#   Queued: 3D model 2222…-2222 for 2025 toyota camry in #1a2b3c — charged 100 credits, 4,000 remaining
#   Waiting: processing 40% (geometry) · ~120 s left
#   ✓ Saved models/2025-toyota-camry-1a2b3c.glb (glb, 6.4 MB) … .usdz … .fbx … .png
car-image 3d create --vehicle veh_errc87t1jgata --webhook-url https://example.com/hooks/3d --webhook-secret "$HOOK_SECRET" --json
car-image 3d get <id> --wait
car-image 3d download <id> --format usdz --out camry.usdz
car-image 3d publish <id>          # key-free URLs on our CDN and a two-line <car-3d> embed, printed ready to paste
car-image 3d publish <id> --unpublish
car-image 3d list

Without --wait the command returns at once with the request id; 3d get <id> shows status (queued, processing, ready, failed), progress, stage and an estimate, and once ready the files with their sizes and URLs. --webhook-url (https, public host) gets one POST {"event": "3d_model.ready" | "3d_model.failed", "data": …, "sent_at": …} when the model settles, signed as X-CarImage-Signature: sha256=<hex HMAC of the raw body> when --webhook-secret is set. 3d create --publish publishes at creation and prints the embed; 3d publish <id> does it later, --unpublish takes it down (the links stop working within the hour). 3d create sends an Idempotency-Key like url does (--idempotency-key for retries from other processes). A 503 means 3D models are switched off or at the day's capacity: nothing is charged, and the hint says when to retry.

Idempotent URL creation

url sends an Idempotency-Key on every call — a generated sdk_<uuid> unless you pass --idempotency-key <key> (1–255 characters of A–Z a–z 0–9 . _ : -). The same key with the same request within 24 hours replays the first response (Idempotent-Replayed: true) instead of minting and billing again, so a retried command or a re-run job never pays twice; the same key with a different request is a 422, and a retry that overtakes the first request still in flight is a 409 with Retry-After. Use your own key when a retry may come from another process, such as a job queue:

car-image url --batch listing-4711.json --ttl 604800 --idempotency-key listing-4711-v1 --json

Agents (MCP)

Two servers expose the same tools, in two sets:

• Core (default), twelve tools: get_car_image, create_car_image_urls, search_vehicles, resolve_vehicle, decode_vin, list_image_options, get_account, rate_image, create_3d_model, get_3d_model, publish_3d_model, describe_api. Only get_car_image, create_car_image_urls (1 credit per image) and create_3d_model (100 credits per model, free once the account owns the vehicle and color) cost credits.
• All, twenty tools: the core twelve plus the free request board — list_requests, request_vehicle, request_feature, get_request, upvote_request, comment_on_request, share_building and share_referral.

get_car_image, each create_car_image_urls entry, rate_image and create_3d_model name the car by make, model and year or by vehicle (a stable id from search_vehicles, resolve_vehicle or decode_vin) and take color as one of the presets or any hex such as #1a2b3c; the image tools also take fit, background, trim and padding alongside view, size and format (auto included: a signed URL negotiates per viewer, an inline get_car_image delivers PNG for it), and create_car_image_urls honors renew and renew_days and takes idempotency_key, forwarded as the Idempotency-Key header so a retried tool call replays the first result (idempotent_replayed: true) instead of billing again. resolve_vehicle reports a confidence of high, medium or low. create_3d_model returns the request at once; agents poll get_3d_model until status is ready and hand over files.<kind>.url.

• Remote (recommended): https://carimage.dev/api/mcp with header Authorization: Bearer ${CAR_IMAGE_API_KEY}. Append ?toolset=all for the request board.
• Local stdio: car-image mcp (reads CAR_IMAGE_API_KEY or the stored key); car-image mcp --toolset all for the request board.

# Claude Code
claude mcp add --transport http car-image https://carimage.dev/api/mcp --header "Authorization: Bearer ${CAR_IMAGE_API_KEY}"
claude mcp add --transport http car-image "https://carimage.dev/api/mcp?toolset=all" --header "Authorization: Bearer ${CAR_IMAGE_API_KEY}"   # with the request board
claude mcp add car-image-local --env CAR_IMAGE_API_KEY=${CAR_IMAGE_API_KEY} -- npx -y @meterapp/car-image mcp

# Cursor (.cursor/mcp.json), Claude Desktop, ChatGPT, generic:
car-image agent-config --host cursor|claude-desktop|chatgpt|generic

The server instructions tell agents that every image costs 1 credit and a 3D model 100 (to be confirmed with the human first), to keep keys out of URLs, to ask a human before buying credits on 402, and never to subscribe to, change or cancel a plan on their own.

Updates

On interactive runs the CLI checks npm at most once a day (cached next to the config file). autoUpdate = ask (default, y/N prompt), always (silent install) or never (notice only). Runs through npx/pnpm dlx are never auto-updated.

Telemetry

The CLI sends anonymous usage events (cli_install, cli_login, cli_doctor, cli_command with command name, version, OS, Node version and exit code) to POST /api/v1/events, fire-and-forget with a 1.5 s timeout — never keys, vehicles, file names or output. A one-line disclosure is printed on first run. Disable with car-image telemetry off or CAR_IMAGE_TELEMETRY=0.

Uninstall

npm uninstall -g @meterapp/car-image        # or pnpm remove -g / bun remove -g
rm -rf ~/.config/car-image-api              # stored key + update cache

Revoke keys any time at https://carimage.dev/dashboard?ref=npm-cli#keys.

License

MIT © Meter

Request attribution

The CLI identifies requests with X-CarImage-Integration: cli (or mcp-stdio when running its MCP bridge). Set CAR_IMAGE_HOST to claude, claude-code, chatgpt, codex, or cursor to declare the calling host. This is usage analytics, not authentication; no prompts or conversation text are sent.