Langcraft Speech API

https://docs.langcraft.world/
Admin
Langcraft Speech API provides pronunciation assessment and prosody analysis with phoneme-level...
Tokens:9,738
Snippets:100
Trust Score:4.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Recording quality response object

Source: https://docs.langcraft.world/recording-quality

Example of a JSON response containing the recording_quality object with metrics and recommendations.

```json
{
  "recording_quality": {
    "version": "1",
    "status": "marginal",
    "score_action": "confirm_negative",
    "metrics": {
      "estimated_snr_db": 17.8,
      "snr_confidence": 0.91,
      "active_speech_level_dbfs": -27.1,
      "noise_floor_dbfs": -44.9,
      "clipped_fraction": 0.0,
      "duration_sec": 1.12,
      "reverberation": {
        "risk": "moderate",
        "score": 0.54,
        "confidence": 0.71,
        "estimated_rt60_ms": null
      }
    },
    "reasons": [
      "marginal_snr",
      "moderate_reverberation"
    ],
    "recommendation": {
      "code": "move_closer_and_reduce_echo",
      "retry_recommended": false
    },
    "gate_applied": false
  }
}
```

--------------------------------

### Retrieve Summary Object

Source: https://docs.langcraft.world/output

Example of the summary object containing aggregate match scores and phone counts.

```json
{
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  }
}
```

--------------------------------

### Retrieve Word Groups

Source: https://docs.langcraft.world/output

Example of the word_groups structure, including IPA sequences, insertion details, and per-word summary statistics.

```json
{
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "phones": ["..."],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ",
          "timestamp_ms": {"start": 1860.39, "end": 1920.41}
        }
      ],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "acceptable_pronunciations": ["s ɪ ɾ i z", "s ɪ t i z"],
      "selected_pronunciation": "s ɪ ɾ i z",
      "selected_pronunciation_index": 0
    }
  ]
}
```

--------------------------------

### Analyze speech with cURL

Source: https://docs.langcraft.world/early-childhood-speaker-profile

Example request using the Nova 1 model to analyze an audio file against reference text.

```bash
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@utterance.wav" \
  -F "reference_text=the red house" \
  -F "lang=en" \
  -F "model=nova-1"
```

--------------------------------

### Phone Entry JSON Structure

Source: https://docs.langcraft.world/output

Example of a phone entry object showing substitution grading and top-k alternatives.

```json
{
  "index": 15,
  "target": "s",
  "predicted": "z",
  "timestamp_ms": {"start": 1860.39, "end": 2060.44},
  "match_score_pct": 90.48,
  "grade": "substitute",
  "topk": [
    {"token": "z", "confidence_pct": 91.5},
    {"token": "s", "confidence_pct": 7.81}
  ]
}
```

--------------------------------

### Lexical Stress JSON Response Example

Source: https://docs.langcraft.world/lexical-stress

A sample JSON structure showing syllable stress scores and expected primary stress flags.

```json
{
  "text": "banana",
  "syllables": [
    {
      "index": 0,
      "text": "ba",
      "stress": {
        "score": 0.08,
        "expected": false
      }
    },
    {
      "index": 1,
      "text": "na",
      "stress": {
        "score": 0.87,
        "expected": true
      }
    },
    {
      "index": 2,
      "text": "na",
      "stress": {
        "score": 0.12,
        "expected": false
      }
    }
  ]
}
```

--------------------------------

### Speaking Rate Metrics JSON Structure

Source: https://docs.langcraft.world/output

Example of the speaking rate metrics object showing words per minute calculations and total speaking time.

```json
{
  "speech_rate_wpm": 110.3,
  "articulation_rate_wpm": 132.6,
  "rate_metrics": {
    "word_count": 22,
    "speech_rate_wpm": 110.3,
    "articulation_rate_wpm": 132.6,
    "speaking_time_sec": 9.95
  }
}
```

--------------------------------

### Prosody Contour JSON Structure

Source: https://docs.langcraft.world/output

Example of the prosody object containing frame-level pitch and stress contours.

```json
{
  "prosody": {
    "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
    "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
  }
}
```

--------------------------------

### API JSON Response Example

Source: https://docs.langcraft.world/quickstart

Represents the standard JSON object returned by the API. Use this structure to parse language, dialect, and phonetic data.

