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

# Billing & limits

> Know the price before creating. Control spending and resume work safely.

MCP uses your **Developer Balance**, shared with the REST API and separate from consumer subscription credits. Connecting, browsing models, checking your balance and estimating costs are free.

## Free credits

* Eligible accounts can claim a **\$0.50 starter balance** after phone verification in the developer portal.
* Eligible paid NinjaChat subscribers receive **\$1 of agent credit per calendar month**. Check your balance to claim the available allowance.

Signing up or creating an API key alone does not guarantee a funded balance. Check your eligibility and balance in [Developers](https://www.ninjachat.ai/developers/agents).

## Get a quote

Ask your agent to use `search_models` for current prices, then `estimate_cost` for the exact request. Include the model, quantity, video duration or literal speech script. Wait for approval before generation.

| Media             | How pricing works                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Images and edits  | Per output; multiply by the requested count.                                                                             |
| Video             | Depends on model and supported duration. The default request is 8 seconds; a starting price may describe a shorter clip. |
| Voiceovers        | `tts-1`: \$0.015 / 1,000 characters; `tts-1-hd`: \$0.030 / 1,000 characters.                                             |
| Model comparisons | Each included model is billed within the total comparison budget.                                                        |

Speech charges round up to \$0.0001, with that minimum. Voice, output format and speed do not change its character-based price. The result's `cost.charged_cents` reports the actual charge.

## Set your limits

| Control                     | Where to set it                                                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| Account monthly MCP limit   | [Developers → Billing](https://www.ninjachat.ai/developers/billing).                                      |
| API-key monthly budget      | [Developers → Keys](https://www.ninjachat.ai/developers/keys); shared across that key's REST and MCP use. |
| Image/video request ceiling | `max_spend_cents`: integer 1–2000.                                                                        |
| Voiceover request ceiling   | `max_spend_cents`: greater than 0, up to 100; fractional cents accepted.                                  |
| Model comparison budget     | `total_budget_cents`: integer 5–100.                                                                      |

Prompt approval guides your agent; saved spending limits and tool ceilings enforce the budget. A quote does not reserve funds, so generation rechecks available balance and limits.

## Add credits

Fund your balance in [Billing](https://www.ninjachat.ai/developers/billing), or ask your agent for a checkout link with `add_credits`. It supports **\$25, \$100 or \$250** packs. You complete the payment yourself.

An **8% service fee** is added when buying credits: \$25 in credit costs \$27. Buying credits does not enable auto-reload; that is a separate setting in Billing.

## Retries and refunds

Use the same `idempotency_key` and unchanged arguments when retrying an uncertain generation response. Within the one-hour replay window, a completed request returns its stored result without a second charge. Use a new key for new content. Speech requires this key; other generation tools support it.

For video, retain the job ID and poll `get_generation_status`. A failed generation is refunded; async video refunds may complete after submission. In a partially successful comparison, successful outputs remain billed.

| Error                                          | Next step                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------- |
| `insufficient_credits`                         | Add funds after approval, then retry.                                     |
| `spend_limit_exceeded` / `key_budget_exceeded` | Review the relevant limit; retrying alone will not raise it.              |
| `budget_too_low`                               | Choose a cheaper request or approve a higher ceiling.                     |
| `generation_pending`                           | Wait and resume the same request or video job.                            |
| `idempotency_conflict`                         | The key was used for different inputs; use a new key for the new request. |
| `generation_failed_refunded`                   | The failed attempt was refunded. You may retry.                           |
| `generation_failed_refund_pending`             | The refund is recorded and will be retried automatically.                 |
| `generation_failed_refund_unrecorded`          | Contact support before retrying.                                          |

## Rate limits

Limits are counted per API key, or per client and user for OAuth.

| Tool class                         | Requests per minute |
| ---------------------------------- | ------------------- |
| Reads, estimates and status checks | 60                  |
| Images                             | 10                  |
| Voiceovers                         | 10                  |
| Uploads                            | 10                  |
| Video                              | 3                   |
| Model comparisons                  | 2                   |
| Scroll-video preparation           | 3                   |
| Page publishing                    | 6                   |

`add_credits` allows 6 requests per 10 minutes. For `rate_limited`, wait for the returned `retry_after_seconds` before retrying.