> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.thymia.ai/helios/llms.txt.
> For full documentation content, see https://docs.thymia.ai/helios/llms-full.txt.

# Quickstart

In this guide you will create a Helios model run, upload a voice
recording, and retrieve biomarker scores — the complete end-to-end
flow of a Helios integration.

## Prerequisites

* A thymia API key. Contact [support@thymia.ai](mailto:support@thymia.ai)
  to request access.
* A voice recording in a supported format (FLAC, MP3, MP4, Ogg, WebM,
  or WAV) containing at least 10 seconds of speech.

## Step 1 — Create a model run

Create a new Helios model run for your user. This returns a unique
model run ID and a pre-signed URL to upload the recording to:

<EndpointRequestSnippet endpoint="POST /v1/models/mental-wellness" />

A successful response returns a model run ID and upload URL:

<EndpointResponseSnippet endpoint="POST /v1/models/mental-wellness" />

<Note>
  The `userLabel` should be a unique identifier from your system — for
  example, a user ID or anonymised reference. Model runs submitted with
  the same `userLabel` are assumed to refer to the same individual.
  Accurate demographic data directly affects the reliability of
  benchmarked results.
</Note>

## Step 2 — Upload the recording

Upload your voice recording to the pre-signed URL returned in the
previous step via a `PUT` request:

```bash
curl "https://path/to/upload" \
  -X PUT \
  -H 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/recording.mp3'
```

<Warning>
  The upload URL is valid for 1 hour. The model will not begin
  processing until the recording has been successfully uploaded.
</Warning>

## Step 3 — Poll for results

Once the recording is uploaded, Helios begins processing automatically.
Poll the model run endpoint using the ID returned in Step 1 until
results are available:

<EndpointRequestSnippet endpoint="GET /v1/models/mental-wellness/{model_run_id}" />

Check the `status` field in the response to determine whether
processing is complete:

| Status           | Meaning                                         |
| ---------------- | ----------------------------------------------- |
| `CREATED`        | Model run created, waiting for recording upload |
| `RUNNING`        | Recording uploaded, model is processing         |
| `COMPLETE_OK`    | Processing complete, results available          |
| `COMPLETE_ERROR` | Processing failed, see `errorCode` for details  |

We recommend polling every 3 seconds. Once processing is complete
the response will include a `results` field containing biomarker scores:

<EndpointResponseSnippet endpoint="GET /v1/models/mental-wellness/{model_run_id}" />

You have successfully run the Helios model and retrieved biomarker
scores for your user.

<Note>
  All requests to the thymia API must include your API key in the
  `x-api-key` header. Keep your key secret and never expose it in
  client-side code.
</Note>

## Next steps

* [Integration Guide](/helios/integration-guide) — Build a
  complete production integration including error handling, data
  deletion, and tagging.
* [Interpreting Results](/helios/interpreting-results) —
  Understand what the scores mean and how to present them to users.
* [Error Reference](/helios/error-reference) — Handle
  `COMPLETE_ERROR` responses correctly in your integration.

<div>
  ***
</div>

<div>
  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/bc677a592c05a522bf7c895b7e9f00da344a3487d5e6baf5e35f4b013bf0e0e5/docs/assets/certs/crown-commerical-logo.png" alt="Crown Commercial Service" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/0fd8cd1c5e2bf5fe9c88a9671b5d62d76ee00fff93b057d3f28295f6e74a8e54/docs/assets/certs/nhs-digital-toolkit-logo.png" alt="NHS Digital" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/3408b37c11afb0482b6108012fdea2edc6843ffa1a6a485d9440f2c28067165c/docs/assets/certs/iso-27001-logo.png" alt="ISO 27001" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/f82c2989ef0c7907f8acc1bf38c1debfb8061a0bad0fd4aff7a724794739e5b0/docs/assets/certs/iso-13485-logo.png" alt="ISO 13485" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/44816901d032fd0dc4b99030c62e6841d10b1796fde6dd1615bf23eb84f9114b/docs/assets/certs/HIPPA-logo.png" alt="HIPAA" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/1c6800dfced2f3bd97bd907302e2ae105c99ed91fd381e0cd64eef7886394779/docs/assets/certs/gdpr-logo.png" alt="GDPR" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/2276326b82aee8a143219440498266a25a1425c423a6854489e706af50d38118/docs/assets/certs/cyber-essentials-logo.png" alt="Cyber Essentials Certified" />
</div>