```json
{
  "language": "en",
  "dialect": "en-us",
  "reference_text": "I can do it tomorrow.",
  "reference_phones": ["aɪ", "k", "ə", "n", "d", "uː", "ɪ", "t", "t", "ə", "m", "ɑː", "ɹ", "oʊ"],
  "predicted_phones": ["aɪ", "k", "ə", "n", "d", "uː", "ɪ", "t", "t", "ə", "m", "ɑː", "ɹ", "oʊ"],
  "audio": {"duration_sec": 1.85},
  "summary": {},
  "word_groups": []
}
```

--------------------------------

### Intended Transcription Mode JSON Response

Source: https://docs.langcraft.world/transcription-modes

Example of a JSON response when using the intended transcription mode.

```json
{
  "transcription": {
    "mode": "intended",
    "event_schema_version": "1",
    "text": "I think we should go on Thursday.",
    "words": [
      {"index": 0, "text": "I", "start": 120, "end": 240, "word_group_index": 0},
      {"index": 1, "text": "think", "start": 270, "end": 610, "word_group_index": 1}
    ],
    "events": []
  }
}
```

--------------------------------

### Functional load response structure

Source: https://docs.langcraft.world/functional-load

Example of the functional load object returned within a phone analysis result.

```json
{
  "text": "ship",
  "phones": [
    {
      "index": 1,
      "target": "ɪ",
      "predicted": "iː",
      "grade": "substitute",
      "functional_load": {
        "meaning_risk": true,
        "priority_score": 82,
        "priority_category": "critical",
        "meaning_risk_score": 82,
        "meaning_risk_category": "critical",
        "contrast_category": "critical",
        "examples": ["ship/sheep"]
      }
    }
  ]
}
```

--------------------------------

### Proficiency Quality Scores JSON Structure

Source: https://docs.langcraft.world/output

Example of the proficiency metrics object containing fluency, prosody, and intelligibility scores with explanatory notes.

```json
{
  "proficiency_metrics": {
    "fluency": {
      "value": 100,
      "note": "The speaker delivers the sentence without any hesitations, fillers, or interruptions."
    },
    "prosody": {
      "value": 95,
      "note": "Natural intonation and rhythm with appropriate emphasis on key words."
    },
    "intelligibility": {
      "value": 100,
      "note": "Every word is pronounced clearly and is easy to understand."
    }
  }
}
```

--------------------------------

### Pause Metrics JSON Structure

Source: https://docs.langcraft.world/output

Example of the pause metrics object containing duration, threshold, individual pause segments, and aggregate statistics.

```json
{
  "audio_duration_sec": 12.0,
  "pause_threshold_sec": 0.25,
  "pauses": [
    {"start": 2.1, "end": 2.6, "duration_sec": 0.5},
    {"start": 5.2, "end": 5.45, "duration_sec": 0.25}
  ],
  "pause_metrics": {
    "pause_count": 2,
    "average_pause_duration_sec": 0.38,
    "total_silence_time_sec": 0.75,
    "pause_ratio": 0.06
  }
}
```

--------------------------------

### Verbatim Transcription Response Structure

Source: https://docs.langcraft.world/transcription-modes

Example JSON response for a verbatim transcription request, including word indices, surface phones, and detected events.

