Getting started

1) Send a request

POST a multipart form request to the public API endpoint. Include your API key in the x-api-key header.

curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "[email protected]" \
  -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"

Request fields

Field	Example	Notes	Type	Required
`audio`	`@speech.wav`	Supported formats: WAV, M4A, FLAC, MP3, OGG, WEBM	file	yes
`reference_text`	`I can do it tomorrow.`	Reference text for forced alignment. If neither `reference_text` nor `reference_phones` is provided, the API runs automatic transcription. Accepted alias: `text`.	string	no
`reference_phones`	`h ə l oʊ`	Space-separated IPA phones to use as the reference. Multi-character phones like `tʃ` or `aʊ` must be one token. Accepted alias: `ipa`.	string	no
`lang`	`en`	Base language code. See Supported languages.	string	no
`dialect`	`en-us`	Full dialect code (can be used instead of `lang`). Default: `en-us`.	string	no
`model`	`aurora-1`	Optional public model selector. Use `aurora-1` for adult speech or `nova-1` for early-childhood speech. Send `default` or leave unset for automatic adult analysis.	string	no
`speaker_profile`	`early_childhood`	Alternative selector for Nova 1. Sending `early_childhood` selects the `nova-1` model.	string	no
`match_score_mode`	`lenient`	Optional scoring style for phone matches. `lenient` is the default and gives near-matches some credit. `strict` only gives credit for accepted matches.	string	no
`enable_prosody_contours`	`true`	Include pitch and stress contours in the response (default `false`).	boolean	no
`enable_proficiency_metrics`	`true`	Include holistic speaking scores in the response under `proficiency_metrics` (default `false`).	boolean	no

Model selection

For adult speech in any supported language, including English, set model=aurora-1. The API uses the same request and response schema across all supported languages. You can also send model=default or omit model; both remain valid and automatically select adult analysis for the request language. Example:

curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "[email protected]" \
  -F "reference_text=Ich kann das morgen machen." \
  -F "lang=de" \
  -F "model=aurora-1"

For early-childhood speech, send the separate public model model=nova-1. Alternatively, sending speaker_profile=early_childhood also selects Nova 1.

Audio upload options

You can provide audio in one of these ways:

Multipart upload (current default): multipart/form-data with a file field named audio.
Raw binary body: use the matching audio Content-Type such as audio/wav or audio/mp4, then POST the bytes directly.
Base64 in JSON: { "audio_b64": "..." }.
URL fetch: { "audio_url": "https://..." } (must be http(s) and sent as JSON, or included as a form field).

Supported formats

Currently supported: WAV, M4A, FLAC, MP3, OGG, WEBM.

Supported languages and dialects

See the full list of supported lang and dialect codes in the Supported languages reference.

Supported languages

Supported base language codes and dialect codes.

2) Read the response

The API returns a single JSON object:

{
  "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": []
}

For a full field‑by‑field breakdown, see the Output Reference.

Output reference

Explore the JSON schema and field definitions.

Reference

Preview

Updates

Getting started

1) Send a request

Request fields

Model selection

Audio upload options

Supported formats

Supported languages and dialects

Supported languages

2) Read the response

Output reference

​1) Send a request

​Request fields

​Model selection

​Audio upload options

​Supported formats

​Supported languages and dialects

Supported languages

​2) Read the response

Output reference

1) Send a request

Request fields

Model selection

Audio upload options

Supported formats

Supported languages and dialects

2) Read the response