> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langcraft.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Make your first API request

## 1) Send a request

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

```bash theme={null}
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"
```

### 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](/dialects).                                                                                                          | 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 multilingual adult speech or `nova-1` for early-childhood speech. Leave unset for standard English 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 non-English speech, send the official public selector `model=aurora-1`.
`aurora-1` is an experimental public model selector currently recommended for German, French, and Spanish.

Example:

```bash theme={null}
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"
```

For early-childhood speech, send `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.

<Card title="Supported languages" icon="list" href="/dialects">
  Supported base language codes and dialect codes.
</Card>

## 2) Read the response

The API returns a single JSON object:

```json theme={null}
{
  "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.

<Card title="Output reference" icon="brackets-curly" href="/output">
  Explore the JSON schema and field definitions.
</Card>