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

# API Wallet & Pricing

> Pay-as-you-go pricing. Add funds and pay only for what you use.

## Pricing

**Start free, pay-as-you-go.** New accounts begin with free credits — no card
required. When you need more, top up and pay only for what you use: **\$1 =
7,500 credits, and credits never expire.**

All API prices below are per minute of audio processed (input duration unless
noted).

| Service                          | Rate       | \$10 Gets You |
| -------------------------------- | ---------- | ------------- |
| **Stem Separation**              | \$0.10/min | 100 min       |
| **Transcription**                | \$0.01/min | 1000 min      |
| **Text to Speech**               | \$0.04/min | 250 min       |
| **Voice Cloning**                | \$0.04/min | 250 min       |
| **Voice Conversion**             | \$0.13/min | 77 min        |
| **Speech Translation (Dubbing)** | \$0.40/min | 25 min        |
| **Speaker Separation**           | \$0.20/min | 50 min        |
| **Music Generation**             | \$0.04/min | 250 min       |
| **Audiobook Narration**          | \$0.04/min | 250 min       |
| **Media Conversion**             | \$0.01/min | 1000 min      |

<Info>
  Minimum top-up: **$1.00**. Maximum: **$10,000**.
</Info>

<Note>
  **Premium variants and modes.** Some services charge a multiplier on the base
  rate:

  * **Music Generation — AudioMusic Premium** (`quality="premium"`): **2×** the
    base rate (\$0.08/min).
  * **Stem Separation — premium catalog selections**: separations that run on
    the premium engine bill at **1.5×** ($0.15/min), and single-instrument
    isolation from the 45-instrument catalog at **2×** ($0.20/min).

  Every standard mode — `single`, `two`, `four`, `six`, `producer`, `studio`,
  `mastering` — bills at the base \$0.10/min.
</Note>

<Note>
  **TTS billing model.** API wallet bills TTS by the **duration of the generated
  audio**, not by character count. The per-character rate shown elsewhere in the
  docs applies to account-credit billing (subscription plans), not to API-wallet
  billing.
</Note>

<Note>
  **Noise Reduction** is currently billed from your **account credit balance**
  (subscription plan credits), not from the API wallet. To use noise reduction
  programmatically, sign in to your account and obtain a session — the API-key

  * wallet path for denoising is not yet enabled.
</Note>

***