```json
{
  "transcription": {
    "mode": "verbatim",
    "event_schema_version": "1",
    "text": "I I think [UM] we should go on th* Thursday [laughter].",
    "words": [
      {"index": 0, "text": "I", "start": 120, "end": 240, "word_group_index": null},
      {"index": 1, "text": "I", "start": 290, "end": 420, "word_group_index": 0},
      {"index": 2, "text": "think", "start": 450, "end": 790, "word_group_index": 1, "surface_phones": [{"phone": "θ", "predicted_index": 2, "start": 460, "end": 520, "word_index": 2}]},
      {"index": 3, "text": "[UM]", "start": 920, "end": 1160, "word_group_index": null, "surface_phones": [{"phone": "ə", "predicted_index": 6, "start": 940, "end": 1120, "word_index": 3}]},
      {"index": 4, "text": "we", "start": 1220, "end": 1370, "word_group_index": 2},
      {"index": 5, "text": "should", "start": 1410, "end": 1690, "word_group_index": 3},
      {"index": 6, "text": "go", "start": 1740, "end": 1910, "word_group_index": 4},
      {"index": 7, "text": "on", "start": 1940, "end": 2050, "word_group_index": 5},
      {"index": 8, "text": "th*", "start": 2090, "end": 2180, "word_group_index": null},
      {"index": 9, "text": "Thursday", "start": 2210, "end": 2760, "word_group_index": 6},
      {"index": 10, "text": "[laughter]", "start": 2940, "end": 3380, "word_group_index": null}
    ],
    "surface_phones": [
      {"phone": "θ", "predicted_index": 2, "start": 460, "end": 520, "word_index": 2},
      {"phone": "ə", "predicted_index": 6, "start": 940, "end": 1120, "word_index": 3}
    ],
    "events": [
      {
        "type": "repetition",
        "text": "I",
        "count": 2,
        "word_indices": [0, 1],
        "start": 120,
        "end": 420
      },
      {
        "type": "filler",
        "label": "um",
        "text": "[UM]",
        "word_indices": [3],
        "start": 920,
        "end": 1160
      },
      {
        "type": "cutoff",
        "text": "th*",
        "fragment": "th",
        "word_indices": [8],
        "start": 2090,
        "end": 2180
      },
      {
        "type": "vocal_event",
        "label": "laughter",
        "text": "[laughter]",
        "word_indices": [10],
        "start": 2940,
        "end": 3380
      }
    ]
  }
}
```

--------------------------------

### POST /v1/speech/analyze

Source: https://docs.langcraft.world/early-childhood-speaker-profile

Analyzes audio for young speakers by selecting the Nova 1 model via the model or speaker_profile parameters.

```APIDOC
## POST /v1/speech/analyze

### Description
Analyzes audio input for young speakers using the Nova 1 model. Requires reference text or reference phones.

### Method
POST

### Endpoint
https://api.langcraft.world/v1/speech/analyze

### Parameters
#### Request Body
- **audio** (file) - Required - The audio file to analyze.
- **reference_text** (string) - Required - The expected text for the audio.
- **lang** (string) - Required - The language code (en, fr, de, pt, es).
- **model** (string) - Optional - Set to 'nova-1' to enable early-childhood analysis.
- **speaker_profile** (string) - Optional - Set to 'early_childhood' to enable early-childhood analysis.

### Request Example
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@utterance.wav" \
  -F "reference_text=the red house" \
  -F "lang=en" \
  -F "model=nova-1"
```

--------------------------------

### Select Early-Childhood Speech Model

Source: https://docs.langcraft.world/

Use the nova-1 model for speakers aged six months to eight years.

```text
model=nova-1

```

--------------------------------

### Supported and missing languages

Source: https://docs.langcraft.world/functional-load

Lists of language codes currently supported or missing functional load support.

```text
ar, bn, ca, cs, da, de, el, en, es, fa, fi, fr, he, hi, hr, hu,
it, ja, ko, lt, no, nl, pl, pt, ro, ru, sk, sv, ta, tr, uk, vi, zh
```

```text
sw, te, th
```

--------------------------------

### Send a speech analysis request

Source: https://docs.langcraft.world/quickstart

Perform a multipart form request to the speech analysis endpoint with required authentication and configuration parameters.

```bash
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@speech.wav" \
  -F "reference_text=I can do it tomorrow." \
  -F "lang=en" \
  -F "dialect=en-us" \
  -F "enable_prosody_contours=true" \
  -F "enable_proficiency_metrics=true"
```

```bash
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@speech.wav" \
  -F "reference_text=Ich kann das morgen machen." \
  -F "lang=de" \
  -F "model=aurora-1"
```

--------------------------------

### POST /v1/speech/analyze

Source: https://docs.langcraft.world/transcription-modes

Analyzes audio input and generates a transcript based on the specified transcription mode.

```APIDOC
## POST /v1/speech/analyze

### Description
Analyzes an audio file and returns a transcript. The `transcription_mode` parameter determines whether the output is a clean 'intended' transcript or a detailed 'verbatim' transcript.

### Method
POST

### Endpoint
https://api.langcraft.world/v1/speech/analyze

### Parameters
#### Request Body
- **audio** (file) - Required - The audio file to be transcribed.
- **lang** (string) - Required - The language code (e.g., 'en').
- **transcription_mode** (string) - Optional - The style of transcript. Supported values: 'intended' (clean, readable) or 'verbatim' (word-for-word with fillers and events). Defaults to 'intended' until August 31, 2026, then 'verbatim'.
```

--------------------------------

### Select Nova 1 model

