# Car Image API for agents

## Fastest setup

From a checkout of the repository:

```bash
npm install
npm link
car-image onboard
```

The CLI uses a browser-assisted device flow. A human signs in with Google and
approves the displayed code. The API key is delivered only to the waiting CLI,
stored at `~/.config/car-image-api/config.json` with mode `0600`, and can be
revoked from the dashboard. `car-image onboard` then opens hosted Stripe
Checkout; payment still requires explicit human confirmation.

Dashboard-created keys receive `images:read` and `account:read`. A key created
through the explicitly approved CLI flow also receives `billing:write`, which
only creates hosted Stripe URLs; it cannot complete a charge by itself.

For CI or an agent sandbox, inject the credential as a secret:

```bash
export CAR_IMAGE_API_KEY=cimg_...
export CAR_IMAGE_API_URL=https://car-imgs.vercel.app
```

Do not paste a key into a prompt or commit it to an MCP config file.

## REST

Download image bytes:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://car-imgs.vercel.app/api/v1/images/car?make=porsche&model=911&year=2024&view=front-3-4&color=red&format=webp" \
  --output car.webp
```

Create up to 50 single-use embed URLs:

```bash
curl --fail-with-body \
  -X POST https://car-imgs.vercel.app/api/v1/image-urls \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"images":[{"make":"BMW","model":"M3","year":2022},{"make":"Porsche","model":"911","year":2024,"view":"side"}]}'
```

Check cost and balance before a larger operation:

```bash
curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  https://car-imgs.vercel.app/api/v1/account
```

All JSON errors use `application/problem+json` and include `status`, `detail`,
and `request_id`. Preserve the request ID when reporting a failure.

Every successful image delivery costs exactly 1 credit. If the canonical
variant is not cached yet, the service generates and caches it at the same
price. Failed rendering is refunded.

## MCP

The local stdio server exposes:

- `get_car_image` — returns image content and usage metadata
- `create_car_image_url` — returns a short-lived, single-use embed URL
- `get_car_image_account` — returns balance and pricing
- `list_vehicle_options` — discovers valid years, makes, and models

Example host configuration:

```json
{
  "mcpServers": {
    "car-images": {
      "command": "car-image",
      "args": ["mcp"],
      "env": {
        "CAR_IMAGE_API_KEY": "${CAR_IMAGE_API_KEY}",
        "CAR_IMAGE_API_URL": "https://car-imgs.vercel.app"
      }
    }
  }
}
```

For stdio MCP, credentials come from the environment. A future remote MCP
endpoint should use OAuth 2.1, Protected Resource Metadata, audience-bound
tokens, and PKCE rather than forwarding API keys through an agent host.

## Safety behavior

- Do not retry a 402 automatically. Ask the human to approve a credit purchase.
- Respect 429 `Retry-After`.
- A single-use URL returns 410 after redemption; request a new URL.
- A 502 does not consume credits, but the delivery URL is consumed. Mint a new
  URL before retrying.
- Never claim images are exact OEM photography. They are generated, catalog-
  bounded product visuals and can contain visual inaccuracies.