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

# Account Balance

> Check your text-to-speech usage balance, remaining credits, and estimated overage charges.

<Steps title="Checking Your Balance">
  <Step title="Overview">
    The balance endpoint provides real-time information about your text-to-speech usage, including:

    * Total included characters in your plan
    * Characters used this month
    * Remaining characters
    * Overage usage and estimated charges

    <Note>
      Monitor your balance regularly to avoid unexpected charges and ensure you stay within your plan limits.
    </Note>
  </Step>

  <Step title="Using the SDK">
    The Node.js SDK provides a simple way to check your balance:

    ```js
    const Suonora = require('suonora-sdk');

    const suonora = new Suonora({
      apiKey: 'YOUR_API_KEY'
    });

    async function getAccountBalance() {
      try {
        const balance = await suonora.getBalance();

        console.log('--- Suonora Account Balance ---');
        console.log(`Total Characters: ${balance.total_credits}`);
        console.log(`Used Characters: ${balance.used_credits}`);
        console.log(`Remaining Characters: ${balance.remaining_credits}`);

        if (balance.overage_characters > 0) {
          console.log(`Overage: ${balance.overage_characters} characters, estimated $${balance.overage_amount_usd.toFixed(2)}`);
        }
      } catch (error) {
        console.error('Error getting balance:', error.message);
      }
    }

    getAccountBalance();
    ```

    <Note type="info">
      The SDK handles authentication and error handling automatically. It's the recommended way to interact with the Suonora API if you're using Node.js.
    </Note>
  </Step>

  <Step title="REST API">
    You can check your balance using the REST API directly. Here are examples in different languages:

    <Tabs>
      <Tab title="curl">
        ```bash
        curl -X GET https://api.suonora.com/v1/balance \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab title="Python">
        ```python
        import requests

        url = "https://api.suonora.com/v1/balance"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY"
        }

        try:
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            balance = response.json()

            print("--- Suonora Account Balance ---")
            print(f"Total Characters: {balance['balance']['total_credits']}")
            print(f"Used Characters: {balance['balance']['used_credits']}")
            print(f"Remaining Characters: {balance['balance']['remaining_credits']}")

            if balance['balance']['overage_characters'] > 0:
                print(f"Overage: {balance['balance']['overage_characters']} characters, "
                      f"estimated ${balance['balance']['overage_amount_usd']:.2f}")

        except requests.exceptions.RequestException as error:
            print(f"Error getting balance: {error}")
        ```
      </Tab>

      <Tab title="Java">
        ```java
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;
        import java.net.URI;
        import org.json.JSONObject;

        public class BalanceChecker {
            public static void main(String[] args) {
                HttpClient client = HttpClient.newHttpClient();
                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://api.suonora.com/v1/balance"))
                    .header("Authorization", "Bearer YOUR_API_KEY")
                    .GET()
                    .build();

                try {
                    HttpResponse<String> response = client.send(request,
                        HttpResponse.BodyHandlers.ofString());

                    JSONObject json = new JSONObject(response.body());
                    JSONObject balance = json.getJSONObject("balance");

                    System.out.println("--- Suonora Account Balance ---");
                    System.out.printf("Total Characters: %d%n",
                        balance.getInt("total_credits"));
                    System.out.printf("Used Characters: %d%n",
                        balance.getInt("used_credits"));
                    System.out.printf("Remaining Characters: %d%n",
                        balance.getInt("remaining_credits"));

                    if (balance.getInt("overage_characters") > 0) {
                        System.out.printf("Overage: %d characters, estimated $%.2f%n",
                            balance.getInt("overage_characters"),
                            balance.getDouble("overage_amount_usd"));
                    }

                } catch (Exception e) {
                    System.err.printf("Error getting balance: %s%n", e.getMessage());
                }
            }
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```js
        async function getAccountBalance() {
          try {
            const response = await fetch('https://api.suonora.com/v1/balance', {
              headers: {
                'Authorization': 'Bearer YOUR_API_KEY'
              }
            });

            if (!response.ok) {
              throw new Error(`HTTP error! status: ${response.status}`);
            }

            const data = await response.json();
            const balance = data.balance;

            console.log('--- Suonora Account Balance ---');
            console.log(`Total Characters: ${balance.total_credits}`);
            console.log(`Used Characters: ${balance.used_credits}`);
            console.log(`Remaining Characters: ${balance.remaining_credits}`);

            if (balance.overage_characters > 0) {
              console.log(`Overage: ${balance.overage_characters} characters, ` +
                         `estimated $${balance.overage_amount_usd.toFixed(2)}`);
            }
          } catch (error) {
            console.error('Error getting balance:', error.message);
          }
        }

        getAccountBalance();
        ```
      </Tab>
    </Tabs>

    <ResponseField name="success" type="boolean" required>
      Indicates if the request was successful
    </ResponseField>

    <ResponseField name="balance" type="object" required>
      Contains the balance information

      <Expandable title="Balance Fields">
        <ResponseField name="total_credits" type="number" required>
          Total characters included in your plan for the month
        </ResponseField>

        <ResponseField name="used_credits" type="number" required>
          Total characters used this month
        </ResponseField>

        <ResponseField name="remaining_credits" type="number" required>
          Characters remaining in your plan. Can be negative if you've exceeded your limit
        </ResponseField>

        <ResponseField name="overage_characters" type="number" required>
          Number of characters over your plan limit. Will be 0 if within limits
        </ResponseField>

        <ResponseField name="overage_amount_usd" type="number" required>
          Estimated additional charge for overage, based on your plan rate
        </ResponseField>
      </Expandable>
    </ResponseField>

    ### Example Response

    ```json
    {
      "success": true,
      "balance": {
        "total_credits": 300000,
        "used_credits": 320000,
        "remaining_credits": -20000,
        "overage_characters": 20000,
        "overage_amount_usd": 1.00
      }
    }
    ```

    <Note>
      For Python, Java, or other languages, you can use the REST API directly with your preferred HTTP client library.
    </Note>
  </Step>
</Steps>

***

## Best Practices

1. **Monitor Usage**

   * Check balance regularly to track usage
   * Set up alerts when approaching limits
   * Monitor for unusual usage patterns

2. **Handle Overage**

   * Implement usage limits in your application
   * Notify users before they exceed their plan
   * Consider upgrading plans for consistent overage

3. **Error Handling**
   * Always check the `success` flag
   * Handle API errors gracefully
   * Implement retry logic for temporary failures

<Note type="tip">
  For production applications, consider implementing automated balance checks
  and notifications to help users manage their usage effectively.
</Note>

{" "}