Source: https://docs.langcraft.world/early-childhood-speaker-profile

Use these parameters to specify the Nova 1 model for speech analysis requests.

```text
model=nova-1
```

```text
speaker_profile=early_childhood
```

--------------------------------

### Functional load category levels

Source: https://docs.langcraft.world/functional-load

The available string categories for functional load metrics.

```text
none
low
medium
high
critical
```

--------------------------------

### POST /v1/speech/analyze

Source: https://docs.langcraft.world/quickstart

Analyzes an audio file to provide speech metrics, forced alignment, or transcription.

```APIDOC
## POST /v1/speech/analyze

### Description
Analyzes an audio file to provide speech metrics, forced alignment, or transcription. Supports multiple audio formats and language/dialect configurations.

### Method
POST

### Endpoint
https://api.langcraft.world/v1/speech/analyze

### Parameters
#### Request Body (Multipart Form)
- **audio** (file) - Required - Supported formats: WAV, M4A, FLAC, MP3, OGG, WEBM
- **reference_text** (string) - Optional - Reference text for forced alignment. Accepted alias: text.
- **reference_phones** (string) - Optional - Space-separated IPA phones. Accepted alias: ipa.
- **lang** (string) - Optional - Base language code.
- **dialect** (string) - Optional - Full dialect code. Default: en-us.
- **model** (string) - Optional - Model selector (e.g., aurora-1, nova-1).
- **speaker_profile** (string) - Optional - Alternative selector for Nova 1 (e.g., early_childhood).
- **match_score_mode** (string) - Optional - Scoring style (lenient or strict).
- **enable_prosody_contours** (boolean) - Optional - Include pitch and stress contours. Default: false.
- **enable_proficiency_metrics** (boolean) - Optional - Include holistic speaking scores. Default: false.

### Request Example
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@speech.wav" \
  -F "reference_text=I can do it tomorrow." \
  -F "lang=en"
```

--------------------------------

### Configure transcription mode via cURL

Source: https://docs.langcraft.world/transcription-modes

Use the transcription_mode parameter in a POST request to specify the desired output style.

```bash
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@speech.wav" \
  -F "lang=en" \
  -F "transcription_mode=verbatim"
```

--------------------------------

### Prioritize corrections in TypeScript

Source: https://docs.langcraft.world/functional-load

Logic for filtering and prioritizing feedback based on functional load risk and category.

```ts
const fl = phone.functional_load;

if (fl?.meaning_risk && ["high", "critical"].includes(fl.priority_category)) {
  // Prioritize this correction in tutor feedback.
  // Example: "This can sound like 'sheep' instead of 'ship'."
}
```

--------------------------------

### Integrate Lexical Stress Metadata

Source: https://docs.langcraft.world/lexical-stress

Iterate through word groups and syllables to extract and render stress scores and expected stress indicators.

```ts
for (const word of response.word_groups ?? []) {
  for (const syllable of word.syllables ?? []) {
    const stress = syllable.stress;

    if (!stress) continue;

    renderSyllableStress({
      text: syllable.text,
      scorePercent: Math.round(stress.score * 100),
      expected: stress.expected === true,
    });
  }
}
```

--------------------------------

### Accuracy vs functional load definitions

Source: https://docs.langcraft.world/functional-load

Conceptual distinction between accuracy and functional load.

```text
How close was the learner's production to the target?
```

```text
How much does this specific phoneme substitution matter linguistically?
```

--------------------------------

### Identify functional load eligibility

Source: https://docs.langcraft.world/functional-load

Functional load is only present on phone objects where the grade is set to substitute.

```json
{
  "grade": "substitute"
}
```

--------------------------------

### Access Lexical Stress Path

Source: https://docs.langcraft.world/lexical-stress

The location of stress information within the response object structure.

```text
word_groups[].syllables[].stress
```

--------------------------------

### Functional Load Metadata

Source: https://docs.langcraft.world/functional-load

The functional load object is returned as optional metadata within phone objects in the /v1/speech/analyze response when a substitution error occurs.

