thymia Documentation

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 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:

POST

/v1/models/mental-wellness

1 curl -X POST /v1/models/mental-wellness \
2      -H "x-api-key: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "user": {
6     "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
7     "dateOfBirth": "1990-08-24",
8     "birthSex": "MALE"
9   },
10   "language": "en-GB"
11 }'

Try it

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

Response

1 {
2   "id": "string",
3   "recordingUploadUrl": "https://path/to/upload"
4 }

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.

Step 2 — Upload the recording

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

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

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

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:

GET

/v1/models/mental-wellness/:model_run_id

1 curl /v1/models/mental-wellness/model_run_id \
2      -H "x-api-key: <apiKey>" \
3      -H "Content-Type: application/json"

Try it

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:

Response

1 {
2   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3   "createdAt": "2024-04-10T11:22:33Z",
4   "status": "COMPLETE_OK",
5   "userLabel": "john.doe@example.com",
6   "deleteData": true,
7   "runAt": "2024-04-10T11:25:00Z",
8   "completedAt": "2024-04-10T11:30:00Z",
9   "warnings": [
10     "Background noise detected, results may be less accurate"
11   ],
12   "results": {
13     "sections": [
14       {
15         "startSecs": 0,
16         "finishSecs": 15.2,
17         "transcript": "I have been feeling quite anxious lately, especially at work.",
18         "distress": {
19           "value": 0.65
20         },
21         "stress": {
22           "value": 0.72
23         },
24         "exhaustion": {
25           "value": 0.55
26         },
27         "sleepPropensity": {
28           "value": 0.4
29         },
30         "lowSelfEsteem": {
31           "value": 0.3
32         },
33         "mentalStrain": {
34           "value": 0.68
35         },
36         "uniformDistress": {
37           "value": 0.63
38         },
39         "uniformStress": {
40           "value": 0.7
41         },
42         "uniformExhaustion": {
43           "value": 0.52
44         },
45         "uniformSleepPropensity": {
46           "value": 0.38
47         },
48         "uniformLowSelfEsteem": {
49           "value": 0.28
50         }
51       },
52       {
53         "startSecs": 15.2,
54         "finishSecs": 30,
55         "transcript": "I try to relax by going for walks and meditating in the evenings.",
56         "distress": {
57           "value": 0.45
58         },
59         "stress": {
60           "value": 0.5
61         },
62         "exhaustion": {
63           "value": 0.4
64         },
65         "sleepPropensity": {
66           "value": 0.35
67         },
68         "lowSelfEsteem": {
69           "value": 0.25
70         },
71         "mentalStrain": {
72           "value": 0.48
73         },
74         "uniformDistress": {
75           "value": 0.43
76         },
77         "uniformStress": {
78           "value": 0.47
79         },
80         "uniformExhaustion": {
81           "value": 0.38
82         },
83         "uniformSleepPropensity": {
84           "value": 0.33
85         },
86         "uniformLowSelfEsteem": {
87           "value": 0.22
88         }
89       }
90     ]
91   },
92   "activityType": "read-aloud",
93   "tags": [
94     {
95       "name": "session",
96       "value": "morning-assessment"
97     }
98   ],
99   "dataToDelete": [
100     "RECORDINGS"
101   ],
102   "model": "mental-wellness-v2.1"
103 }

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

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.

Next steps

Integration Guide — Build a complete production integration including error handling, data deletion, and tagging.
Interpreting Results — Understand what the scores mean and how to present them to users.
Error Reference — Handle COMPLETE_ERROR responses correctly in your integration.