1

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
Monitor your balance regularly to avoid unexpected charges and ensure you stay within your plan limits.
2

Using the SDK

The Node.js SDK provides a simple way to check your balance:
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();
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.
3

REST API

You can check your balance using the REST API directly. Here are examples in different languages:
curl -X GET https://api.suonora.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
​
success
boolean
required
Indicates if the request was successful
​
balance
object
required
Contains the balance information

​
Example Response

{
  "success": true,
  "balance": {
    "total_credits": 300000,
    "used_credits": 320000,
    "remaining_credits": -20000,
    "overage_characters": 20000,
    "overage_amount_usd": 1.00
  }
}
For Python, Java, or other languages, you can use the REST API directly with your preferred HTTP client library.

​
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
For production applications, consider implementing automated balance checks and notifications to help users manage their usage effectively.