## Check Balance

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -s "https://api.audiopod.ai/api/v1/api-wallet/balance" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" | jq .
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from audiopod import AudioPod

    client = AudioPod()
    balance = client.wallet.get_balance()

    print(f"Balance: {balance['balance_usd']}")
    print(f"Spent: {balance['total_spent_usd']}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import AudioPod from 'audiopod';

    const client = new AudioPod();
    const balance = await client.wallet.getBalance();

    console.log(`Balance: ${balance.balance_usd}`);
    console.log(`Spent: ${balance.total_spent_usd}`);
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "balance_cents": 2500,
  "balance_usd": "$25.00",
  "total_spent_cents": 1500,
  "total_spent_usd": "$15.00",
  "low_balance_warning": false
}
```

***

## Add Funds

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # Get Stripe payment link ($25)
    curl -X POST "https://api.audiopod.ai/api/v1/api-wallet/topup/checkout" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"amount_cents": 2500}'
    ```

    Open the returned `url` in your browser to complete payment.
  </Tab>

  <Tab title="App">
    1. Go to [API Keys](https://www.audiopod.ai/dashboard/account/api-keys)
    2. Click **Add Funds**
    3. Choose amount and complete Stripe checkout
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "url": "https://checkout.stripe.com/c/pay/...",
  "amount_usd": "$25.00"
}
```

***

## Automatic Top-Up

Automatic top-up keeps long-running and unattended integrations from stalling
on an empty wallet. Once it is on, we watch your balance as calls come in — the
moment it would drop below your **threshold**, we charge a saved card for your
chosen **amount** and credit the wallet.

The wallet stays prepaid: funds are added *before* they are spent. Nothing is
ever billed after the fact, and every automatic charge sends you a receipt by
email.

### One-time browser step

A card can only be saved from a browser. Card details are entered on a secure
hosted form run by our payment provider — they never pass through the AudioPod
API, and they can never be sent with an API key. This is a card-industry
requirement (and the reason bank verification prompts can appear), not an
AudioPod restriction.

So arming automatic top-up is a two-part flow:

1. **Once, in a browser** — save a card, either from
   [API Keys](https://www.audiopod.ai/dashboard/account/api-keys) →
   **Automatic top-up** → **Add card**, or by calling
   `POST /auto-topup/payment-method-session` from a signed-in session and
   opening the returned `url`.
2. **From then on, over the API** — read the configuration, tighten the limits,
   or switch it off with a plain API key.

<Warning>
  **API keys have deliberately limited power here.** With an API key you can
  read the configuration, **lower** any limit, and **disable** automatic top-up.
  Turning it **on**, **raising** a limit, or saving a card requires a signed-in
  dashboard session and returns `403` with
  `detail.error = "dashboard_required"` otherwise. A leaked key can therefore
  never arm or widen a charge against your card — only shrink or stop one.
</Warning>

### Read the configuration

```bash theme={null}
curl -s "https://api.audiopod.ai/api/v1/api-wallet/auto-topup" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" | jq .
```

**Response:**

```json theme={null}
{
  "enabled": true,
  "threshold_cents": 1000,
  "threshold_usd": "$10.00",
  "topup_amount_cents": 2500,
  "topup_amount_usd": "$25.00",
  "max_topups_per_day": 3,
  "monthly_cap_cents": 20000,
  "monthly_cap_usd": "$200.00",
  "has_payment_method": true,
  "card_brand": "visa",
  "card_last4": "4242",
  "day_charge_count": 1,
  "month_charged_cents": 2500,
  "last_charged_at": "2026-07-30T14:02:11Z",
  "next_attempt_at": null,
  "consecutive_failures": 0,
  "disabled_reason": null,
  "disabled_at": null,
  "limits": {
    "min_threshold_cents": 500,
    "max_threshold_cents": 50000,
    "min_amount_cents": 1000,
    "max_amount_cents": 50000,
    "max_per_day": 20,
    "min_monthly_cap_cents": 2500,
    "max_monthly_cap_cents": 500000
  }
}
```

Read your bounds from `limits` rather than hard-coding them — they are the
authoritative ranges and can change without a breaking API version.

### Update the configuration

Every field is optional; send only what you want to change.

```bash theme={null}
curl -X PUT "https://api.audiopod.ai/api/v1/api-wallet/auto-topup" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold_cents": 2000, "monthly_cap_cents": 10000}'
```

| Field                | Type    | Default         | Range                                    |
| -------------------- | ------- | --------------- | ---------------------------------------- |
| `enabled`            | boolean | `false`         | — (turning on needs a dashboard session) |
| `threshold_cents`    | integer | `1000` (\$10)   | $5 – $500                                |
| `topup_amount_cents` | integer | `2500` (\$25)   | $10 – $500                               |
| `max_topups_per_day` | integer | `3`             | 1 – 20                                   |
| `monthly_cap_cents`  | integer | `20000` (\$200) | $25 – $5,000                             |

Returns the full configuration object shown above.

<Note>
  **The automatic minimum ($10) is higher than the manual minimum ($1)** on
  purpose. Card processing has a flat component, so a \$1 automatic recharge
  spends a third of itself on fees. Larger, less frequent top-ups keep more of
  your money in the wallet.
</Note>

### Save or replace a card

Call this from a signed-in dashboard session and send the browser to the
returned `url`. The link is single-use and short-lived; `expires_at` is a Unix
timestamp.

```bash theme={null}
curl -X POST \
  "https://api.audiopod.ai/api/v1/api-wallet/auto-topup/payment-method-session" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "url": "https://<secure-card-form-url>",
  "expires_at": 1785000000
}
```

### Turn it off

`DELETE` switches automatic top-up off **and** forgets the saved card. It
returns the resulting configuration, with `enabled: false` and
`has_payment_method: false`. Your balance and manual top-up are untouched.

```bash theme={null}
curl -X DELETE "https://api.audiopod.ai/api/v1/api-wallet/auto-topup" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"
```

To pause automatic top-up but keep the card, send
`PUT {"enabled": false}` instead.

### Guardrails

Two independent ceilings bound what a runaway loop can spend. Both are enforced
server-side, and a charge that would cross either is simply not placed.

| Guardrail            | What it caps                        | Resets                            |
| -------------------- | ----------------------------------- | --------------------------------- |
| `max_topups_per_day` | Number of automatic charges         | Daily                             |
| `monthly_cap_cents`  | Total dollars charged automatically | On the 1st of each calendar month |

`day_charge_count` and `month_charged_cents` in the response tell you how much
headroom is left against each. When a ceiling is reached, automatic top-up stops
for the period but stays armed — nothing is disabled, and manual top-up still
works.

### When a charge fails

A declined charge is retried on a widening schedule, then automatic top-up
switches itself off rather than hammering your card:

1. **First failure** — retried about an hour later.
2. **Second failure** — retried about six hours after that.
3. **Third failure** — automatic top-up is switched off and we email you.

While a retry is pending, `next_attempt_at` holds the earliest time we will try
again and `consecutive_failures` counts the run. A successful charge resets both.

Some failures skip the retries and disable immediately, because a retry cannot
possibly clear them — most commonly when your bank requires you to confirm the
card in person, which is impossible for a charge placed while you are away.
When automatic top-up disables itself, `disabled_reason` and `disabled_at`
explain what happened. Save the card again (or replace it) and turn automatic
top-up back on.

<Warning>
  **Cards issued in India are not supported for automatic top-up yet.** Indian
  regulations require a separately registered mandate with its own notification
  and approval steps, which we have not built. Saving an Indian card for
  automatic top-up is refused at the point of saving. **Manual top-up is
  unaffected** — Add Funds and `POST /api-wallet/topup/checkout` work normally
  with an Indian card.
</Warning>

***

## Estimate Cost

Calculate cost before processing (no auth required):

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/api-wallet/estimate" \
  -H "Content-Type: application/json" \
  -d '{"service_type": "stem_extraction", "duration_seconds": 300}'
```