```APIDOC
## Functional Load Metadata

### Description
Provides linguistic importance metrics for phoneme substitution errors. This object appears within phone objects in the `/v1/speech/analyze` response when `grade` is `substitute`.

### Fields
- **meaning_risk** (boolean) - True when this substitution can make the target word collide with another known word.
- **priority_score** (integer) - Main correction-priority score from 0 to 100.
- **priority_category** (string) - Human-readable category for priority_score (none, low, medium, high, critical).
- **meaning_risk_score** (integer) - Word-specific collision strength from 0 to 100.
- **meaning_risk_category** (string) - Human-readable category for meaning_risk_score.
- **contrast_category** (string) - Importance of this phone contrast across the language dictionary.
- **examples** (string[]) - Minimal-pair examples that explain the risk.

### Response Example
{
  "index": 1,
  "target": "ɪ",
  "predicted": "iː",
  "grade": "substitute",
  "functional_load": {
    "meaning_risk": true,
    "priority_score": 82,
    "priority_category": "critical",
    "meaning_risk_score": 82,
    "meaning_risk_category": "critical",
    "contrast_category": "critical",
    "examples": ["ship/sheep"]
  }
}
```

--------------------------------

### Speech Analysis JSON Response

Source: https://docs.langcraft.world/output

This JSON object represents the full structure of the speech analysis output, including proficiency metrics, word-level prosody, and phone-level alignment data.

```json
{
  "language": "en",
  "dialect": "en-us",
  "reference_text": "In recent years, many cities have begun redesigning public spaces...",
  "reference_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "predicted_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "audio": {"duration_sec": 56.83},
  "audio_duration_sec": 56.83,
  "pause_threshold_sec": 0.25,
  "pauses": [{"start": 2.1, "end": 2.6, "duration_sec": 0.5}],
  "pause_metrics": {
    "pause_count": 1,
    "average_pause_duration_sec": 0.5,
    "total_silence_time_sec": 0.5,
    "pause_ratio": 0.01
  },
  "speech_rate_wpm": 138.66,
  "articulation_rate_wpm": 139.9,
  "rate_metrics": {
    "word_count": 131,
    "speech_rate_wpm": 138.66,
    "articulation_rate_wpm": 139.9,
    "speaking_time_sec": 56.33
  },
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  },
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "prosody": {
        "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
        "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
      },
      "phones": [
        {
          "index": 15,
          "target": "s",
          "predicted": "z",
          "timestamp_ms": {"start": 1860.39, "end": 2060.44},
          "match_score_pct": 90.48,
          "grade": "substitute",
          "topk": [
            {"token": "z", "confidence_pct": 91.5},
            {"token": "s", "confidence_pct": 7.81}
          ]
        },
        {
          "index": 16,
          "target": "ɪ",
          "predicted": "ɪ",
          "timestamp_ms": {"start": 2060.44, "end": 2220.47},
          "match_score_pct": 100.0,
          "grade": "match",
          "topk": [
            {"token": "ɪ", "confidence_pct": 90.95},
            {"token": "iː", "confidence_pct": 4.55}
          ]
        },
        {
          "index": 17,
          "target": "ɾ",
          "predicted": "t",
          "timestamp_ms": {"start": 2220.47, "end": 2260.48},
          "match_score_pct": 61.72,
          "grade": "substitute",
          "topk": [
            {"token": "t", "confidence_pct": 54.07},
            {"token": "ɾ", "confidence_pct": 33.33}
          ]
        }
      ],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ"
        }
      ]
    },
    {
      "index": 9,
      "text": "spaces",
      "ipa": ["s", "p", "eɪ", "s", "ᵻ", "z"],
      "summary": {
        "avg_match_score_pct": 96.0,
        "total_phones": 6,
        "matches": 4,
        "num_insertions": 0,
        "num_deletions": 1,
        "num_substitutions": 1
      },
      "phones": [
        {
          "index": 45,
          "target": "eɪ",
          "predicted": null,
          "timestamp_ms": {"start": 4680.99, "end": 4801.01},
          "match_score_pct": null,
          "grade": "delete",
          "topk": [
            {"token": "eɪ", "confidence_pct": 5.22},
            {"token": "ɪ", "confidence_pct": 0.29}
          ]
        }
      ],
      "insertions": []
    }
  ],
  "proficiency_metrics": {
    "fluency": {
      "value": 82,
      "note": "Generally smooth delivery with minor hesitations between phrases."
    },
    "prosody": {
      "value": 78,
      "note": "Intonation is mostly natural but slightly flat on longer phrases."
    },
    "intelligibility": {
      "value": 91,
      "note": "Nearly all words are clearly articulated and easy to understand."
    }
  }
}
```
Tokens:
Raw