# API credits

How the API charges, how to read your balance, and how to buy API credits.

> **Coming soon:** The Developer API opens soon. You can read the docs now; API keys arrive when it opens.

The API uses **API credits**. They are separate from the credits you use on the website and in the
MCP connector, and the two never convert into each other. Website plans include no API credits.

## What a request costs

A live request uses **1 API credit when its conversion succeeds**. `GET /v1/account` shows the
current price in `pricing.credits_per_request`, so you never need to hard-code it:

```json
"pricing": { "credits_per_request": { "single": 1 } }
```

These use no credits:

- failed and timed-out conversions;
- requests the API refuses, including `402`, `429` and `503` answers;
- status checks, `GET /v1/account` and `DELETE`;
- downloading a result again while it is available;
- repeating a request with the same `Idempotency-Key` within 24 hours;
- every call with a test key.

A request that succeeds is charged even if your client stopped waiting for it. Use an
`Idempotency-Key` so that a retry returns the same conversion instead of a new one (see
[Idempotency](/docs/api/idempotency)).

## Credit headers

| Header | Where | Meaning |
|---|---|---|
| `X-Credits-Charged` | Every response | Credits this request caused to be charged: `1` on a create that succeeded within the wait (not on a replay), `0` everywhere else. |
| `X-Credits-Remaining` | `POST /v1/vectorizations` once the key is accepted and the attempts limit passed (also on `402` and most other errors), `GET /v1/account` | Your available live API credits after this request. |
| `X-Credits-Would-Charge` | `POST /v1/vectorizations` with a test key | What a live key would have paid. |

A conversion that finishes after a `202` answer is charged when it succeeds. Its object then shows
`"credits_charged": 1`, but the `202` response said `X-Credits-Charged: 0`. The conversion object is
the record of what each request cost.

## Your balance

`GET /v1/account` returns your live API balance, also when you call it with a test key:

```json
"balance": {
  "credits": 482,
  "held": 1,
  "available": 481,
  "expiring": [{ "credits": 100, "expires_at": "2027-03-02T10:14:00Z" }]
}
```

| Field | Meaning |
|---|---|
| `credits` | Spendable API credits. |
| `held` | Credits held by your requests that are still running. |
| `available` | `max(0, credits − held)`: what a new request can use. |
| `expiring` | The next five expiry dates, with the credits that expire on each. |

There is no overdraft. If `available` is lower than the request's price, `POST /v1/vectorizations`
answers `402 insufficient_credits` before any work starts. The error carries `credits_required` and
`credits_available`.

API credits expire **12 months after purchase**. Credits we grant you are used before credits you
buy; within each kind, the credits that expire soonest are used first.

## Buy credits

Buy API credit packs in the [Developers area of your account](/account/developers). Each pack is a one-time purchase; there
is no subscription and no automatic top-up.

| Pack | API credits | Price | Per conversion |
|---|---|---|---|
| Starter | 10 | $5 | $0.50 |
| Bulk-100 | 100 | $20 | $0.20 |
| Bulk-1,000 | 1,000 | $100 | $0.10 |
| Bulk-10,000 | 10,000 | $800 | $0.08 |

Prices are in US dollars, and Lemon Squeezy may add tax at checkout. You can buy up to 10 of
any pack in one order. For more than 100,000 credits, contact contact@perfectvector.com.

- **At checkout** you tick a required box that starts your credits at once, and the first time you
  also accept the [API Terms](/docs/api/terms). The box reads: "Add my credits now. I can get a refund
  for unused credits within 14 days. Once they're all used, the purchase is final."
- **Payment** goes through Lemon Squeezy, our Merchant of Record. Your credits appear in your
  balance shortly after the payment is confirmed.
- **Receipts:** Lemon Squeezy emails you the receipt with a link to the invoice.
- **Business buyers:** enter your tax ID in the checkout; it cannot be added later. When you create
  the invoice from the receipt email, type your business name in its Name field. Both then appear on
  the invoice.
- You may withdraw from a purchase within 14 days: you pay for the credits you used, and the unused
  part is refunded. The right ends once all credits of that purchase are used
  ([API Terms §7](/docs/api/terms)).

## Low-balance banner

The Developers area shows a banner when your available API credits fall below a level. It is on by
default.

- **Automatic level:** 20% of your API balance right after your latest top-up, rounded up, and at
  least 2 credits. For example, buying a Bulk-100 pack with no other credits sets the level to 20.
- **Your own level:** set a fixed number of credits instead. It replaces the automatic level.
- You can turn the banner off in the Developers area.

There is no low-balance email. Check your balance with `GET /v1/account` or the `X-Credits-Remaining`
header to automate your top-ups.

## Account deletion

If you delete your PerfectVector account, unspent API credits are lost and are not refunded, except
where the law requires otherwise. The website warns you first.

[Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.