> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing & Credits: How API Billing Works

> How BudgetPixel API usage is billed in credits — per-model pricing, charge-only-on-success, cost estimates, spend limits and alerts, and your balance.

API usage is metered in **credits**, drawn from your BudgetPixel account balance.

## You pay only for success

Credits are charged when a job reaches `succeeded`. You are **not** charged for:

* jobs that `fail` or `timeout`,
* the time a job spends queued or processing,
* requests rejected before generation (e.g. invalid input, content policy).

## Per-model pricing

Each model has a published price, returned by [`GET /v1/models`](/concepts/models):

* **Images** are priced per **output image** (`credits_per_generation`). Most requests
  return one image and cost that price. A request that returns several — see
  [multiple images per request](/concepts/models#multiple-images-per-request) — is charged
  **per image**, so a 3-image result costs `3 × credits_per_generation`.
* **Video** is priced per second (`credits_per_unit` with `unit_type: second`), so
  total cost scales with `length_seconds`. Some models (e.g. SeeDance 2.0) charge a
  **different per-second rate per resolution** — `GET /v1/models` returns a
  `resolution_pricing` map, and the cost is `that rate × length_seconds`.
* **Music** is a flat price per track (`credits_per_generation`) whatever its length —
  Music 3.0 / 2.6 = 200, Lyria 3 = 100, Mureka V9 = 60 credits — except the two per-second
  Sonilo models:
  * **Sonilo Music** (`sonilo-music`) makes instrumental/background music of an exact
    length and bills per second of the requested `duration`: `credits_per_unit` = **4**
    with a **10-second minimum** — 10 s = 40, 30 s = 120, 60 s = 240, 180 s = 720 credits.
  * **Sonilo Video Music** (`sonilo-video-music`) composes a soundtrack for an input video
    and bills the video's **measured** length, rounded up to whole seconds, at
    **15 credits/s** with a **10-second minimum** — a 30 s clip is 450 credits, a 60 s clip
    is 900. `POST /v1/cost` returns the per-second rate for this model (the duration is
    only known once the video is analyzed at submit time).
* **Sound effects** are priced per second (`credits_per_unit` with `unit_type: second`)
  with a **3-second minimum** (`min_billable_seconds`):
  * `sonilo-sfx` (text) bills the requested `duration` at **5 credits/s** —
    `5 × max(3, duration)`: 3 s = 15, 5 s = 25, 10 s = 50, 30 s = 150, 180 s = 900 credits.
  * `sonilo-video-sfx` (video) bills the input video's **measured** length, rounded up
    to whole seconds, at **15 credits/s** — a 4.2 s clip is 5 s = 75 credits, a 60 s clip
    is 900. `POST /v1/cost` returns the per-second rate for this model (the duration is
    only known once the video is analyzed at submit time).

Some image models have parameter-dependent pricing on top of the per-image rule:

* **flux-2-pro** prices by output size: `0.5MP` = 15, `1MP` = 25 (default), `2MP` = 50,
  `4MP` = 80 credits per image.

* **grok-imagine-image-2** prices by **`quality` × `size`** — both parameters move the
  price together:

  | | `size: "1K"` | `size: "2K"` |
  | - | - | - |
  | `quality: "low"` (default) | **50** | **80** |
  | `quality: "medium"` | **80** | **100** |

  Omitting either parameter uses the cheapest cell (`low` / `1K` = 50 credits). This model
  has no `high` quality tier, and the optional input `image` is **free** — editing costs the
  same as generating. Example: `{"size": "2K", "quality": "medium"}` costs 100 credits.

* **seedream-5.0-pro** prices by output size **and input images**: `1K` = 55 (default) or
  `2K` = 110 credits per image, plus **5 credits per `reference_images` item after the
  first** (the first input image is free). The input fee applies per generated image —
  each output is its own generation call carrying its own inputs. Example: a `2K` request
  with 3 reference images and `num_images: 1` costs `110 + 2 × 5 = 120` credits.

* **seedream-5.0-flash** is a flat **25 credits per image** at `1K` and `2K`, and its
  `reference_images` (up to 10) are **free** — a `2K` edit with 10 references still costs 25.

* **flux-3-image** prices by output `size`: `768px` = 55, `1K` = 65 (default), `1.5K` = 90,
  `2K` = 130 and `4K` = 790 credits per image, the same for text-to-image and editing. Its
  `reference_images` (up to 10) and `grounding` are **free**. Example: a `2K` edit with 10
  references and `num_images: 2` costs `2 × 130 = 260` credits.

* **nano-banana-2.1** prices by output `size`: `1K` = 45 (default), `2K` = 70 and `4K` = 150
  credits per image, the same for text-to-image and editing. Its `reference_images` (up to 9)
  are **free**. Search grounding is off by default and adds **per image**: `google_search` =
  10 credits, `image_search` = 20 credits. Image search runs a web search too, so the two
  never add up: with `image_search: true` the extra is 20 whether or not `google_search` is
  set. Example: a `2K` request with `image_search: true` and `num_images: 2` costs
  `2 × (70 + 20) = 180` credits.

* **minimax-h3** (video) prices per second of **output** (160 credits/sec at 2K) **plus
  per second of reference-video input**: each `reference_videos` clip is measured and
  billed at 160 credits per second of input (rounded up on the combined total).
  `reference_images` (up to 5) and `reference_audios` are free. Example: a 5-second
  generation guided by a 8.2s reference clip costs `5 × 160 + 9 × 160 = 2240` credits.

* **minimax-h3-max** (video) prices per second of **output** by resolution (480p = 65,
  768p = 105, 1080p = 210, 2k = 420 credits/sec — 2k on extension only) **plus 170 credits
  per second of video input**: every `reference_videos` clip, or the source `video` of an
  extension (billed on its first 15 seconds), rounded up on the combined total. The first
  two `reference_images` are free and each further one adds 50 credits; `reference_audios`
  and the `audio` soundtrack are free. Example: extending a 10.2s clip by 5 seconds at 768p
  costs `5 × 105 + 11 × 170 = 2395` credits.

* **seedance-2.5** (video) prices per second of **output** by resolution (480p = 150,
  720p = 330, 1080p = 750 credits/sec) **plus per second of reference-video input at half
  the output rate** (480p = 80, 720p = 160, 1080p = 375 credits per input second, rounded
  up on the combined total). `reference_images` (up to 15) and `reference_audios` are
  free. Example: a
  5-second 720p generation guided by a 8.2s reference clip costs
  `5 × 330 + 9 × 160 = 3090` credits.

* **seedance-2.0 / seedance-2.0-fast / seedance-2.0-mini** (video) price video-edit
  the same way: when a `video` input is supplied (2–15s), its measured duration is
  billed **at half the model's output per-second rate for that resolution** on top of
  the output (rounded up). Example: a 5-second 480p `seedance-2.0-mini` edit of a 4s
  clip costs `5 × 60 + 4 × 30 = 420` credits. Text/image/reference-image requests are
  unaffected — output seconds only.

* **wan-2.7-video** prices per second of **output** by resolution (720p = 100,
  1080p = 150 credits/sec). When a `video` input is supplied the request becomes a
  video edit, which bills the input clip's measured duration **at the same full
  per-second rate** on top of the output — there is no half-rate discount here.
  Video edit also takes its **output length from the input clip** (`length_seconds`
  is ignored), so a clip is billed twice over: once as input, once as output.
  Example: editing an 8.2s clip at 720p costs `9 × 100 + 9 × 100 = 1800` credits.
  `reference_images` (up to 4, video edit only) are free. Text-to-video and
  image-to-video requests are unaffected — output seconds only.

* **wan-3.0-video** prices per second of **output only**, by resolution (480p = 60,
  720p = 120, 1080p = 240 credits/sec; the high-speed **wan-3.0-video-prime** tier is
  85 / 170 / 340). **All input media is free** — reference images,
  reference video clips, and reference audio never add to the charge (the only constraint
  is that input video duration + `length_seconds` can't exceed 30 seconds). Example: a
  5-second 720p edit guided by an 8.2s reference clip costs `5 × 120 = 600` credits.

* **Video upscaling** (`POST /v1/video-upscales/topazlabs-video-upscale`) is priced
  **per second of the input video** (measured server-side, rounded up; input up to 20s)
  by target tier: 1080p = 15 (30fps) / 30 (60fps), 4K = 60 / 120 credits per second.

* **Upscalers** (`POST /v1/upscales/{model}`) are priced per image:
  **p-image-upscale** by its `target` resolution tier — 4 MP = 10, 8 MP = 15,
  16 MP = 30, 32 MP = 60 credits (input media never adds to the charge) — and
  **clarity-upscaler** at a flat 30 credits.

[`POST /v1/cost`](#estimating-cost-up-front) resolves all of this — send the exact body
you plan to generate with.

<Note>
  Your plan's perks follow you to the API. **Model discounts and active promotions**
  apply to API charges exactly as they do on the web (`POST /v1/cost` quotes your
  discounted price), and the Pro/Ultra **daily free-models allowance** — a shared pool
  of free generations per day (Pro 100, Ultra 300) across qualified image models like
  `flux-2-klein` and `qwen-image` — covers API requests too. Once the day's
  pool is used, those models charge their standard price until the reset (midnight UTC).
  Other promotional free daily generations remain web/app-only.
</Note>

## Utility pricing (conversions & posts)

These endpoints aren't models, so they don't appear in `GET /v1/models` — their
pricing is flat and stated here and on each endpoint's reference page:

| Endpoint | Credits |
| - | - |
| [`POST /v1/convert/image`](/api-reference/conversions/convert-an-image) | **2** |
| [`POST /v1/convert/video`](/api-reference/conversions/convert-a-video) | **10** |
| [`POST /v1/convert/audio`](/api-reference/conversions/convert-an-audio-file) | **3** |
| [`POST /v1/posts`](/api-reference/social/publish-a-post) | **10** |

Charged on success only, like generation. `POST /v1/cost` also resolves them — send
`{ "model": "convert-image" }` (or `convert-video` / `convert-audio` / `create-post`).
A post that is later hidden by content review is **not** refunded — it was published.

## Estimating cost up front

To know what a request will cost **before** running it, POST the same body to `/v1/cost`
with `model` added:

```bash theme={null}
curl -X POST https://api.budgetpixel.com/v1/cost \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.0", "resolution": "1080p", "length_seconds": 5 }'
```

```json theme={null}
{ "model": "seedance-2.0", "type": "video", "credits": 2750, "exact": true }
```

It's computed by the same logic that bills you, so it never disagrees with the charge.
`exact` is `true` for deterministic pricing; for seedream's sequential mode (the model decides
how many images, up to `max_images`) `credits` is the ceiling and `exact` is `false` — the real
charge is always ≤ it.

## Checking your balance

```bash theme={null}
curl https://api.budgetpixel.com/v1/account/credits \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```

```json theme={null}
{
  "total_available": 148885,
  "monthly_remaining": 126275,
  "monthly_limit": 130000,
  "monthly_used": 3725,
  "extra_credits": 22610
}
```

`total_available` is what you can spend right now (monthly remaining plus any
purchased extra credits). If a request would exceed your available balance, it's
rejected before the job is created. For a multi-image request we reserve the maximum it
could cost (`max_images × credits_per_generation`) up front, then charge only for the
images actually returned.

## Spend limits and alerts

You can put guardrails on API spend in the developer console under
[**Billing**](https://budgetpixel.com/developers?tab=billing). Both controls count
**programmatic traffic** — API keys and the [MCP connector](/mcp-server) — since both can
run unattended. Usage in the web app is separate and never blocked by them.

* **Monthly spend limit** — once your API usage reaches this many credits in a
  calendar month, new `/v1` requests and MCP generations are rejected until you raise
  or remove the limit, or the month rolls over. Jobs that were already accepted finish and bill
  normally, so a month can close slightly above the cap. Setting the limit to `0`
  pauses all API and MCP traffic immediately (a kill switch for a leaked key — though
  you should also revoke the key).
* **Spend alert** — an email to your account address when the month's API usage
  crosses a threshold. Purely informational, sent at most once per month; nothing
  is blocked. Set it below your limit to get warning before requests pause.

Both controls are **off by default** — credits are prepaid, so your balance
already caps exposure, and a default hard cap could interrupt production
traffic you intended to run. Thresholds are set in **whole thousands of
credits** (1k credits ≈ \$1 at pack rates), so a limit reads the same in
credits and dollars.

Requests over the limit receive HTTP `429` with:

```json theme={null}
{
  "error": {
    "code": "monthly_spend_limit_reached",
    "message": "Your monthly API spend limit has been reached (12500 of 12000 credits this month). Raise or remove the limit under Billing at budgetpixel.com/developers?tab=billing. Web usage is not affected.",
    "type": "rate_limit_error"
  }
}
```

Unlike [`rate_limited`](/concepts/rate-limits), backing off won't clear this —
don't retry on `monthly_spend_limit_reached`; raise the limit (or wait for the
new month) instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.