Assessment

Assess a short recording

Multipart upload of the recording plus its reference. Provide text, or (Mandarin only) pinyin, or both with one pinyin syllable per character. 60 requests per minute per account; assessments in progress at once per plan are listed in GET /v1/terms (limits.concurrent_requests_by_plan). A tp_test_ key returns a fixed example result (test: true), never scores audio and never spends credits.

post/v1/assess

Request

  • Base URL: https://api.toneperfect.app
  • URL: https://api.toneperfect.app/v1/assess
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key

Headers

Idempotency-Keystring required
Example:lesson-42-attempt-1

Unique per recording attempt. Retry with the same key and identical fields when the outcome is unknown; use a new key for a new attempt. Results are kept for 24 hours.

TonePerfect-Response'compact'

Request the versioned toneperfect.compact.v1 shape; default engine-oriented shape remains available.

TonePerfect-Test-Outcome'success' | 'unassessable' | 'invalid_assessment' | 'engine_unavailable' | 'subscription_required' | 'insufficient_credits' | 'account_busy' | 'rate_limit'

Test keys (tp_test_…) only: the outcome the fixed example response rehearses. Ignored by live keys.

Response

Assessment completed. Check assessable: when it is false the recording could not be assessed (reason says why) and nothing was charged.

OR

Example response

{
  "language": "zh",
  "locale": "zh-CN",
  "words": [
    {
      "decision": "no_correction",
      "phones": [
        {
          "dimension": "tone",
          "decision": "no_correction"
        }
      ]
    }
  ],
  "syllables": [
    {
      "components": {
        "initial": {
          "decision": "no_correction"
        },
        "final": {
          "decision": "no_correction"
        },
        "tone": {
          "decision": "no_correction"
        }
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.