Docs

Prosody scores pronunciation from audio and known reference text, then exposes the result history needed for practice products.

Quickstart

Try the playground or call the API with an API key. 

curl -X POST "https://api.prosody.studio/v1/scores?session_id=lesson-001" \
  -H "X-API-Key: $PROSODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_data": "<base64 audio>",
    "sample_rate": 16000,
    "language": "en-US",
    "reference_text": "The quick brown fox"
  }'

Authentication

Send your key in the X-API-Key header. The playground has a small no-key trial for evaluation.

POST /v1/scores

Score one recording against one reference text. Add the optional session_id query parameter to group attempts into a practice timeline.

Field Required Description
audio_data Yes Base64-encoded audio.
sample_rate Yes Audio sample rate in Hz.
language Yes Use en-US today.
reference_text Yes The text the speaker was expected to say.
session_id query No Caller-defined practice/session grouping key.

Results, history, sessions, profile

The API is no longer just a one-shot scoring call. Use these authenticated endpoints to build review screens, lesson timelines, and learner dashboards.

Endpoint Use it for
POST /v1/scores Submit a single audio + reference text pair for scoring. Accepts an optional caller-defined session_id that history/results endpoints can filter on later.
POST /v1/scores/batch Submit multiple audio + reference text pairs in one request for batched scoring. Same session_id grouping semantics as single scoring.
GET /v1/scores/{result_id} Fetch a previously persisted score result by ID.
GET /v1/results Reload stored score results with filters and pagination.
GET /v1/history Show chronological practice history and aggregate summary.
GET /v1/sessions ⚠️ Preview. List practice-session rollups grouped by session_id.
POST /v1/sessions ⚠️ Preview. Create a first-class practice session before scoring starts.
GET /v1/sessions/{session_id} ⚠️ Preview. Read a single session by ID — merges lifecycle metadata with its score rollup.
PATCH /v1/sessions/{session_id} ⚠️ Preview. Close or abandon an open practice session (status: "closed" | "abandoned"). Further score writes against the same session return 409 Conflict.
GET /v1/profile ⚠️ Preview. Read profile preferences and storage-backed learning stats.
PUT /v1/profile ⚠️ Preview. Update display name, native/target languages, preferences, timezone, UI language, and app-level privacy settings. Subscription remains auth-derived.

Response

The response includes aggregate scores and per-word detail. Full responses may also include phoneme timing, insertions, warnings, and mismatch diagnostics. 

{
  "scores": {
    "pronunciation": 72.4,
    "script_adherence": 100.0,
    "overall": 72.4
  },
  "words": [
    {
      "word": "the",
      "status": "match",
      "acoustic_match": 68.1,
      "timing": { "start": 0.12, "end": 0.24, "duration_ms": 120 },
      "phonemes": [
        { "detected": "DH", "acoustic_match": 71.2 }
      ]
    }
  ]
}

TypeScript SDK

Use @prosody/sdk if you want typed requests and response validation. 

npm install @prosody/sdk

Privacy

  • Audio is processed for scoring and is not retained by the playground.
  • Scoring metadata can be retained for authenticated history and profile views.
  • Audio is not sent to third-party speech APIs.
  • Training use requires explicit consent and is separate from the trial flow.

Request an API key

Email [email protected] with what you are building and roughly how much audio you expect to score.