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.
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.
REST API
You can check your balance using the REST API directly. Here are examples in different languages: curl
Python
Java
JavaScript
curl -X GET https://api.suonora.com/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
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}")
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());
}
}
}
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();
Indicates if the request was successful
Contains the balance information
Total characters included in your plan for the month
Total characters used this month
Characters remaining in your plan. Can be negative if you’ve exceeded your limit
Number of characters over your plan limit. Will be 0 if within limits
Estimated additional charge for overage, based on your plan rate
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
-
Monitor Usage
- Check balance regularly to track usage
- Set up alerts when approaching limits
- Monitor for unusual usage patterns
-
Handle Overage
- Implement usage limits in your application
- Notify users before they exceed their plan
- Consider upgrading plans for consistent overage
-
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.