**Response:**

```json theme={null}
{
  "service_type": "stem_extraction",
  "duration_minutes": 5.0,
  "rate_per_minute": "$0.10/min",
  "cost_usd": "$0.50"
}
```

***

## Usage History

```bash theme={null}
curl -s "https://api.audiopod.ai/api/v1/api-wallet/usage?limit=10" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" | jq .
```

**Response:**

```json theme={null}
{
  "logs": [
    {
      "service_type": "stem_extraction",
      "duration_minutes": 5.47,
      "amount_usd": "$0.55",
      "created_at": "2025-12-11T12:39:37Z"
    }
  ]
}
```

***

## Get Pricing (No Auth)

```bash theme={null}
curl -s "https://api.audiopod.ai/api/v1/api-wallet/pricing" | jq .services
```

***

## Error Handling

| Code  | Error                      | Meaning                                                                                                              |
| ----- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `402` | `insufficient_api_balance` | Wallet is empty                                                                                                      |
| `400` | `invalid_amount`           | Amount outside $1-$10,000 range                                                                                      |
| `401` | `unauthorized`             | Invalid API key                                                                                                      |
| `403` | `dashboard_required`       | Automatic top-up: this change (turning it on, raising a limit, or saving a card) needs a signed-in dashboard session |

**Example 402 response:**

```json theme={null}
{
  "error": "insufficient_api_balance",
  "message": "Insufficient balance. Required: $0.50, Available: $0.00",
  "required_cents": 50,
  "available_cents": 0
}
```

***

## Next Steps

<Columns cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Make your first API call
  </Card>

  <Card title="Stem Separation" icon="music" href="/api-reference/stem-splitter">
    Most popular API
  </Card>
</Columns>