Guide updated
Implemented against current official v3 documentation; real-account verification is pending. Please validate key creation, permissions, wallet scope, amounts and these instructions. Automated checks and deployment are not live reconciliation.
- Required credentials
- HeyGen API key
- Monitoring currency
- USD · US dollars
- What is monitored
- API prepaid wallet balance · USD
- Fixed GET https://api.heygen.com/v3/users/me requires billing_type=wallet and wallet.currency=usd, then reads wallet.remaining_balance directly (scope=account). remaining_balance=42.5 means $42.5. Do not divide by 60 or 100 or subtract spend again.
How can I check HeyGen balance without sharing a key?
- Sign in to the official API platform and verify the paying account/workspace.
- Read the USD prepaid balance in its billing area. Web subscription Credits, Enterprise credits and metered spending caps are different amounts.
- Record the unit and time. Manual checking requires no key sharing with Quota Monitor or anyone else; funding remains the account owner's decision.
Connect HeyGen to Quota Monitor
Identify the API account and prepaid wallet
Open the HeyGen API platform below and sign in to the account paying for your API use. For a team, select the business workspace first. Find its billing/balance area and note the currency, amount and time.
Check: this is a USD prepaid wallet, not web subscription Credits. If you only have Enterprise credits or metered billing, use manual checking; do not change plans or pay just to test monitoring.
Create a dedicated API key
Open API keys below, confirm the same account/workspace, and use the key-creation control to create a separate monitoring key. If offered, name it Quota Monitor and set an appropriate expiration.
Check: this is a new key, not a replacement for a production application's key. If creation is unavailable, ask your account administrator; do not copy a login Cookie.
Grant only account:read
In the key's permission settings, choose custom permissions, enable only account:read and save. This scope covers GET /v3/users/me. Do not enable generation, write scopes or full access *:*. Labels may change; verify the saved scope.
Check: account:read is narrower than *:read, which covers all read endpoints. There is no documented IAM policy to paste for this setup, so we do not invent policy JSON. If custom permissions are unavailable, check manually and contact HeyGen support.
Store and copy the secret safely
Save the new key in a password manager. Copy only the secret value, without X-Api-Key:, Bearer, quotes, whitespace or masked characters. Review the saved permissions; if necessary, your own secure tooling can inspect GET /v3/api_keys/self for scope_mode=custom and scopes.
Check: the key is not in chat, screenshots, tickets, URLs or MCP arguments. Quota Monitor does not call the key-inspection endpoint. Protect account:read keys too: their read access includes personal profile fields.
Add HeyGen inside your Quota Monitor project
Open the target project, add a provider connection and select HeyGen (USD prepaid wallet). Enter a recognizable name, paste the key into the masked input and save. For MCP, follow the secure setup link instead of sending the key to your agent.
Check: the connection belongs to the intended project and uses USD. Do not enter a custom API URL, upstream project ID or key ID. Reusing this connection elsewhere does not create separate funds.
Wait for the first successful sync
Wait for automatic synchronization or request one refresh. A successful query shows the API wallet balance with an updated time. Respect any refresh cooldown instead of repeatedly clicking.
Check both status and time: failed reads may retain an older amount. Null, missing data, permission errors and unsupported billing types do not become zero-dollar balances.
Reconcile the same account and unit
Return to the same API platform account and compare the USD prepaid balance. For example, remaining_balance=42.5 must show $42.5, not legacy quota seconds. Do not divide by 60 or compare a spending cap or auto_reload threshold.
Check: REST/MCP heygenBalance.balance matches the card, with billingType=wallet and scope=account. Note both observation times. If usage is in flight, recheck later rather than estimating a correction.
Manage funding, rotation and live acceptance
Use the card's provider button when funds run low. Confirm the account before an authorized person decides whether to add funds. We never top up or change auto-reload. To rotate, create another account:read key, update the connection securely, verify a successful sync, then revoke only the old monitoring key.
Check: unlinking a project or deleting a connection does not revoke the provider key. Test the setup and amount with your own account. Share only sanitized error codes, times and differences, never keys, profile data or full responses.
What Quota Monitor reads from HeyGen
- Only the API key's USD prepaid wallet is supported. Enterprise currency=credits, OAuth subscription pools and usage_based billing are excluded; none is converted into dollar funds.
- The key selects the upstream account/workspace context. No additional organization, project or key filter is accepted. Several Quota Monitor projects can reference the same wallet; never sum duplicate balances.
- Only the exact balance and billing type are retained. Username, email, names and auto-reload settings are discarded. REST/MCP heygenBalance.balance uses the same amount as the card.
- One uncached GET, no redirects. No generation, key management, payments or auto_reload changes. An auto-reload threshold is not available funds.
- A null or missing balance is unknown, not zero. Failed reads retain the previous amount and timestamp. Zero and negative values remain unchanged. Query time is not a settlement guarantee and positive funds do not guarantee a model request can run.
- The dashboard shows the latest successful snapshot. Manual refresh queries the provider again but cannot eliminate upstream billing delays. An old balance is not a new result after a failed query.
HeyGen FAQ and troubleshooting
- 401: rejected key?
- Confirm it was created at platform.heygen.com/api-keys, is complete and has not expired or been revoked. Remove X-Api-Key:, Bearer and whitespace. Do not use OAuth or a browser session token.
- 403: insufficient_api_key_scope?
- Confirm account:read was saved for this key in the same account. You do not need generation or administrator rights to troubleshoot. If permissions cannot be configured, contact HeyGen support or check manually.
- Unsupported billing type or currency?
- This integration requires billing_type=wallet and currency=usd. Enterprise currency=credits, subscription and usage_based are not dollar wallets. Check them manually; changing plans or disabling protection is unnecessary.
- Null, missing balance or invalid_response?
- Null is unknown, not zero. The last successful snapshot stays intact, with no legacy quota fallback. Record the sanitized error and time, review the official wallet state and retry later. Do not send a full account response.
- 404, 429 or a timeout?
- 404 may indicate an endpoint availability change; wait out 429 throttling and retry timeouts later. Do not use mirror URLs, Cookies or broader permissions. Check whether the displayed time belongs to an older successful query.
- Duplicate balances or different web Credits?
- Several projects may reference one upstream account, so do not add their balances. API dollars differ from web subscriptions, Enterprise credits, auto-reload thresholds and metered spending caps. Compare the same account near the same time.
Official HeyGen references
- Official reference · developers.heygen.com/reference/get-current-user(opens in a new tab)
- Official reference · developers.heygen.com/user-profile(opens in a new tab)
- Official reference · developers.heygen.com/docs/api-key(opens in a new tab)
- Official reference · developers.heygen.com/docs/api-key-permissions(opens in a new tab)
- Official reference · developers.heygen.com/reference/get-current-api-key(opens in a new tab)
Prepared by Quota Monitor, not an official provider tutorial. Interfaces and permissions may change; check official pages. Verification is limited to the scope stated here.