toneperfect library

Client for the TonePerfect pronunciation assessment API (https://api.toneperfect.app).

Wraps the two public endpoints:

  • GET /v1/capabilities — languages served, limits, model version (no key needed)
  • POST /v1/assess — score one scripted recording against its reference text

Accounts, API keys and billing live in the web dashboard (https://api.toneperfect.app/dashboard) and are not wrapped. Keep the API key on your server: mobile and browser apps should call your own backend, which calls this API.

Classes

Assessment
One POST /v1/assess result. data is the full JSON body, untouched.
TonePerfect
Client for https://api.toneperfect.app.

Constants

defaultBaseUrl → const String
Production API origin. Requests pass a proxy with a 26-second timeout.
newKeyCodes → const Set<String>
Error codes that mean the key is spent: start a new attempt with a new key.
retrySameKeyCodes → const Set<String>
Error codes after which the SAME Idempotency-Key must be retried: nothing was finalized.
tasks → const List<String>
Accepted values of the task field.
toneperfectVersion → const String
Package version, sent in the User-Agent header.

Functions

newIdempotencyKey([String prefix = 'tp']) → String
A fresh Idempotency-Key for one recording attempt.

Exceptions / Errors

APIConnectionError
Transport failure (status 0): timeout or network_error. The outcome is unknown: retry with the same Idempotency-Key.
AuthenticationError
401: missing, revoked or unknown API key (invalid_api_key).
PaymentRequiredError
402: nothing was charged. code is subscription_required (the 50 free credits are used up and there is no active plan), insufficient_credits or payment_balance_due. Fix it in https://api.toneperfect.app/dashboard.
RateLimitError
429: rate_limit (60 assessments/minute) or account_busy (2 running). Retry with the same key.
ServerError
5xx: engine_unavailable, request_interrupted or a proxy 502/504.
TonePerfectError
Any non-2xx response, or a transport failure (status 0).
ValidationError
Other 4xx: the request needs a fix (invalid_audio, unsupported_language, invalid_reference, upload_too_large, idempotency_conflict, ...).