--- # API Reference: API Overview URL: https://docs.amplifierhealth.com/api-reference/overview The Amplifier Health API analyzes acoustic properties of a speaker's voice to produce structured health signals — numerical scores and categorical levels — across behavioral, cognitive, and metabolic conditions. The API provides two analysis layers: - **Condition API** (`POST /v2/condition/analyze`) — Analyze a single condition and receive the most detailed result for that model. Use this to build custom analysis logic tailored to your specific scenario. - **Use-Case API** (`POST /v2/use-case/analyze`) — Submit audio against a pre-defined bundle of conditions and receive an aggregated result with a summary and recommended action. Use this for common health and wellness scenarios out of the box. All endpoints return JSON. Successful v2 analyze and job responses return HTTP **200** with a **job object** in the body (see [Response Schema](/api-reference/schema)). Error responses return the appropriate HTTP status and a JSON object with `code`, `message`, and `status` — see [Error Reference](/api-reference/error-reference). ## Authentication All requests require `X-Account-ID`. The second required header depends on your API version: | Header | Description | | -------------- | ----------------------------- | | `X-Account-ID` | Your account identifier | | `X-Secret-Key` | Your secret key **(V1 only)** | | `X-API-Key` | Your API key **(V2 only)** | Sign up at [console.amplifierhealth.com](https://console.amplifierhealth.com), open the console, and create an API key under **Settings → API Keys**. Your account ID is shown in the console. See [Getting Started](/getting-started) for the full walkthrough. The examples below call **v2** `GET /v2/account/credits` with `X-API-Key`. **V1** uses the same `X-Account-ID` header but **`X-Secret-Key`** instead of `X-API-Key`, and paths under `/api/v1/...` (for example `GET https://api.amplifierhealth.com/api/v1/account/credits`) — see [Legacy API (v1)](/api-reference/v1-overview). #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/account/credits" \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const response = await fetch("https://api.amplifierhealth.com/v2/account/credits", { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const data = await response.json(); ``` #### Python ```python import os import httpx response = httpx.get( "https://api.amplifierhealth.com/v2/account/credits", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ## Limits | Limit | Value | | ----------------------- | ------------------------- | | Maximum audio file size | 32 MB per upload | | Maximum audio duration | 20 minutes (1200 seconds) | | Minimum audio duration | 15 seconds | | Supported formats | WAV, FLAC, MP3 | For longer recordings, MP3 or FLAC typically keep file size under the 32 MB limit. See [Audio Requirements](/guides/audio-requirements#file-size). ## Rate Limits The API enforces per-account rate limits using a sliding 60-second window. Limits vary by **rate limit plan**: | Plan | General Endpoints | Upload / Analyze Endpoints | | ------------------ | ------------------ | -------------------------- | | Standard (default) | 10 requests/min | 5 requests/min | | Enterprise | 1,000 requests/min | 500 requests/min | **Upload / Analyze endpoints**: - V2: `POST /v2/use-case/analyze`, `POST /v2/condition/analyze` - V1: `POST /api/v1/{condition}/analyze-audio`, `analyze-audio-url`, `analyze-and-diarize-audio`, `analyze-and-diarize-audio-url` **General endpoints** (all other requests): - V2: `GET /v2/account/credits`, `GET /v2/jobs`, `GET /v2/jobs/{job_id}`, `POST /v2/account/webhook` - V1: `GET /api/v1/account/credits`, `GET /api/v1/account/jobs`, `GET /api/v1/account/jobs/{job_id}`, `POST /api/v1/account/webhook` When a rate limit is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating seconds until the window resets. See [Error Reference](/api-reference/error-reference) for retry guidance. To request rate limit changes, please contact . --- # API Reference: Quick Start URL: https://docs.amplifierhealth.com/api-reference/quick-start This example covers the complete request-response cycle for a behavioral health screening. All use cases follow the same structure — only the `use_case` value and the `signals` array differ. ## Step 1 — Submit audio #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "use_case=behavioral-health" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("use_case", "behavioral-health"); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/use-case/analyze", { method: "POST", headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, body: form, }); const submitJson = await submitResponse.json(); const job_id = submitJson.job_id; ``` #### Python ```python # Requires httpx: pip install httpx # Alternatively, replace httpx.post(...) with requests.post(...) from the requests library. import os import httpx with open("recording.wav", "rb") as f: audio_bytes = f.read() submit_response = httpx.post( "https://api.amplifierhealth.com/v2/use-case/analyze", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, files={"audio": ("recording.wav", audio_bytes, "audio/wav")}, data={"use_case": "behavioral-health"}, ) job_id = submit_response.json()["job_id"] ``` This example uses `behavioral-health`. All use case IDs follow the same request and response structure — only the `use_case` value and the `signals` array contents differ. See [Use case IDs](/api-reference/use-case-analyze#use-case-ids) for the full list. Requests use `Content-Type: multipart/form-data`. The `audio` field accepts a binary file upload; all other fields are form fields. Each file must be **32 MB** or smaller. For longer recordings, prefer MP3 or FLAC so the file stays under the limit — details in [Audio Requirements](/guides/audio-requirements#file-size). The response returns immediately with the job object. `status` is `running` and `result` is `null` until processing completes: ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "running", "created_at": "2026-02-22T09:14:00Z", "completed_at": null, "result": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null } ``` ## Step 2 — Retrieve the result Use the `job_id` from Step 1 with `GET /v2/jobs/{job_id}`. The **cURL** tab uses the sample `job_id` from the response example above; **JavaScript** and **Python** reuse the `job_id` variable from Step 1. Poll at 2–5 second intervals. Most jobs complete within a few seconds; longer recordings may take up to 30 seconds. #### cURL ```bash curl https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109 \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const jobResponse = await fetch("https://api.amplifierhealth.com/v2/jobs/" + job_id, { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const job = await jobResponse.json(); console.log(job.result.summary.recommended_action); ``` #### Python ```python job_response = httpx.get( "https://api.amplifierhealth.com/v2/jobs/" + job_id, headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) job = job_response.json() print(job["result"]["summary"]["recommended_action"]) ``` ## Result Behavioral health screening result with elevated depression indicators: ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "done", "created_at": "2026-02-22T09:14:00Z", "completed_at": "2026-02-22T09:14:03Z", "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "result": { "summary": { "overall_level": "elevated", "recommended_action": "escalate", "flagged_count": 3, "primary_signals": ["depression", "anxiety", "acute-stress"], "description": { "summary": "Voice patterns suggest elevated indicators for depression and anxiety. Speech rate and rhythmic patterns were notably different from typical patterns.", "vocal_features": [ { "feature": "speech_rate", "label": "Speech Rate", "value": 3.2, "unit": "syllables/s", "value_interpretation": "reduced" } ] } }, "signals": [ {"model_id": "depression", "label": "Depression", "score": 0.81, "level": "elevated", "flagged": true}, {"model_id": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true}, {"model_id": "acute-stress", "label": "Acute Stress & Nervousness", "score": 0.54, "level": "consider", "flagged": true} ], "audio_quality": { "issues": [], "voice_percentage": 82.4, "audio_clarity": 74.1 }, "extended_metrics": [ { "metric_id": "anxious-mood", "label": "Anxious Mood", "score_mean": 0.72, "score_std": 0.08, "low_anchor": "tranquil", "high_anchor": "panicked" } ] } } ``` ### Timestamps and edge cases Parse timestamps with an ISO 8601-compatible library. The API may return timestamps with or without fractional seconds and with varying timezone designators. Job datetimes (`created_at`, `completed_at`): [Response Schema — Timestamps](/api-reference/schema#timestamps). Failed jobs (`result`, HTTP `200`): [Job Status: Failed](/api-reference/schema#job-status-failed). `audio_quality` fields (`issues`, `voice_percentage`, `audio_clarity`) and issue codes: [Response Schema — `audio_quality`](/api-reference/schema#audio_quality-object). Reading this response: - `job.result.summary.recommended_action` is `escalate` — trigger your urgent alert workflow. - `job.result.summary.primary_signals` lists the top contributors: `depression`, `anxiety`. - `job.result.summary.description.summary` is a narrative of the voice findings — surface to qualified care staff only, not in automated alerts or patient-facing output. - `job.result.summary.description.vocal_features` lists the acoustic measurements that informed the summary — use `label` and `value_interpretation` for display; keep `feature` for internal use. - In `job.result.signals`, use `level` and `flagged` for display logic. Keep `score` for internal use only — see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines) for display label mappings. - `job.result.audio_quality.issues` is empty — the recording met quality standards. - `job.result.extended_metrics` contains wellness dimension scores for the use case bundle. --- # API Reference: POST /v2/use-case/analyze URL: https://docs.amplifierhealth.com/api-reference/use-case-analyze ### POST /v2/use-case/analyze Submit audio for voice biomarker analysis. Specify a use\_case to select the bundled model set that runs against the audio. ## Request Body Requests use `Content-Type: multipart/form-data`. | Field | Type | Required | Description | | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio` | file | Yes | Audio file (WAV, FLAC, or MP3). Max 32 MB per file. For longer recordings, MP3 or FLAC usually keep the file under the limit. See [Audio Requirements](/guides/audio-requirements#file-size). | | `use_case` | string | Yes | Analysis bundle. See Use case IDs below. | | `diarize` | boolean | No | Whether to apply speaker diarization. Default: false. | | `webhook_url` | string | No | Per-request webhook URL. Overrides the account-level webhook for this job. The API sends an HTTP POST to this URL when analysis completes. Must be provided together with webhook\_secret\_key — omit both or include both. | | `webhook_secret_key` | string | No | Required when webhook\_url is provided. Used to sign the webhook payload (HMAC-SHA256) so your server can verify it came from Amplifier. Must be provided together with webhook\_url — omit both or include both. | ## Use case IDs Each `use_case` selects a fixed bundle of models. Bundles combine models at different **evidence tiers**; use each signal’s tier when interpreting results — see [Model Overview](/guides/models#evidence-tiers) and [Models](/api-reference/models). For the one-time **as-is** disclaimer for all models, see [Introduction](/guides/introduction). The list order matches [Use Cases — Available use case IDs](/guides/use-cases#available-use-case-ids). | use\_case | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `behavioral-health` | Behavioral health screening — includes depression, anxiety, acute stress & nervousness, and more | | `substance-use` | Substance use screening — includes alcohol use disorder, psychoactive substance use, and more | | `womens-health` | Women's health screening — includes hyperandrogenism (PCOS), anemia, dehydration, and more | | `wellness` | General wellness and readiness monitoring — includes fatigue & malaise, acute stress, dehydration, and more | | `athletics-occupational` | Athletics and occupational health screening — includes traumatic brain injury, cognitive impairment, fatigue, dehydration, and more | | `cognitive` | Cognitive impairment analysis — cognitive impairment; designed for cognitive health and ADHD management platforms | | `cardiometabolic` | Cardiometabolic risk screening — includes elevated blood pressure, overweight & obesity, dehydration, and more | | `respiratory` | Chronic respiratory issues screening — COPD and allergy | For full use case descriptions and per-model evidence tiers, see [Use Cases](/guides/use-cases) and [Use Cases reference](/guides/use-cases-all). To analyze a single condition directly — without a named bundle — use [POST /v2/condition/analyze](/api-reference/condition-analyze). ## Webhooks Instead of polling `GET /v2/jobs/{job_id}`, you can receive results via webhook. When a webhook is configured, the API sends an HTTP POST to your URL when analysis completes. **Two levels of webhook configuration:** - **Account-level webhook** — Set via [POST /v2/account/webhook](/api-reference/v2-account#webhook). Applies to all jobs for the account. - **Per-request webhook** — Pass `webhook_url` and `webhook_secret_key` as form fields on the analyze request. Overrides the account-level webhook for that job only. ### Example: submit with per-request webhook #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "use_case=behavioral-health" \ -F "audio=@recording.wav;type=audio/wav" \ -F "webhook_url=https://your-server.com/webhooks/amplifier" \ -F "webhook_secret_key=your-webhook-secret" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("use_case", "behavioral-health"); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); form.append("webhook_url", "https://your-server.com/webhooks/amplifier"); form.append("webhook_secret_key", "your-webhook-secret"); await fetch("https://api.amplifierhealth.com/v2/use-case/analyze", { method: "POST", headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, body: form, }); ``` #### Python ```python import os import httpx with open("recording.wav", "rb") as f: audio_bytes = f.read() httpx.post( "https://api.amplifierhealth.com/v2/use-case/analyze", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, files={"audio": ("recording.wav", audio_bytes, "audio/wav")}, data={ "use_case": "behavioral-health", "webhook_url": "https://your-server.com/webhooks/amplifier", "webhook_secret_key": "your-webhook-secret", }, ) ``` The submit call returns `{"job_id": "..."}` as usual. When analysis completes, the API delivers the result to `https://your-server.com/webhooks/amplifier` as a signed HTTP POST. See [Webhooks](/api-reference/v2-account#webhook) for payload format, signature verification, and retry behavior. ## Code Examples _For a step-by-step walkthrough with an annotated response, see [Quick Start](/api-reference/quick-start)._ ### Submit #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "use_case=behavioral-health" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("use_case", "behavioral-health"); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/use-case/analyze", { method: "POST", headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, body: form, }); const submitJson = await submitResponse.json(); const job_id = submitJson.job_id; ``` #### Python ```python import os import httpx with open("recording.wav", "rb") as f: audio_bytes = f.read() submit_response = httpx.post( "https://api.amplifierhealth.com/v2/use-case/analyze", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, files={"audio": ("recording.wav", audio_bytes, "audio/wav")}, data={"use_case": "behavioral-health"}, ) job_id = submit_response.json()["job_id"] ``` ### Example response The API returns immediately with the job object. `status` is `running` and `result` is `null` until processing completes: ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "running", "created_at": "2026-02-22T09:14:00Z", "completed_at": null, "result": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null } ``` ### Poll job #### cURL ```bash curl https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109 \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const jobResponse = await fetch("https://api.amplifierhealth.com/v2/jobs/" + job_id, { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const job = await jobResponse.json(); ``` #### Python ```python job_response = httpx.get( "https://api.amplifierhealth.com/v2/jobs/" + job_id, headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) job = job_response.json() ``` See [Jobs](/api-reference/results) for the full job response schema. ### Timestamps and payload edge cases `created_at` and `completed_at` are ISO 8601; use a standard datetime parser. Formatting varies (`Z`, offsets, optional fractional seconds). For timestamp parsing rules, failed-job behavior, and `audio_quality` field details, see [Response Schema — Timestamps](/api-reference/schema#timestamps), [Job Status: Failed](/api-reference/schema#job-status-failed), and [`audio_quality`](/api-reference/schema#audio_quality-object). ## Response The response returns immediately with the full job object (`job_id`, `status`, `created_at`, `completed_at`, `result`, `audio_*`, `use_case`). The `status` is `running` and `result` is `null` until processing completes — poll `GET /v2/jobs/{job_id}` or configure a webhook to receive the completed result. For any full job object from `GET /v2/jobs/{job_id}` or a webhook, timestamps, `audio_quality` fields, and **failed** jobs are specified in [Response Schema — Job response](/api-reference/schema#job-response) (subsections linked under [Timestamps and payload edge cases](#timestamps-and-payload-edge-cases) above). When `result.summary.recommended_action` is `inconclusive`, handle it as "no clear signal; prefer re-recording or collecting more information" — see [Levels & Actions](/api-reference/levels-actions) and [Interpreting Results](/guides/interpreting-results). If only one of `webhook_url` or `webhook_secret_key` is provided, the request returns `400 Bad Request`. Provide both or omit both. For other error codes and retry guidance, see [Error Reference](/api-reference/error-reference). --- # API Reference: POST /v2/condition/analyze URL: https://docs.amplifierhealth.com/api-reference/condition-analyze ### POST /v2/condition/analyze Submit audio to analyze a single condition. Returns a job object immediately; poll GET /v2/jobs/{job\_id} or use a webhook for the completed result. The condition API is the base layer of the Amplifier API. Each call analyzes a single condition against the submitted audio. Use this API when the out-of-box use cases don't match your scenario — call multiple conditions separately and compose your own analysis logic. Evidence tiers and the product disclaimer are the same as for use-case analysis; see [Introduction](/guides/introduction) and [Model Overview — Evidence tiers](/guides/models#evidence-tiers). For pre-built bundles that group multiple conditions into a single call, see [POST /v2/use-case/analyze](/api-reference/use-case-analyze). ## Request Body Requests use `Content-Type: multipart/form-data`. | Field | Type | Required | Description | | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio` | file | Yes | Audio file (WAV, FLAC, or MP3). Max 32 MB per file. For longer recordings, MP3 or FLAC usually keep the file under the limit. See [Audio Requirements](/guides/audio-requirements#file-size). | | `condition` | string | Yes | Condition model ID to analyze (e.g. depression, anxiety, cognitive-impairment). See [Models](/api-reference/models) for valid IDs and evidence tiers. | | `diarize` | boolean | No | Whether to apply speaker diarization. Default: false. | | `webhook_url` | string | No | Per-request webhook URL. Overrides the account-level webhook for this job. The API sends an HTTP POST to this URL when analysis completes. Must be provided together with webhook\_secret\_key — omit both or include both. | | `webhook_secret_key` | string | No | Required when webhook\_url is provided. Used to sign the webhook payload (HMAC-SHA256) so your server can verify it came from Amplifier. Must be provided together with webhook\_url — omit both or include both. | ## Code Examples ### Submit #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/condition/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "condition=depression" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("condition", "depression"); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/condition/analyze", { method: "POST", headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, body: form, }); const submitJson = await submitResponse.json(); const job_id = submitJson.job_id; ``` #### Python ```python import os import httpx with open("recording.wav", "rb") as f: audio_bytes = f.read() submit_response = httpx.post( "https://api.amplifierhealth.com/v2/condition/analyze", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, files={"audio": ("recording.wav", audio_bytes, "audio/wav")}, data={"condition": "depression"}, ) job_id = submit_response.json()["job_id"] ``` ### Example response ```json { "job_id": "4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f", "status": "running", "created_at": "2026-02-22T09:14:00Z", "completed_at": null, "result": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "job_type": "condition", "api_version": "v2", "use_case": null, "condition": "depression" } ``` ### Poll job #### cURL ```bash curl https://api.amplifierhealth.com/v2/jobs/4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const jobResponse = await fetch("https://api.amplifierhealth.com/v2/jobs/" + job_id, { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const job = await jobResponse.json(); ``` #### Python ```python job_response = httpx.get( "https://api.amplifierhealth.com/v2/jobs/" + job_id, headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) job = job_response.json() ``` See [Jobs](/api-reference/results) for the full job response schema. The multipart and polling flow matches [Quick Start](/api-reference/quick-start); use form field **`condition`** instead of **`use_case`**. ## Response The response returns immediately with the full job object (`job_id`, `status: running`, `result: null`). Poll `GET /v2/jobs/{job_id}` or configure a webhook to receive the completed result. The job object is the same as [POST /v2/use-case/analyze](/api-reference/use-case-analyze#response), but the `result` interior is structurally different. Condition results use a **singular `signal` object** — not a `summary` + `signals[]` array. The `signal` carries `recommended_action` and `description` directly, with no `summary` wrapper. For condition-analyze jobs, the job object has `job_type: "condition"`, `condition` set to the model ID you submitted (e.g. `"depression"`), and `use_case: null`. ### Reading the result - `result.signal.recommended_action` — the action for this condition: `none`, `monitor`, `consider`, `review`, `escalate`, or `inconclusive`. Map to your workflow triggers. See [Levels & Actions](/api-reference/levels-actions). - `result.signal.level` — the display primitive: `none` | `low` | `consider` | `moderate` | `elevated` | `inconclusive`. Use for UI rendering; keep `score` for internal use only. - `result.signal.flagged` — `true` when the level warrants attention. - `result.signal.description` — narrative summary and vocal features. Surface only after review by qualified care staff. - `result.audio_quality.issues` — when non-empty, review issue codes before routing on the result. When `signal.recommended_action` is `inconclusive`, handle as "no clear signal; prefer re-recording or collecting more information" — see [Interpreting Results](/guides/interpreting-results). See [Condition Response Schema](/api-reference/schema#condition-response) for the complete field reference. If only one of `webhook_url` or `webhook_secret_key` is provided, the request returns `400 Bad Request`. Provide both or omit both. For error codes and retry guidance, see [Error Reference](/api-reference/error-reference). ## Building custom use cases To analyze multiple conditions against the same recording, submit separate requests with the same audio — one per `condition`. Each call creates an independent job. #### cURL ```bash # Analyze three conditions for a custom mental health check curl -X POST https://api.amplifierhealth.com/v2/condition/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "condition=depression" \ -F "audio=@recording.wav;type=audio/wav" curl -X POST https://api.amplifierhealth.com/v2/condition/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "condition=anxiety" \ -F "audio=@recording.wav;type=audio/wav" curl -X POST https://api.amplifierhealth.com/v2/condition/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "condition=ptsd" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const audioBytes = fs.readFileSync("recording.wav"); const headers = { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }; async function submitCondition(condition) { const form = new FormData(); form.append("condition", condition); form.append("audio", new Blob([audioBytes], { type: "audio/wav" }), "recording.wav"); const res = await fetch("https://api.amplifierhealth.com/v2/condition/analyze", { method: "POST", headers, body: form, }); return res.json(); } const j1 = await submitCondition("depression"); const j2 = await submitCondition("anxiety"); const j3 = await submitCondition("ptsd"); ``` #### Python ```python import os import httpx with open("recording.wav", "rb") as f: audio_bytes = f.read() headers = { "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], } def submit_condition(condition: str) -> dict: return httpx.post( "https://api.amplifierhealth.com/v2/condition/analyze", headers=headers, files={"audio": ("recording.wav", audio_bytes, "audio/wav")}, data={"condition": condition}, ).json() j1 = submit_condition("depression") j2 = submit_condition("anxiety") j3 = submit_condition("ptsd") ``` Each result is independent. Your application aggregates and interprets the results according to your own logic. --- # API Reference: Jobs URL: https://docs.amplifierhealth.com/api-reference/results ## GET /v2/jobs Get a paginated list of jobs for the account. Results are returned in reverse chronological order. ``` GET https://api.amplifierhealth.com/v2/jobs ``` ### Query Parameters | Parameter | Type | Description | | --------- | ------- | ----------------------------------------------- | | `page` | integer | Page number to retrieve. 0-based. Default: `0`. | ### Response | Field | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------- | | `jobs` | array | List of job summary objects for the current page. Each object has `job_id`, `status`, and `created_at`. | | `page` | integer | The current page number (0-based). | | `total_pages` | integer | Total number of pages available. | Each item in `jobs`: | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------ | | `job_id` | string | Unique job identifier. Use with `GET /v2/jobs/{job_id}` to retrieve the full result. | | `status` | string | Job status: `pending` \| `running` \| `done` \| `failed`. | | `created_at` | string | ISO 8601 datetime; fractional seconds and timezone suffix may vary. | ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/jobs?page=0" \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const response = await fetch("https://api.amplifierhealth.com/v2/jobs?page=0", { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const data = await response.json(); ``` #### Python ```python import os import httpx response = httpx.get( "https://api.amplifierhealth.com/v2/jobs", params={"page": 0}, headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Errors For 401 and other codes, see [Error Reference](/api-reference/error-reference). --- ## GET /v2/jobs/{job\_id} Retrieve a previously submitted job by ID. For a valid `job_id` on your account, the API returns **`200 OK`** with a **job object**. **`status`** tells you whether the job is still running, succeeded (`done`), or failed (`failed`) — failure is expressed in the body, not only via HTTP error codes (see [Job Status: Failed](#job-status-failed)). ``` GET https://api.amplifierhealth.com/v2/jobs/{job_id} ``` ### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------- | | `job_id` | string | The `job_id` returned from `POST /v2/use-case/analyze`. | ### Response | Field | Type | Description | | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `job_id` | string | Unique job identifier. | | `status` | string | Job status: `pending` \| `running` \| `done` \| `failed`. | | `created_at` | string | ISO 8601 datetime; fractional seconds and timezone designator may vary. See [Response Schema — Timestamps](/api-reference/schema#timestamps). | | `completed_at` | string or null | ISO 8601; null while running. See [Timestamps](/api-reference/schema#timestamps) and [Job Status: Failed](/api-reference/schema#job-status-failed). | | `job_type` | string | `"use_case"` or `"condition"`. | | `api_version` | string | `"v1"` or `"v2"`. | | `use_case` | string or null | Use-case bundle name. Populated for use-case jobs, null for condition jobs. | | `condition` | string or null | Condition model ID. Populated for condition jobs, null for use-case jobs. | | `audio_content_type` | string | MIME type of the submitted audio (e.g. `audio/wav`). | | `audio_size_bytes` | integer | Size in bytes of the submitted audio as accepted and processed for this job. | | `audio_duration_seconds` | number | Duration of the submitted audio in seconds. | | `audio_sample_rate` | integer or null | Sample rate in Hz (e.g. 16000). | | `result` | object or null | When `done`, full analysis. When `failed`, typically `null`. [Job Status: Failed](/api-reference/schema#job-status-failed); [Result Object](#result-object) below. | ### Job Status: Failed `status: "failed"` means processing ended unsuccessfully. For a valid `job_id`, the API returns `200 OK` with the job object — failure is expressed in `status`, not only via HTTP codes. `result` is usually `null`; poll until `done` or `failed`, then branch. Full contract: [Response Schema — Job Status: Failed](/api-reference/schema#job-status-failed). ### Result Object `result` contains the full analysis output when `status` is **`done`**. | Field | Type | Description | | ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------- | | `summary` | object | Aggregated result across all signals. See [Response Schema](/api-reference/schema#summary-object). | | `signals` | array | Per-model signal results. See [Response Schema](/api-reference/schema#signals-array). | | `audio_quality` | object | Recording quality scores and detected issue codes. See [Response Schema](/api-reference/schema#audio_quality-object). | | `extended_metrics` | array | Per-metric wellness scores. See [Response Schema](/api-reference/schema#extended_metrics-array). | When `result.summary.recommended_action` is `inconclusive`, handle it as "no clear signal; prefer re-recording or collecting more information" — see [Levels & Actions](/api-reference/levels-actions) and [Interpreting Results](/guides/interpreting-results). ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "done", "created_at": "2026-02-22T09:14:00Z", "completed_at": "2026-02-22T09:14:03Z", "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "result": { "summary": { ... }, "signals": [ ... ], "audio_quality": { ... }, "extended_metrics": [ ... ] } } ``` ### Example #### cURL ```bash curl -X GET https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109 \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const jobId = "189bce4a-52cb-4e60-8586-cef89e719109"; const response = await fetch("https://api.amplifierhealth.com/v2/jobs/" + jobId, { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); if (response.status === 404) { console.log("Job not found"); } else { const job = await response.json(); if (job.status === "done") { console.log(job.result.summary.recommended_action); } else if (job.status === "failed") { console.log("Job failed", job.completed_at); } } ``` #### Python ```python # Requires httpx: pip install httpx # Alternatively, replace httpx.get(...) with requests.get(...) from the requests library. import os import httpx job_id = "189bce4a-52cb-4e60-8586-cef89e719109" response = httpx.get( f"https://api.amplifierhealth.com/v2/jobs/{job_id}", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) if response.status_code == 404: print("Job not found") else: job = response.json() if job["status"] == "done": print(job["result"]["summary"]["recommended_action"]) elif job["status"] == "failed": print("Job failed", job.get("completed_at")) ``` ### Error Handling For authentication errors (401), verify your `X-Account-ID` and `X-API-Key` headers. For rate limiting (429), retry using exponential backoff and check the `Retry-After` header. For server errors (500), retry with exponential backoff. See [Error Reference](/api-reference/error-reference) for retry examples. The following conditions return `404 Not Found` for this endpoint: the `job_id` is incorrect, the job belongs to a different account, or the job was not found. Check the `job_id` value against the original `POST /v2/use-case/analyze` response and verify your `X-Account-ID` header. --- # API Reference: Response Schema URL: https://docs.amplifierhealth.com/api-reference/schema The Amplifier API documents two primary response shapes — **use-case** job results (bundled `summary` and `signals` array) and **condition** responses (a single `signal` object). - **Use-case analyze:** `POST /v2/use-case/analyze` returns the full job object immediately (`job_id`, `status: running`, `result: null`). Retrieve the completed result with **`GET /v2/jobs/{job_id}`**, or receive it via **webhook** — see [Use-case analyze](/api-reference/use-case-analyze). - **Condition analyze:** `POST /v2/condition/analyze` returns the same job object (multipart/form-data), but the `result` interior uses a singular `signal` object instead of `summary` + `signals[]`. Retrieve the completed result with **`GET /v2/jobs/{job_id}`** — see [Condition analyze](/api-reference/condition-analyze). - **Errors:** When a request fails, the API returns a JSON object with **code**, **message**, and **status** — see [Error Reference](/api-reference/error-reference). For workflow and display rules, see [Interpreting Results](/guides/interpreting-results). --- ## Use-Case Response ### Submit Response `POST /v2/use-case/analyze` returns the job object immediately. `status` is `running` and `result` is `null` until processing completes. Use `GET /v2/jobs/{job_id}` to retrieve the completed result. | Field | Type | Description | | ------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------- | | `job_id` | string | Unique identifier for the submitted job. | | `status` | string | Job status: `running` at submit time. | | `created_at` | string (ISO 8601) | Timestamp when the job was created. | | `completed_at` | null | Null until the job completes. | | `result` | null | Null until the job completes. | | `audio_content_type` | string | MIME type of the submitted audio. | | `audio_size_bytes` | integer | Size of the submitted audio file in bytes. | | `audio_duration_seconds` | number | Duration of the submitted audio in seconds. | | `audio_sample_rate` | integer or null | Sample rate of the submitted audio in Hz (e.g. 16000). | | `job_type` | string | `"use_case"` or `"condition"`. | | `api_version` | string | `"v1"` or `"v2"`. | | `use_case` | string or null | Use-case bundle name (e.g. `"behavioral-health"`). Populated for use-case jobs, null for condition jobs. | | `condition` | string or null | Condition model ID (e.g. `"depression"`). Populated for condition jobs, null for use-case jobs. | ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "running", "created_at": "2026-02-22T09:14:00Z", "completed_at": null, "result": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null } ``` ### Job Response `GET /v2/jobs/{job_id}` returns the job status and, when complete, the full analysis result. | Field | Type | Description | | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `job_id` | string | Unique job identifier. | | `status` | string | Job status: `pending` \| `running` \| `done` \| `failed`. | | `created_at` | string | ISO 8601; fractional seconds and timezone designator vary. See [Timestamps](#timestamps). | | `completed_at` | string or null | ISO 8601; null while `pending`/`running`. Semantics for `done` vs `failed`: [Timestamps](#timestamps), [Job Status: Failed](#job-status-failed). | | `job_type` | string | `"use_case"` or `"condition"`. | | `api_version` | string | `"v1"` or `"v2"`. | | `use_case` | string or null | Use-case bundle name. Populated for use-case jobs, null for condition jobs. | | `condition` | string or null | Condition model ID. Populated for condition jobs, null for use-case jobs. | | `audio_content_type` | string | MIME type of the submitted audio. | | `audio_size_bytes` | integer | Size in bytes of the submitted audio as accepted and processed for this job. | | `audio_duration_seconds` | number | Duration of the submitted audio in seconds. | | `audio_sample_rate` | integer or null | Sample rate in Hz. | | `result` | object or null | Full analysis when `status` is `done`. When `failed`, typically `null`. See [Job Status: Failed](#job-status-failed). | `result` contains: | Field | Type | Description | | ------------------ | ------ | ----------------------------------------------------------------------------------------- | | `summary` | object | Aggregated result across all signals. | | `signals` | array | Per-model signal results. | | `audio_quality` | object | Recording quality scores and detected issue codes. | | `extended_metrics` | array | Per-metric wellness scores for this use case. Empty array when no metrics are configured. | ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "done", "created_at": "2026-02-22T09:14:00Z", "completed_at": "2026-02-22T09:14:03Z", "use_case": "behavioral-health", "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "result": { "summary": { ... }, "signals": [ ... ], "audio_quality": { ... }, "extended_metrics": [ ... ] } } ``` ### Timestamps **Type:** `created_at` and `completed_at` are **ISO 8601** datetimes; **RFC 3339–compatible parsing** is recommended. **Variability:** The API may return: - A timezone designator: `Z` (UTC) or numeric offset `±hh:mm`, or omit the designator in some responses. - Fractional seconds at variable precision (milliseconds, microseconds, etc.). **UTC:** Values with a `Z` suffix are UTC. When no offset appears, treat the timestamp as UTC. **Client guidance:** Use a standard ISO 8601-compatible datetime parser. Avoid string-comparing timestamps or assuming a fixed number of fractional digits. **Examples (both valid):** _With `Z`, no fractional seconds:_ ```json "created_at": "2026-02-22T09:14:00Z", "completed_at": "2026-02-22T09:14:03Z" ``` _With fractional seconds, no `Z`:_ ```json "created_at": "2026-03-28T01:05:35.943000", "completed_at": "2026-03-28T01:05:38.120500" ``` ### Job Status: Failed When `status` is `"failed"`, processing ended unsuccessfully. For a valid `job_id` on your account, `GET /v2/jobs/{job_id}` still returns `200 OK` with a job object — failure is expressed in `status`, not via a 4xx HTTP code. Poll until `status` is `done` or `failed`, then branch: - **`done`:** `result` contains the full analysis. - **`failed`:** `result` is typically `null`; `completed_at` may also be `null`. If you need the failure reason, check your operational logs or contact support — the job object does not include a structured error code in this API version. `404 Not Found` applies when the job is unknown or belongs to a different account — see [Jobs — Error handling](/api-reference/results#error-handling). ### summary Object `result.summary` is the primary object for routing decisions. Read it first. | Field | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `overall_level` | string | Highest level across all signals: `none` \| `low` \| `consider` \| `moderate` \| `elevated` \| `inconclusive`. | | `recommended_action` | string | Highest-priority action: `none` \| `monitor` \| `consider` \| `review` \| `escalate` \| `inconclusive`. | | `flagged_count` | integer | Count of signals where `flagged: true`. | | `primary_signals` | string\[] | Top 1–3 `model_id` values by score, descending. | | `description` | object | Narrative `summary` plus `vocal_features`. See [Display and compliance](#display-and-compliance). | `overall_level` reflects the highest `level` value across all signals in the bundle. `recommended_action` is derived from the full distribution of signal levels — not from `overall_level` alone. See [Levels & Actions](/api-reference/levels-actions#recommended-action-trigger-logic) for the derivation logic. ```json { "overall_level": "elevated", "recommended_action": "escalate", "flagged_count": 3, "primary_signals": ["depression", "anxiety", "acute-stress"], "description": { "summary": "Voice patterns suggest elevated indicators for depression and stress...", "vocal_features": [ ... ] } } ``` ### signals Array `signals` contains one entry per model in the requested use case bundle. | Field | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_id` | string | Model identifier. See [Models](/api-reference/models). | | `label` | string | Human-readable model name. | | `score` | number | Raw confidence score, 0.0–1.0. For internal use only; use `level` for display. For the score-to-level mapping, see [Level Definitions](/api-reference/levels-actions#level-definitions). | | `level` | string | Quantized level: `none` \| `low` \| `consider` \| `moderate` \| `elevated` \| `inconclusive`. | | `flagged` | boolean | `true` when level is `consider`, `moderate`, or `elevated`. | ```json [ {"model_id": "depression", "label": "Depression", "score": 0.81, "level": "elevated", "flagged": true}, {"model_id": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true}, {"model_id": "acute-stress", "label": "Acute Stress & Nervousness", "score": 0.54, "level": "consider", "flagged": true} ] ``` For display rules and field usage guidance, see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines). ### description Object `description` is nested inside `summary`. It contains a machine-generated plain-text summary and a structured array of annotated vocal feature values. #### Display and compliance Surface `description` in care-staff interfaces only. For the full display and compliance rules, see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines). | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | `summary` | string | LLM-generated plain-text description of the acoustic findings. Not a diagnostic assessment. | | `vocal_features` | array | Annotated acoustic feature values that informed the summary. See [vocal\_features Array](#vocal_features-array) below. | ### vocal\_features Array Each entry in `vocal_features` describes a single acoustic measurement extracted from the recording. | Field | Type | Description | | ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | `feature` | string | Canonical feature identifier (e.g. `speech_rate`, `voice_shimmer`, `pitch_mean`). | | `label` | string | Human-readable feature name (e.g. `"Speech Rate"`, `"Voice Shimmer"`, `"Average Pitch"`). | | `value` | number | Measured value for this recording. | | `unit` | string | Unit of measurement (e.g. `"dB"`, `"syllables/s"`, `"Hz"`). | | `value_interpretation` | string | Interpretation relative to reference range: `"within range"` \| `"slightly elevated"` \| `"high"` \| `"reduced"` \| `"low"`. | ```json { "summary": "Voice patterns suggest elevated stress and fatigue indicators...", "vocal_features": [ { "feature": "speech_rate", "label": "Speech Rate", "value": 3.2, "unit": "syllables/s", "value_interpretation": "reduced" }, { "feature": "voice_shimmer", "label": "Voice Shimmer", "value": 0.041, "unit": "dB", "value_interpretation": "slightly elevated" } ] } ``` ### audio\_quality Object `audio_quality` provides quality scores for the submitted recording and flags any conditions so you can assess when to use the result or re-record. File-level metadata (size, duration, and format) is available on the job object fields (`audio_size_bytes`, `audio_duration_seconds`, `audio_content_type`). | Field | Type | Description | | ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `issues` | string\[] | Detected quality issue codes. Empty array means no issues. See [Audio Requirements](/guides/audio-requirements#audio-quality-issue-codes) for the full list and recommended actions. | | `voice_percentage` | number or null | Percentage of the recording containing active speech (0–100). A value of `0` means no speech was detected; `100` means the full recording contains active speech. Values below 30 typically correspond to an `insufficient_speech` issue. | | `audio_clarity` | number or null | Background noise quality score (0–100), derived from SI-SDR (Scale-Invariant Signal-to-Distortion Ratio). Higher values indicate a clearer recording with less background noise. Values below 50 typically correspond to a `high_background_noise` issue. | `issues`, `voice_percentage`, and `audio_clarity` are coherent: when a score is below its threshold, the corresponding issue code will typically be present in `issues`. ```json { "issues": [], "voice_percentage": 82.4, "audio_clarity": 74.1 } ``` Example with quality issues detected: ```json { "issues": ["high_background_noise", "insufficient_speech"], "voice_percentage": 21.3, "audio_clarity": 38.6 } ``` When `issues` is non-empty, signals may still be returned. Use the issue codes to decide whether to act on the result or re-record — see [Audio Requirements](/guides/audio-requirements#audio-quality-issue-codes) for recommended actions for each code. ### extended\_metrics Array `extended_metrics` contains wellness metric scores derived from the voice recording. The set of metrics returned depends on the `use_case` — each use case exposes a defined subset. For metric definitions see [Wellness](/guides/wellness); for how condition models are composed into each bundle see [Use Cases reference](/guides/use-cases-all). | Field | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------- | | `metric_id` | string | Canonical metric identifier (e.g. `anxious-mood`, `vad-valence`). | | `label` | string | Human-readable metric name (e.g. `"Anxious Mood"`, `"Emotional Valence"`). | | `score_mean` | number | Mean score, 0.0–1.0. | | `score_std` | number | Standard deviation of the score, 0.0–1.0. | | `low_anchor` | string | Verbal anchor describing the state at score ≈ 0 (e.g. `"tranquil"`). | | `high_anchor` | string | Verbal anchor describing the state at score ≈ 1 (e.g. `"panicked"`). | ```json [ { "metric_id": "anxious-mood", "label": "Anxious Mood", "score_mean": 0.72, "score_std": 0.08, "low_anchor": "tranquil", "high_anchor": "panicked" }, { "metric_id": "vad-valence", "label": "Emotional Valence", "score_mean": 0.38, "score_std": 0.05, "low_anchor": "negative", "high_anchor": "positive" } ] ``` --- ## Condition Response `POST /v2/condition/analyze` returns the same **job object** as use-case analyze (see [Job Response](#job-response) above), but with `job_type: "condition"`, `condition` populated, `use_case` null, and the **`result` interior is structurally different**. The `result` object uses a singular `signal` object instead of `summary` + `signals[]`: ```json { "job_id": "4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f", "status": "done", "job_type": "condition", "api_version": "v2", "use_case": null, "condition": "depression", "result": { "signal": { ... }, "audio_quality": { ... }, "extended_metrics": [ ... ] } } ``` ### signal Object `signal` is a single object (not an array) containing the full result for the requested condition. Unlike the use-case response — where `description` and `recommended_action` live on the `summary` wrapper — the condition response places them directly on `signal`. | Field | Type | Description | | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_id` | string | Condition model analyzed. See [Models](/api-reference/models). | | `label` | string | Human-readable condition name. | | `score` | number | Raw confidence score, 0.0–1.0. For internal use only; use `level` for display. For the score-to-level mapping, see [Level Definitions](/api-reference/levels-actions#level-definitions). | | `level` | string | Quantized level: `none` \| `low` \| `consider` \| `moderate` \| `elevated` \| `inconclusive`. | | `flagged` | boolean | `true` when level is `consider`, `moderate`, or `elevated`. | | `recommended_action` | string | Action for this condition: `none` \| `monitor` \| `consider` \| `review` \| `escalate` \| `inconclusive`. | | `description` | object | Narrative `summary` plus `vocal_features`. Same schema as the use-case [description Object](#description-object). | `recommended_action` is derived from this condition's `level` alone — not aggregated across a bundle. See [Levels & Actions](/api-reference/levels-actions#recommended-action-trigger-logic) for the derivation logic. `description` contains an LLM-generated plain-text summary of the acoustic findings and a structured `vocal_features` array. The same [display and compliance](#display-and-compliance) rules apply: surface in care-staff interfaces only, not in automated alerts or patient-facing output. On the inconclusive path, `summary` contains a standard inconclusive message and `vocal_features` is empty. ```json { "model_id": "depression", "label": "Depression", "score": 0.81, "level": "elevated", "flagged": true, "recommended_action": "escalate", "description": { "summary": "Voice patterns suggest elevated indicators for depression...", "vocal_features": [ { "feature": "speech_rate", "label": "Speech Rate", "value": 3.2, "unit": "syllables/s", "value_interpretation": "reduced" } ] } } ``` For display rules, see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines). --- # API Reference: Levels & Actions URL: https://docs.amplifierhealth.com/api-reference/levels-actions For end-to-end workflow guidance and display rules for clinical and patient-facing UIs, see [Interpreting Results](/guides/interpreting-results). ## Level Definitions Signal levels are applied to individual models in the `signals` array and to `overall_level` in `summary`. | Level | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `none` | Signal not detected at a meaningful threshold. | | `low` | Faint signal detected. Monitor for changes. | | `consider` | Signal worth considering. Review alongside other clinical context. | | `moderate` | Signal present. Provider review indicated. | | `elevated` | Signal present at the highest level. Trigger your escalation workflow. | | `inconclusive` | Analysis inconclusive or incomplete (for example, limited speech or notable `audio_quality` issues); prefer re-recording or collecting more information before routing. | > Score-to-level mapping uses a distribution-based calibration unique to each model, rather than fixed numeric ranges. This means the score value corresponding to each level varies by model. Use `level` — not raw `score` — for routing and display logic. If you log raw `score` values for analytics, note the API version and model ID alongside each result. For display label mappings (e.g. `elevated` → "Significant indicator"), see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines). ## Recommended Action Trigger Logic `recommended_action` is determined by evaluating the full set of signal levels, not any single model in isolation. In some cases, both `overall_level` and `recommended_action` may be `inconclusive` when the analysis cannot complete to the usual quality standards (for example, very short recordings or notable `audio_quality` issues). | Condition | recommended\_action | | --------------------------------------------------- | ------------------- | | No signals at low, consider, moderate, or elevated | `none` | | 1+ at low (none at consider, moderate, or elevated) | `monitor` | | 1+ at consider | `consider` | | 1+ at moderate OR 2+ at consider | `review` | | 1+ at elevated | `escalate` | When recording conditions may be below optimal for analysis, the API may return `recommended_action: "inconclusive"` and `overall_level: "inconclusive"`. Treat this as “no clear signal; prefer re-recording or collecting more information” rather than as a monitoring, review, or escalation trigger. `escalate` takes precedence over all other conditions. When any signal is at `elevated`, the action is always `escalate` regardless of other signals. --- # API Reference: Error Reference URL: https://docs.amplifierhealth.com/api-reference/error-reference ## Error Codes Every error returns this structure: ```json {"code": "AUDIO_TOO_SHORT", "message": "Audio duration is below the minimum required threshold.", "status": 400} ``` | Code | HTTP Status | Description | Retry | | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | `UNAUTHORIZED` | 401 | X-Account-ID is missing or invalid, or the credential header is missing or invalid: use X-API-Key for v2 and X-Secret-Key for v1. Verify your credentials and resubmit. | Correct and resubmit | | `INSUFFICIENT_CREDITS` | 402 | No credits remaining for the account. Add credits or contact support to continue. | Add credits or contact support before resubmitting | | `NOT_FOUND` | 404 | Resource not found. Returned by GET /v2/jobs/{job\_id} when the job\_id is invalid or the job belongs to another account; and by v1 job detail when the job\_id is invalid or not found. Verify the ID and your X-Account-ID header. | Verify the ID and account; correct and resubmit | | `INVALID_USE_CASE` | 400 | The use\_case value is not recognized. Correct the value using the use case IDs table and resubmit. | Correct and resubmit | | `AUDIO_POOR_QUALITY` | 422 | Recording conditions may be below the threshold used for analysis. Improve the recording environment and resubmit. | Correct and resubmit | | `AUDIO_TOO_SHORT` | 400 | Recording is under 15 seconds. Submit a recording of at least 15 seconds. | Correct and resubmit | | `AUDIO_TOO_LONG` | 400 | Recording exceeds the 20-minute (1200-second) maximum. Trim to 20 minutes or fewer and resubmit. | Correct and resubmit | | `UNSUPPORTED_FORMAT` | 400 | Audio format is not supported. Use WAV, FLAC, or MP3. | Correct and resubmit | | `RATE_LIMIT_EXCEEDED` | 429 | Rate limit reached. Check the Retry-After response header and retry using exponential backoff. | Retry with backoff | | `PROCESSING_ERROR` | 500 | Internal processing error. Retry with the same payload using exponential backoff — no changes to the request are needed. | Retry with backoff | ## Retry Guidance For `429` and `500` responses, use exponential backoff: - Start at 1 second. - Double the delay on each attempt. - Maximum 5 retries. - For `429`, check the `Retry-After` response header before retrying. Other `4xx` responses indicate a request condition to correct before resubmitting. For `402`, add credits or contact support before resubmitting. For `404`, verify the result or job ID and your account. For other codes, review the error message, adjust the request, and resubmit. --- # API Reference: Model IDs Reference URL: https://docs.amplifierhealth.com/api-reference/models All models are classified by evidence tier (Established, Emerging, or Investigational) based on published voice-based studies using acoustic analysis of human speech. The table below lists all available model IDs, their evidence tiers, and the use case bundles they appear in. For available `use_case` IDs and how to choose a bundle, see [Use Cases](/guides/use-cases). For full descriptions and per-bundle model lists, see [Use Cases reference](/guides/use-cases-all). For the **as-is** disclaimer and how tiers fit together, see [Introduction](/guides/introduction). ## Available Models Each `model_id` in the table corresponds to an entry in the `signals` array of the API response. For example: ```json {"model_id": "depression", "label": "Depression", "score": 0.81, "level": "elevated", "flagged": true} ``` See [Response Schema](/api-reference/schema#signals-array) for the full `signals` field reference. | model\_id | Label | Tier | Relevant Use Cases | | ------------------------- | -------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- | | `acute-stress` | Acute Stress & Nervousness | `established` | behavioral-health, substance-use, wellness, athletics-occupational | | `adhd` | ADHD | `emerging` | behavioral-health | | `alcohol-use` | Alcohol Use Disorder | `emerging` | substance-use | | `allergy` | Allergy | `emerging` | respiratory | | `anemia` | Anemia | `investigational` | womens-health, cardiometabolic | | `anxiety` | Anxiety | `established` | behavioral-health, substance-use, wellness, athletics-occupational | | `anxiety-female` | Anxiety (Female) | `established` | womens-health | | `cognitive-impairment` | Cognitive Impairment | `established` | athletics-occupational, cognitive | | `copd` | COPD | `established` | respiratory | | `dehydration` | Dehydration | `investigational` | wellness, athletics-occupational, womens-health, cardiometabolic | | `depression` | Depression | `established` | behavioral-health, substance-use, wellness | | `depression-female` | Depression (Female) | `established` | womens-health | | `dry-mouth` | Dry Mouth | `investigational` | cardiometabolic | | `elevated-blood-pressure` | Elevated Blood Pressure | `established` | wellness, athletics-occupational, womens-health, cardiometabolic | | `fatigue` | Fatigue & Malaise | `established` | behavioral-health, substance-use, wellness, athletics-occupational, womens-health, cardiometabolic, respiratory | | `hyperandrogenism` | Hyperandrogenism (PCOS) | `emerging` | womens-health | | `overweight-obesity` | Overweight & Obesity | `emerging` | cardiometabolic | | `ptsd` | PTSD | `emerging` | behavioral-health | | `substance-use` | Psychoactive Substance Use | `emerging` | substance-use | | `traumatic-brain-injury` | Traumatic Brain Injury | `established` | athletics-occupational | --- # API Reference: v2 API — Account URL: https://docs.amplifierhealth.com/api-reference/v2-account Configure a webhook to receive results via push instead of polling. When a webhook is configured, the API sends an HTTP POST to your URL when analysis completes. The webhook payload contains the job result — see [Response Schema](/api-reference/schema) for field definitions. For when to use webhooks and implementation best practices, see [Production Checklist — Webhooks](/guides/production-checklist#webhooks-if-applicable). ## POST /v2/account/webhook ### POST /v2/account/webhook Set the webhook URL and secret for the account. Once configured, your webhook is called when an audio analysis completes. ### Request Body | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `url` | string | Yes | HTTPS URL where webhooks are sent. Must be publicly accessible. | | `secret_key` | string | Yes | Secret used to sign webhook payloads. Store securely and use only for signature verification on your server. | ### Example #### cURL ```bash curl -X POST "https://api.amplifierhealth.com/v2/account/webhook" \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{"url":"https://your-server.com/webhooks/amplifier","secret_key":"your-webhook-secret"}' ``` #### JavaScript ```javascript await fetch("https://api.amplifierhealth.com/v2/account/webhook", { method: "POST", headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://your-server.com/webhooks/amplifier", secret_key: "your-webhook-secret", }), }); ``` #### Python ```python import os import httpx httpx.post( "https://api.amplifierhealth.com/v2/account/webhook", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, json={ "url": "https://your-server.com/webhooks/amplifier", "secret_key": "your-webhook-secret", }, ) ``` ### How webhooks work - Webhooks are sent **asynchronously** when analysis completes successfully. - The API sends an HTTP POST to your configured URL with a JSON payload. - If your endpoint is unavailable or returns a non-2xx status, the system retries delivery up to 5 times with increasing delays. Respond within 30 seconds to avoid timeout. ### Webhook request format **Headers:** - `Content-Type: application/json` - `X-Webhook-Signature`: HMAC-SHA256 signature of the raw request body (use to verify the request came from Amplifier) **Payload:** The body contains the completed job result: `job_id`, `status`, `use_case`, `result` (with `summary`, `signals`, `audio_quality`, `extended_metrics`). See [Response Schema](/api-reference/schema) for field definitions. ### Signature verification To verify the webhook request came from Amplifier: 1. Read the raw request body (as bytes or string) and the `X-Webhook-Signature` header. 2. Compute HMAC-SHA256 of the raw body using your `secret_key`. 3. Compare the computed value with the header using a constant-time comparison. **Example (Python only):** HMAC verification is typically implemented on your server; below uses the Python standard library. ```python # Requires no additional packages — hmac and hashlib are Python standard library modules. import hmac import hashlib def verify_webhook_signature(secret_key: str, payload_body: str, signature_header: str) -> bool: expected = hmac.new( secret_key.encode("utf-8"), payload_body.encode("utf-8"), hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature_header) # In your webhook handler: # payload_body = request.get_data(as_text=True) # or request.body.decode("utf-8") # signature = request.headers.get("X-Webhook-Signature", "") # if verify_webhook_signature(secret_key, payload_body, signature): # process_job(json.loads(payload_body)) ``` ### Response | Field | Type | Description | | --------- | ------- | ----------------------------------- | | `success` | boolean | Whether the webhook was configured. | | `message` | string | Confirmation message. | For implementation best practices, see [Production Checklist — Webhooks](/guides/production-checklist#webhooks-if-applicable). ### Errors Validation errors return `422` with a detail array. For authentication (401), rate limiting (429), and other codes, see [Error Reference](/api-reference/error-reference). ## GET /v2/account/credits ### GET /v2/account/credits Check remaining credits for the account. ### Response | Field | Type | Description | | --------- | ------- | ---------------------------------- | | `credits` | integer | Remaining credits for the account. | If the account has no remaining credits, analyze endpoints return `402 Payment Required`. Check this endpoint before submitting jobs. ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/account/credits" \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" ``` #### JavaScript ```javascript const response = await fetch("https://api.amplifierhealth.com/v2/account/credits", { headers: { "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID, "X-API-Key": process.env.AMPLIFIER_API_KEY, }, }); const data = await response.json(); ``` #### Python ```python import os import httpx response = httpx.get( "https://api.amplifierhealth.com/v2/account/credits", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Errors For 401 and other codes, see [Error Reference](/api-reference/error-reference). --- # Guides: Introduction URL: https://docs.amplifierhealth.com/guides/introduction The **Amplifier Health API** analyzes voice recordings (WAV, FLAC, or MP3, up to **32 MB** per file) and returns structured health signals—scores, levels, and workflow-oriented fields—for behavioral, cognitive, and metabolic models. ## Two analyze endpoints Both endpoints use **`multipart/form-data`**: an **`audio`** file plus a selector field. Successful responses return a **job object** (JSON). Errors return a JSON object with **code**, **message**, and **status** — see [Error Reference](/api-reference/error-reference). | Endpoint | Selector | Best for | | ---------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- | | [`POST /v2/use-case/analyze`](/api-reference/use-case-analyze) | `use_case` | Pre-built bundles—one call, summary + `signals[]` + single `recommended_action`. | | [`POST /v2/condition/analyze`](/api-reference/condition-analyze) | `condition` | One model per request; compose your own logic from multiple jobs. | Details, optional fields (e.g. diarization, per-request webhooks), and examples: [Use-case analyze](/api-reference/use-case-analyze), [Condition analyze](/api-reference/condition-analyze). ## Job flow Submit returns a **job object** right away (`job_id`, `status: running`, `result: null`). When analysis finishes, obtain the completed job by **webhook** and/or **`GET /v2/jobs/{job_id}`** — see [Jobs](/api-reference/results). Typed, enumerated values are meant for routing in apps, wellness products, and clinical-adjacent workflows; how to display and interpret them is covered in [Interpreting Results](/guides/interpreting-results) and [Response Schema](/api-reference/schema). ## Use case bundles Eight `use_case` IDs select fixed model bundles. Short map below; full lists and guidance: [Use Cases](/guides/use-cases), [Use case IDs](/guides/use-cases#available-use-case-ids), [Use Cases reference](/guides/use-cases-all). - **Behavioral Health** (`behavioral-health`) — depression, anxiety, acute stress & nervousness, and more - **Substance Use** (`substance-use`) — alcohol use disorder, psychoactive substance use, and more - **Women's Health** (`womens-health`) — hyperandrogenism (PCOS), anemia, dehydration, and more - **General Wellness** (`wellness`) — fatigue & malaise, acute stress & nervousness, dehydration, and more - **Athletics & Occupational** (`athletics-occupational`) — TBI, cognitive impairment, fatigue, dehydration, and more - **Cognitive** (`cognitive`) — cognitive impairment; cognitive health and ADHD-oriented products - **Cardiometabolic** (`cardiometabolic`) — elevated blood pressure, overweight & obesity, dehydration, and more - **Respiratory** (`respiratory`) — COPD and allergy Per-model **evidence tiers** (how much published voice-based research supports each model): [Model Overview](/guides/models#evidence-tiers), [Models](/api-reference/models). ## Key concepts - **Auth (v2).** Send `X-Account-ID` and `X-API-Key` on every request. Keys and account ID live in the console (**Settings → API Keys**). Legacy v1 uses `X-Secret-Key` — [Legacy API](/api-reference/v1-overview). Walkthrough: [Getting Started](/getting-started). - **Routing fields.** Use enumerated **`level`** and **`recommended_action`** for UI and automation; keep raw **`score`** internal. Narrative text under `summary` / descriptions is supporting context only—follow [Interpreting Results](/guides/interpreting-results) for display rules. - **`audio_quality`.** Check `issues` before acting on a result; see [Audio Requirements](/guides/audio-requirements) for recording guidance and issue codes. - **Outputs are biomarker signals, not diagnoses.** `recommended_action` supports workflow routing; clinical decisions belong with qualified staff. > **Note:** > > **As-is.** All models and API outputs are provided **as-is**. > > Labels such as **Established**, **Emerging**, and **Investigational** describe the **depth of published academic and scientific research** behind each model and how use-case bundles combine those models. They are not a separate commercial tier, contract, or entitlement. --- # Guides: Interpreting Results URL: https://docs.amplifierhealth.com/guides/interpreting-results Submitting audio returns a `job_id` immediately. Poll [`GET /v2/jobs/{job_id}`](/api-reference/results) or use a **webhook** until `status` is a terminal value: **`done`** or **`failed`**. - **Use-case analyze** — [`POST /v2/use-case/analyze`](/api-reference/use-case-analyze). When `status` is **`done`**, `result` contains `summary`, `signals`, and `audio_quality` — read them in that order for routing, per-condition detail, and recording quality. - **Condition analyze** — [`POST /v2/condition/analyze`](/api-reference/condition-analyze). When `status` is **`done`**, `result` contains a single `signal` and `audio_quality` (no bundle `summary` or `signals[]`). See [Condition API job results](#condition-api-job-results). When `status` is **`failed`**, `result` is usually `null`; see [Job status: failed](/api-reference/schema#job-status-failed). For field-level reference see [Response Schema](/api-reference/schema). For model IDs and tiers see [Models](/api-reference/models). Use-case bundles combine models with different **evidence tiers** (Established, Emerging, Investigational). Interpret each signal using its model’s tier — see [Use Cases](/guides/use-cases) and [Models](/api-reference/models). For the product disclaimer and how tiers fit together, see [Introduction](/guides/introduction). ## Response structure overview ```text job ├── job_id — Unique job identifier ├── status — pending | running | done | failed (poll until done | failed) ├── use_case — The use case bundle that was run ├── created_at — ISO 8601; format varies — see Response Schema → Timestamps ├── completed_at — null while pending/running; when done vs failed see Schema ├── audio_content_type — MIME type of submitted audio ├── audio_size_bytes — Size of submitted audio ├── audio_duration_seconds └── result — Full analysis when status is done; typically null when failed ├── summary — Aggregate view; primary routing object │ ├── overall_level │ ├── recommended_action │ ├── flagged_count │ ├── primary_signals │ └── description — Natural language summary and vocal features │ ├── summary — Narrative text of voice pattern findings │ └── vocal_features[] ├── signals[] — Array of per-model results ├── audio_quality — Recording quality scores and issue codes └── extended_metrics[] ``` ## Condition API job results If you use [`POST /v2/condition/analyze`](/api-reference/condition-analyze), send multipart **`audio`** plus a **`condition`** model ID. The API returns a **job object** right away (`job_id`, `status: running`, `result: null` until processing finishes). Poll [`GET /v2/jobs/{job_id}`](/api-reference/results) or use a **webhook** until `status` is **`done`** or **`failed`** — same delivery pattern as use-case analyze; only the completed **`result`** shape differs. On the outer job object, `job_type` is `condition`, `condition` is the model you requested, and `use_case` is `null`. When `status` is `done`, **`result`** holds one **`signal`** object for that model (`recommended_action`, `level`, `description`, scores, and related fields) and **`audio_quality`**. There is no top-level **`summary`** and no **`signals[]`** array; use **`result.signal`** for routing and UI. When `status` is `failed`, `result` is usually `null`; see [Job status: failed](/api-reference/schema#job-status-failed). Field-level detail: [Condition response](/api-reference/schema#condition-response) and [POST /v2/condition/analyze — Response](/api-reference/condition-analyze#response). The same [display and compliance rules](/api-reference/schema#display-and-compliance) apply when presenting outputs. ## The summary object `summary` is the primary object for routing decisions. It aggregates all signal scores into a single recommended action and level. Read `summary` first: if `recommended_action` is `none` or `monitor`, your workflow may not need to inspect individual signals at all. When the action is `consider`, `review`, or `escalate`, check `primary_signals` to identify which conditions are driving the result, then inspect the corresponding entries in `signals` for score detail. For field definitions, see [Response Schema](/api-reference/schema#summary-object). ## The description object `summary.description` provides a narrative of the voice analysis alongside a set of interpretable acoustic features. It has two fields: - **`summary`** — Describes the voice pattern findings for this recording. Contains no PII. See [Display Guidelines](#display-guidelines) for display guidance. - **`vocal_features`** — An array of the acoustic features most relevant to the analysis. Each entry describes one measured voice characteristic. Each item in `vocal_features` has the following shape: | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | `feature` | string | Canonical feature ID (e.g. `speech_rate`, `pitch_variability`) | | `label` | string | Human-readable name (e.g. "Speech Rate") | | `value` | number | Numeric measurement after any display conversion | | `unit` | string | Unit of measurement (e.g. `"syllables/s"`, `"Hz"`, `"dB"`) | | `value_interpretation` | string | Plain-language interpretation: `"within range"`, `"slightly elevated"`, `"high"`, `"reduced"`, or `"low"` | `vocal_features` is appropriate for display to qualified care staff as supporting context for the summary narrative. ## Signal levels Signal levels are applied both to individual models in the `signals` array and to `overall_level` in `summary`. The five risk-derived levels are `none`, `low`, `consider`, `moderate`, and `elevated`, each mapping to a score range and a clinical interpretation, and there is an additional neutral `inconclusive` level for cases where the analysis cannot complete to the usual quality standards. Use `none` to represent a clear “within normal range” result; use `inconclusive` when there is no clear signal at all and you prefer to re-record or collect more information rather than making a routing decision. | Level | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `none` | Signal not detected at a meaningful threshold. | | `low` | Faint signal detected. Monitor for changes. | | `consider` | Signal worth considering. Review alongside other clinical context. | | `moderate` | Signal present. Provider review indicated. | | `elevated` | Signal present at the highest level. Trigger your escalation workflow. | | `inconclusive` | Analysis inconclusive or incomplete (for example, limited speech or notable audio\_quality issues); prefer re-recording or collecting more information before routing. | > Score-to-level mapping uses a distribution-based calibration unique to each model, rather than fixed numeric ranges. Use `level` — not raw `score` — for routing and display logic. For the full trigger logic table, see [Levels & Actions — Recommended Action Trigger Logic](/api-reference/levels-actions#recommended-action-trigger-logic). ## Recommended action logic `recommended_action` aggregates **all** signal levels (not one model alone). See [Levels & Actions — Recommended Action Trigger Logic](/api-reference/levels-actions#recommended-action-trigger-logic) for the full trigger table. **Why `review` includes two or more at `consider`:** Co-occurring signals at the `consider` level can warrant provider attention even when each alone would only trigger a `consider` action. One signal at `consider` → `consider`; two or more at `consider` → `review`. When recording conditions may be below optimal for analysis, the API may return `recommended_action: "inconclusive"` and `overall_level: "inconclusive"`. Treat this as "no clear signal; prefer re-recording or collecting more information" rather than as a monitoring, review, or escalation trigger. ## The signals array `signals` contains one entry per model in the requested use case bundle. Each entry describes the model's output for this specific audio sample. In most integrations, filter by `flagged: true` to surface only the conditions the API considers noteworthy for this recording. Unflagged signals (`flagged: false`) are still valuable for logging and analytics, even when not shown to end users — they establish a baseline for detecting changes over time. For field definitions, see [Response Schema](/api-reference/schema#signals-array). For display guidance, see [Display Guidelines](#display-guidelines). ## The audio\_quality object `audio_quality` provides quality scores for the recording and flags any conditions so you can assess when to use the result or re-record. It contains `issues` (array of issue codes), `voice_percentage` (0–100, percentage of recording with active speech), and `audio_clarity` (0–100, background noise quality score). File-level metadata such as size, duration, and format is available on the job object fields. For field definitions and issue codes, see [Response Schema — audio\_quality Object](/api-reference/schema#audio_quality-object) and [Audio Requirements](/guides/audio-requirements#audio-quality-issue-codes). When `issues` is non-empty, signals may still be returned. Use the issue codes to decide whether to act on the result or re-record; for critical routing decisions, prefer re-recording when quality issues are present. > **Info:** > > If `audio_quality.issues` contains `invalid_speaker`, request a new recording before routing on this result. These conditions make signal values less predictable, and re-recording is recommended. ## Display Guidelines Amplifier outputs include fields intended for internal system logic and fields appropriate for end-user display. Mixing these up is the most common integration mistake. **What to display:** - `level` — Use this as your primary display primitive. It conveys meaning without revealing the raw score. - `label` — The human-readable condition name. - `flagged` — Use to filter which signals appear in a user-facing view. **Keep for internal use:** - `score` — Use `level` and `label` for display; keep raw `score` values for internal logging and analytics. - `description.summary` — Auto-generated narrative; surface it only after review by qualified care staff, not as direct patient-facing output. Located at `summary.description.summary` in use-case responses, `signal.description.summary` in condition responses. - `model_id` — Internal identifier; use `label` instead. Use the display labels below for patient or end-user display. `flagged` is `true` when a signal's `level` is `consider`, `moderate`, or `elevated`. | level | Display Label | UI Treatment | | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------- | | `none` | Within normal range | Neutral | | `low` | Faint indicator | Informational | | `consider` | Worth considering | Informational / Caution | | `moderate` | Notable indicator | Caution | | `elevated` | Significant indicator | Alert | | `inconclusive` | Analysis inconclusive | Neutral; suggest re-recording or collecting more information rather than treating this as a risk level. | Use language that is informational and non-diagnostic; do not use clinical diagnostic terms. ## Handling errors When the API returns a non-200 response, check the HTTP status code before retrying. For the full list of error codes, retry guidance, and exponential backoff examples, see [Error Reference](/api-reference/error-reference). --- # Guides: Billing & Cost URL: https://docs.amplifierhealth.com/guides/billing-and-cost Amplifier pricing is based on **audio tokens**. Charges are **flat per call** — audio duration does not affect cost. ## When charges apply Billing is tied to **processing**, not to whether every signal comes back decisive. Once the API has analyzed your audio, that usage counts **regardless of signal outcome** or **`audio_quality` flags**—decisive, inconclusive, and quality-flagged responses all reflect completed compute. ## Token rates | API call | Tokens | With diarization | | -------------------------------------------------------------- | :----: | :--------------: | | **Condition API** (`/v2/condition/analyze`) | 50 | 100 | | **Use-case API** (`/v1/analyze-audio`, `/v2/use-case/analyze`) | 75 | 125 | The **diarization add-on** costs a flat **+50 tokens** on top of the base rate. Audio duration has no effect on token consumption. ## Example calculations | Scenario | Tokens | Cost | | ----------------------------------------------- | ------ | ----- | | Depression screen (Condition API, any duration) | 50 | $0.10 | | behavioral-health use case, no diarization | 75 | $0.15 | | behavioral-health use case + diarization | 125 | $0.25 | | Condition API + diarization | 100 | $0.20 | Token price: **$0.002 per token** ($10 = 5,000 tokens). For **diarization**, add a flat 50 tokens to the base rate regardless of audio length. See [Speaker diarization](/guides/audio-requirements#speaker-diarization) in Audio Requirements. --- # Guides: Audio Requirements URL: https://docs.amplifierhealth.com/guides/audio-requirements Follow these guidelines to get the most accurate analysis results from each recording. This page covers supported formats, duration, encoding, recording environment best practices, and audio quality issue codes. ## Supported formats | Format | Notes | | ------ | ----------------------------------------------------------------------------- | | `wav` | Lossless quality; larger file sizes | | `flac` | Lossless compression; smaller than WAV with no quality loss | | `mp3` | Accepted; often smaller than WAV; helps you stay under the 32 MB upload limit | The API detects the format from the uploaded file. Submitting an unsupported format returns `UNSUPPORTED_FORMAT` with HTTP **`400`**. ## File size | Limit | Value | | ---------------- | ----- | | Maximum per file | 32 MB | For longer recordings, **MP3** or **FLAC** usually keep file size under the limit while preserving good analysis quality. ## Duration | Duration | Outcome | | -------------------------------------- | -------------------------------------------------------------------------------- | | Less than 15 seconds | Returns `400 Bad Request`; submit a recording of at least 15 seconds | | 15–19 seconds | Processed; check `audio_quality` for guidance on use | | 20–120 seconds | Recommended range for best results | | 2–20 minutes | Accepted; longer recordings have longer processing times (up to several minutes) | | Greater than 20 minutes (1200 seconds) | Returns `400 Bad Request`; trim to 20 minutes or fewer before submitting | Recordings on the shorter end of the 15–19 second range are more likely to produce `insufficient_speech` issues. ## Sample rate | Parameter | Value | | ----------- | ------------------------------------------------------------ | | Minimum | 8000 Hz | | Recommended | 16000 Hz | | Maximum | No hard upper limit; higher rates are downsampled internally | Record and submit at 16000 Hz where possible for best results across all models. ## Channels Mono recordings are recommended. Stereo recordings are accepted — the API automatically downmixes stereo input to mono before analysis. For best results, mixing to mono before submitting is still preferred. ## Speaker diarization Speaker diarization identifies and separates individual speakers in a multi-speaker recording, then analyzes each speaker independently. Use diarization when the recording contains two or more speakers — for example, a clinician-patient interview or a group therapy session. ### When to use diarization - **Single speaker** — `diarize=false` (default). Recommended for most use cases. - **Multiple speakers** — `diarize=true`. The API identifies each speaker and runs analysis separately on their voice segments. Single-speaker recordings analyzed with `diarize=true` still work — the diarizer detects one speaker and processes normally — but diarization adds a flat **50 tokens** on top of the base rate (see [Billing & cost](/guides/billing-and-cost)). ### How to enable **V2 API:** Pass `diarize=true` as a form field on `POST /v2/use-case/analyze`. ```bash curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "use_case=behavioral-health" \ -F "diarize=true" \ -F "audio=@recording.wav;type=audio/wav" ``` **V1 API:** Use the dedicated diarization endpoints — `POST /api/v1/{condition}/analyze-and-diarize-audio` or `POST /api/v1/{condition}/analyze-and-diarize-audio-url`. V1 diarization is async only. See [Legacy API — Conditions](/api-reference/v1-pipelines) for details. ### Processing time Diarization adds a speaker separation step before analysis, which increases total processing time. For longer recordings, processing can take several minutes. Submit returns a job immediately; retrieve results via `GET /v2/jobs/{job_id}` or webhook. ## Submitting audio Audio is submitted as `multipart/form-data` with the file in the `audio` field. For a complete working example with all parameters, see [POST /v2/use-case/analyze](/api-reference/use-case-analyze). ## Recording environment guidelines The acoustic environment affects every model. Poor recording conditions are the leading cause of quality issues. Follow the guidelines below to get the best results. **Environment:** - Record in a quiet space with minimal background noise. Avoid open offices, public spaces, or rooms with significant echo. - Eliminate sources of intermittent noise (fans, air conditioning, notifications) where possible. **Microphone:** - Use a close-proximity microphone. Headset microphones, lavaliers, and phone handsets held close to the mouth produce consistently better results than speakerphone or far-field microphones. - Avoid clipping. If the speaker's voice is loud, lower the input gain until audio levels peak around -6 dBFS. **Speaker:** - Capture a single speaker per recording. - The speaker should be the subject being assessed, not a clinician or interviewer. > **Tip:** > > Before deploying in a new environment — a clinic room, a mobile app, an enterprise desktop — test recording levels with a sample recording and check `audio_quality.issues` in the response. Fix issues before going live. ## Free-form speech Most use cases work well with free-form conversational speech. Ask the speaker to talk naturally about any topic: how their day is going, how they have been feeling, or anything they are comfortable sharing. ## Language support Amplifier's models are currently trained on **English-language speech**. Support for additional languages is in active development. Before deploying in a multilingual environment: - Confirm supported languages for each model you intend to use. Contact Amplifier for the current language support matrix. - Verify that each model supports the languages in your deployment. - Contact before deploying in any multilingual context. > **Warning:** > > Submitting audio in an unsupported language can produce signal values without a quality warning. Always verify language compatibility for your target population before deploying in production. ## Audio quality issue codes When the API detects recording problems, it returns issue codes in `audio_quality.issues`. Results may still be returned alongside issues. Use the issue codes to decide whether to use the result or re-record. | Code | Effect on results | Recommended action | | ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | | `poor_voice_quality` | Recording may be below optimal for analysis | Re-record in a quieter environment with a better microphone | | `insufficient_speech` | Limited speech detected; more continuous speech may improve results | Re-record with more active continuous speech; eliminate long pauses | | `high_background_noise` | Background noise may affect analysis quality | Re-record in a quieter space or with a closer microphone | | `invalid_speaker` | No clear single-speaker human speech detected | Verify the recording contains the intended speaker's voice | When `issues` contains `invalid_speaker`, request a new recording before routing on the result. See [Interpreting Results](/guides/interpreting-results#the-audio_quality-object) for guidance on how to handle quality conditions in your routing logic. --- # Guides: Use Cases — Overview URL: https://docs.amplifierhealth.com/guides/use-cases A use case is a pre-configured bundle of acoustic models selected for a specific clinical or wellness context. When you submit audio to [`POST /v2/use-case/analyze`](/api-reference/use-case-analyze), the `use_case` field determines which models run on that recording and which signals appear in the response. To analyze a single condition directly, use [`POST /v2/condition/analyze`](/api-reference/condition-analyze) — see [Condition API](/api-reference/condition-analyze). ## How use cases work Specify a use case by passing its ID in the `use_case` field of the request body: ```bash curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "use_case=behavioral-health" \ -F "audio=@recording.wav;type=audio/wav" ``` The submit call returns a `job_id`; retrieve the full result (with `summary`, `signals`, etc.) via `GET /v2/jobs/{job_id}`. Every use case runs all of its models on the submitted audio and returns a `signals` array with one entry per model. The `summary` object aggregates across all signals in the bundle to produce `overall_level`, `recommended_action`, and `flagged_count`. In most cases these fields use the standard levels (`none`, `low`, `consider`, `moderate`, `elevated`) and actions (`none`, `monitor`, `consider`, `review`, `escalate`); when `overall_level` and `recommended_action` are `inconclusive`, treat the result as “no clear signal” and prefer re-recording or deferring routing until a conclusive result is available. ## Available use case IDs The `use_case` values below match [POST /v2/use-case/analyze](/api-reference/use-case-analyze#use-case-ids). For descriptions and per-bundle model lists, see [Use Cases reference](/guides/use-cases-all). | `use_case` | Summary | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | `behavioral-health` | Behavioral health screening — depression, anxiety, acute stress, PTSD, ADHD, fatigue, and more | | `substance-use` | Substance use screening — alcohol use disorder, psychoactive substance use, and co-occurring signals | | `womens-health` | Women's health — PCOS-related signals, anemia, dehydration, gender-stratified mood models, and more | | `wellness` | General wellness and readiness — fatigue, stress, dehydration, mood, blood pressure, and more | | `athletics-occupational` | Athletics and occupational health — TBI, cognitive impairment, fatigue, dehydration, stress, and more | | `cognitive` | Cognitive impairment — primary cognitive signal for neurology and brain health contexts | | `cardiometabolic` | Cardiometabolic risk — blood pressure, overweight & obesity, dehydration, anemia, dry mouth, fatigue | | `respiratory` | Respiratory — COPD and allergy signals with contextual models | ## Selecting the right use case Choose the use case that best matches the clinical or wellness context in which you are deploying. The right use case is determined primarily by who your end users are and what conditions are most clinically relevant for that population. If your platform serves a general behavioral health population — primary care, teletherapy, employee wellness — start with `behavioral-health` or `wellness`. If your context is specialized — substance use, cognitive assessment, sports medicine — use the corresponding specialized bundle, which is tuned with the models most predictive for that population. Prefer the specialized bundle when one exists for your context. The specialized bundles are configured with the models most validated for their respective populations, which improves both precision and the clinical relevance of `recommended_action` outputs. If your platform serves multiple population contexts — for example, a corporate wellness platform that also supports a substance use recovery programme — submit separate requests with the most specific `use_case` ID for each participant population. This ensures each group's signals are evaluated with the models most validated for that context. See [Use Cases reference](/guides/use-cases-all) for full detail on each bundle. If no existing use case fits your deployment context or you need a custom model configuration, contact to discuss your requirements. Amplifier can work with partners to configure appropriate model bundles for specialized populations. --- # Guides: Use Cases URL: https://docs.amplifierhealth.com/guides/use-cases-all Use cases are pre-configured bundles of acoustic models selected for a specific clinical or wellness context. For how to use them, see [Use Cases Overview](/guides/use-cases). For model evidence tiers, see [Model Overview](/guides/models#evidence-tiers). Each bundle combines models at different evidence tiers; use the tier on each signal in API responses when interpreting results. Each bundle may also run additional associated models as contextual signals to improve accuracy. These contextual models are not exposed as primary signals but inform the analysis of the primary conditions listed for each bundle. ### Behavioral Health Screening **Use case ID:** `behavioral-health` A general-purpose behavioral health screening bundle for clinical and telehealth contexts. Covers depression, anxiety, acute stress, PTSD, ADHD, and fatigue as primary exposed signals. **Contextual models:** sleep disorders, elevated blood pressure. #### Common Scenarios - **Pre-visit screening:** Collect a short recording before an appointment (e.g. in a waiting room or via a patient app) and surface flagged signals to the care team. - **Between-visit check-ins:** Collect recordings between appointments and use `recommended_action` to identify when a follow-up or escalation is indicated. - **Population health monitoring:** Aggregate signals across a cohort to inform program outreach or resource allocation. #### Conditions | model\_id | Label | Evidence tier | | -------------- | ------------------------------------------------------------- | ------------- | | `acute-stress` | [Acute Stress & Nervousness](/guides/models-all#acute-stress) | `established` | | `adhd` | [ADHD](/guides/models-all#adhd) | `emerging` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `depression` | [Depression](/guides/models-all#depression) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | | `ptsd` | [PTSD](/guides/models-all#ptsd) | `emerging` | --- ### General Wellness & Readiness Monitoring **Use case ID:** `wellness` Built for employer-sponsored wellness programs and employee assistance platforms. Exposes fatigue, acute stress, dehydration, depression, anxiety, and elevated blood pressure as primary signals. **Contextual models:** sleep disorders. #### Common Scenarios - **Weekly pulse checks:** Collect brief recordings as part of a regular employee wellness check-in and aggregate population-level signals for HR dashboards. - **EAP referral:** Use `recommended_action` to route employees to an EAP counselor when signals reach `review` or `escalate`. - **Manager dashboards:** With appropriate consent, surface aggregated team-level trends (not individual scores) to people managers for wellness support. #### Conditions | model\_id | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `acute-stress` | [Acute Stress & Nervousness](/guides/models-all#acute-stress) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `depression` | [Depression](/guides/models-all#depression) | `established` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | --- ### Athletics & Occupational Health Screening **Use case ID:** `athletics-occupational` A performance health bundle for sports medicine, athletic training, and occupational health applications. Exposes traumatic brain injury, cognitive impairment, fatigue, dehydration, acute stress, anxiety, and elevated blood pressure as primary signals. **Contextual models:** sleep disorders. #### Common Scenarios - **Pre-competition screening:** Collect a short recording before training or competition and surface fatigue or cognitive signals for review by a performance coach or athletic trainer. - **Post-impact TBI screening:** For contact sports, collect recordings after potential head impacts; elevated TBI signals warrant immediate medical evaluation. - **Recovery assessments:** Collect recordings at scheduled check-ins during recovery and use fatigue and cognitive impairment signals to inform return-to-play discussions with a sports medicine professional. #### Conditions | model\_id | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `acute-stress` | [Acute Stress & Nervousness](/guides/models-all#acute-stress) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `cognitive-impairment` | [Cognitive Impairment](/guides/models-all#cognitive-impairment) | `established` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | | `traumatic-brain-injury` | [Traumatic Brain Injury](/guides/models-all#traumatic-brain-injury) | `established` | --- ### Cognitive Impairment Analysis **Use case ID:** `cognitive` Designed for cognitive health platforms, neurology practices, and brain health programs. Exposes cognitive impairment as the primary signal. #### Common Scenarios - **Cognitive screening:** Use as a pre-assessment tool before neuropsychological evaluation to triage referral urgency. - **Post-TBI screening:** Collect recordings at scheduled clinical assessments during TBI recovery and surface cognitive signals to the clinical team for review. - **ADHD management:** Monitor cognitive signals between clinical appointments to inform medication or care decisions. #### Conditions | model\_id | Label | Evidence tier | | ---------------------- | --------------------------------------------------------------- | ------------- | | `cognitive-impairment` | [Cognitive Impairment](/guides/models-all#cognitive-impairment) | `established` | --- ### Substance Use Screening **Use case ID:** `substance-use` Designed for recovery programs, behavioral health practices, and outpatient substance use treatment. Exposes alcohol use disorder, psychoactive substance use, depression, anxiety, acute stress, and fatigue as primary signals. **Contextual models:** elevated blood pressure. #### Common Scenarios - **Intake assessment:** Screen new participants for co-occurring disorders before treatment planning. - **Recovery check-ins:** Collect periodic recordings from enrolled participants and use `recommended_action` to prioritize counselor follow-ups. - **Relapse risk monitoring:** Elevated signals on alcohol use or psychoactive substance use identify when outreach or clinical follow-up is warranted. #### Conditions | model\_id | Label | Evidence tier | | --------------- | -------------------------------------------------------------- | ------------- | | `acute-stress` | [Acute Stress & Nervousness](/guides/models-all#acute-stress) | `established` | | `alcohol-use` | [Alcohol Use Disorder](/guides/models-all#alcohol-use) | `emerging` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `depression` | [Depression](/guides/models-all#depression) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | | `substance-use` | [Psychoactive Substance Use](/guides/models-all#substance-use) | `emerging` | --- ### Women's Health Screening **Use case ID:** `womens-health` A specialized bundle for women's health platforms, OB/GYN practices, and hormonal health programs. Exposes hyperandrogenism (PCOS), anemia, dehydration, depression, anxiety, fatigue, and elevated blood pressure as primary signals. Gender-stratified models (`depression-female`, `anxiety-female`) are used where applicable. #### Common Scenarios - **Symptom triage:** Surface hormonal and metabolic signals to a care coordinator for review alongside lab work. - **Check-ins during treatment:** Collect recordings at scheduled clinical touchpoints and surface hormonal signals for care team review. #### Conditions | model\_id | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `anemia` | [Anemia](/guides/models-all#anemia) | `investigational` | | `anxiety-female` | [Anxiety (Female)](/guides/models-all#anxiety-female) | `established` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `depression-female` | [Depression (Female)](/guides/models-all#depression-female) | `established` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | | `hyperandrogenism` | [Hyperandrogenism (PCOS)](/guides/models-all#hyperandrogenism) | `emerging` | --- ### Cardiometabolic Risk Screening **Use case ID:** `cardiometabolic` A bundle targeting metabolic and cardiometabolic conditions detectable through voice acoustics. Exposes elevated blood pressure, overweight & obesity, dehydration, anemia, dry mouth, and fatigue as primary signals. Combines models across evidence tiers; use tier labels when interpreting each signal. #### Common Scenarios - **Research intake:** Collect recordings during clinical assessments and correlate acoustic signals with lab values to evaluate biomarker validity for your population. - **Pilot monitoring:** Enrich wellness or clinical datasets with metabolic acoustic signals as a supplementary data stream alongside standard clinical measures. - **Exploratory screening:** Use as a preliminary flag for metabolic conditions in telemedicine or app-based contexts; follow up with clinical evaluation. #### Conditions | model\_id | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `anemia` | [Anemia](/guides/models-all#anemia) | `investigational` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `dry-mouth` | [Dry Mouth](/guides/models-all#dry-mouth) | `investigational` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `fatigue` | [Fatigue & Malaise](/guides/models-all#fatigue) | `established` | | `overweight-obesity` | [Overweight & Obesity](/guides/models-all#overweight-obesity) | `emerging` | --- ### Chronic Respiratory Issues Screening **Use case ID:** `respiratory` A bundle for respiratory conditions with detectable acoustic signatures. Exposes COPD and allergy as primary signals. Combines Established- and Emerging-tier models; use tier labels when interpreting each signal. **Contextual models:** fatigue, elevated blood pressure. #### Common Scenarios - **Telemedicine triage:** Collect a short recording at the start of a remote visit and surface respiratory signals to the clinician as supplementary context alongside a standard symptom review. - **Between-appointment check-ins:** Collect recordings between scheduled appointments and use COPD and allergy signals to identify when a clinical follow-up may be indicated. - **Research partnerships:** Use as a supplementary biomarker data stream in respiratory research, correlating acoustic signals with spirometry or clinical assessments. #### Conditions | model\_id | Label | Evidence tier | | --------- | ------------------------------------- | ------------- | | `allergy` | [Allergy](/guides/models-all#allergy) | `emerging` | | `copd` | [COPD](/guides/models-all#copd) | `established` | --- # Guides: Models — Overview URL: https://docs.amplifierhealth.com/guides/models Voice biomarker models are the acoustic analysis units that run when you submit audio to [`POST /v2/use-case/analyze`](/api-reference/use-case-analyze) or [`POST /v2/condition/analyze`](/api-reference/condition-analyze). Each model targets a specific condition or health state by measuring how that condition alters the mechanics of speech production — breath support, laryngeal control, articulation timing, and prosodic patterning. Every model carries an evidence tier that reflects the **depth of published academic and scientific research** behind that voice biomarker. Models are grouped into [use case bundles](/guides/use-cases) for common scenarios, or can be called individually via the [Condition API](/api-reference/condition-analyze) to build custom analysis logic. The acoustic indicators listed for each model in the full reference are interpretable speech features associated in the literature as vocal mechanisms linked to that condition. They are provided for informational purposes and represent the research basis for each model — not a description of how every individual recording is evaluated. Model outputs reflect a broad acoustic analysis; no single indicator solely determines a result. ## Evidence Tiers Use tiers to inform routing logic, display decisions, and clinical workflow design. The table below summarizes tier requirements and recommended deployment contexts. | Tier | Requirements | Recommended for | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `established` | Three or more peer-reviewed studies; findings replicated across two or more independent research groups; at least one prospective or large-scale validation | Workflows and products where you want the strongest published evidence base for the voice-based signal | | `emerging` | Published peer-reviewed evidence; replication present but not yet at clinical-validation scale; active research pipeline | Research partnerships, pilots, and validation studies where newer voice-specific literature is appropriate | | `investigational` | Acoustically plausible mechanism with supporting physiological rationale; no peer-reviewed voice-specific detection study published | Exploratory research, hypothesis generation, supplementary data streams | ## Speech Features Each recording is analyzed using thousands of acoustic speech features that capture how the voice and speech behave — spanning timing, energy, spectral content, and vocal quality. In addition to the condition scores, wellness metrics, and emotion signals returned per use case, the API exposes a subset of interpretable speech features for additional use and understanding of the analyzed speech signal. These features are provided to give transparency into the acoustic dimensions being measured; they represent a human-readable window into a much broader feature space driving the models. | Feature ID | Label | Unit | Description | | ---------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------- | | `pitch_mean` | Average Pitch | Hz | The average highness or lowness of the voice | | `pitch_variability` | Pitch Variability | ratio | How much the pitch fluctuates — monotone vs. expressive | | `loudness_mean` | Average Loudness | dB | The average equivalent sound level in decibels | | `loudness_variability` | Loudness Variability | ratio | How much the loudness changes over time — dynamic range | | `speech_rate` | Speech Rate | syllables/s | Speed of speech including pauses, in syllables per second | | `articulation_rate` | Articulation Rate | syllables/s | Speed of speech excluding pauses — how fast words are actually spoken | | `pause_duration_mean` | Average Pause Duration | s | How long the average silence or pause lasts between words | | `voice_jitter` | Voice Roughness (Jitter) | % | Micro-fluctuations in pitch. High values sound raspy, gravelly, or creaky | | `voice_shimmer` | Voice Shimmer | dB | Micro-fluctuations in volume. High shimmer can sound breathy or unstable | | `voice_clarity_hnr` | Voice Clarity (HNR) | dB | Harmonic-to-Noise Ratio. Higher values mean a clearer, less noisy voice | | `voice_breathiness` | Voice Breathiness | dB | A measure of breathiness. Higher values indicate a breathier voice | See [Models reference](/guides/models-all): [Established](/guides/models-all#established), [Emerging](/guides/models-all#emerging), and [Investigational](/guides/models-all#investigational). --- # Guides: Models URL: https://docs.amplifierhealth.com/guides/models-all Models below are listed by evidence tier. For how models run in the API, tier definitions, speech features, and the acoustic-indicators disclaimer, see [Model Overview](/guides/models). For bundle membership, see [Use Cases](/guides/use-cases) and [Use Cases reference](/guides/use-cases-all). The acoustic indicators listed for each model are interpretable speech features associated in the literature as vocal mechanisms linked to that condition. They are provided for informational purposes and represent the research basis (Established and Emerging models) or physiological rationale (Investigational models) for each model — not a description of how every individual recording is evaluated. Model outputs reflect a broad acoustic analysis; no single indicator solely determines a result. ## Established Established models have three or more peer-reviewed publications and replicated findings across independent research groups. This tier indicates the broadest published voice-based validation for those models — use it with clinical judgment in the context of each bundle’s model mix; see [Introduction](/guides/introduction) for the product disclaimer. ### Acute Stress & Nervousness `established` **Model ID:** `acute-stress` **Detects:** Acoustic indicators of stress and nervousness — elevated laryngeal tension, altered respiratory patterns, and shifts in vocal tract dynamics associated with sympathetic arousal. **Detection rationale:** Stress and nervousness activate the sympathetic nervous system and the hypothalamic-pituitary-adrenal (HPA) axis, producing physiological changes that increase laryngeal muscle tension, alter respiratory support for speech, and shift vocal tract resonance characteristics — all producing measurable acoustic changes. Stress is one of the most extensively studied states in speech biomarker research, with studies establishing both direct (HPA-axis) and indirect (autonomic) pathways to vocal change. **Acoustic indicators:** Elevated `pitch_variability` from heightened laryngeal muscle tension; increased `speech_rate` driven by sympathetic arousal; reduced `voice_clarity_hnr` (tighter, less clear vocal quality); changes in `loudness_mean` reflecting altered respiratory drive; formant frequency shifts from vocal tract tension. **Evidence:** Three or more peer-reviewed voice-based studies; meta-analyses with cortisol biomarker validation; findings replicated across two or more independent research groups. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening), [General Wellness](/guides/use-cases-all#general-wellness-readiness), [Substance Use Screening](/guides/use-cases-all#substance-use-screening), [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening) --- ### Anxiety `established` **Model ID:** `anxiety` **Detects:** Acoustic indicators of generalized and social anxiety — vocal fold irregularity under autonomic tension, altered breath support, and characteristic prosodic patterning. **Detection rationale:** Anxiety activates the sympathetic branch of the autonomic nervous system, producing shallow breathing, increased laryngeal muscle tension, and reduced respiratory support for phonation. These changes are observable even in neutral speech content, making voice a useful index of anxious arousal independent of what is being said. The indirect autonomic pathway between anxiety and vocal change is well characterized in psychophysiology literature. **Acoustic indicators:** Increased `voice_jitter` and `voice_shimmer` reflecting vocal fold irregularity under tension; altered `pitch_variability` from heightened laryngeal tension; changes in `pause_duration_mean` driven by respiratory disruption; `loudness_mean` shifts from altered breath support; spectral features reflecting vocal tract changes. **Evidence:** Three or more peer-reviewed studies; JMIR validation; replicated across independent groups. Indirect autonomic pathway validated. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening), [Substance Use Screening](/guides/use-cases-all#substance-use-screening), [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening), [Women's Health Screening](/guides/use-cases-all#womens-health-screening) --- ### Anxiety (Female) `established` **Model ID:** `anxiety-female` **Detects:** Acoustic indicators of generalized and social anxiety in female speakers — vocal fold irregularity under autonomic tension, altered breath support, and characteristic prosodic patterning, using a gender-stratified model trained on female speech. **Detection rationale:** The same autonomic pathway applies here as described in the `anxiety` model above. Gender-stratified modeling accounts for systematic differences in vocal tract anatomy, fundamental frequency range, and hormone-mediated acoustic baseline between male and female speakers, improving detection accuracy for female populations. **Acoustic indicators:** Increased `voice_jitter` and `voice_shimmer` reflecting vocal fold irregularity under tension; altered `pitch_variability` from heightened laryngeal tension; changes in `pause_duration_mean` driven by respiratory disruption; `loudness_mean` shifts from altered breath support. **Evidence:** Three or more peer-reviewed studies with female-stratified or female-majority validation; replicated across independent groups. Gender-stratified modeling validated in behavioral health populations. **Relevant use cases:** [Women's Health Screening](/guides/use-cases-all#womens-health-screening) --- ### Cognitive Impairment `established` **Model ID:** `cognitive-impairment` **Detects:** Acoustic and linguistic indicators of cognitive impairment — word-finding difficulty, disrupted speech planning, reduced verbal fluency, and altered speech timing. **Detection rationale:** Cognitive impairment affects the neural pathways responsible for speech production, verbal fluency, memory retrieval, and semantic processing. Degradation in these systems produces measurable changes in the temporal structure of speech: more frequent and longer pauses reflecting word-finding difficulty, reduced speech rate from slower cognitive processing, and changes in lexical diversity and semantic coherence that are detectable from short speech samples. **Acoustic indicators:** Increased `pause_duration_mean` and pause frequency reflecting word-finding difficulty; reduced `speech_rate` from slower cognitive processing; changes in `articulation_rate` from disrupted planning; linguistic features (lexical diversity, semantic coherence) contribute significantly alongside acoustic indicators. **Evidence:** Five or more peer-reviewed publications; ADReSS challenge benchmark; replicated across multiple independent research groups; prospective validation studies including large-cohort MCI detection from speech. **Relevant use cases:** [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening), [Cognitive Impairment Analysis](/guides/use-cases-all#cognitive-impairment-analysis) --- ### COPD `established` **Model ID:** `copd` **Detects:** Acoustic indicators of chronic obstructive pulmonary disease — impaired respiratory function and its downstream effects on breath support, phonation duration, and voice quality. **Detection rationale:** COPD reduces lung function and respiratory capacity, directly limiting the breath support available for speech. Reduced airflow produces shorter phrase lengths before breath replenishment, more frequent breath-driven pauses, and breathier vocal quality from incomplete glottal closure under low subglottal pressure. Air trapping and altered respiratory mechanics further affect the consistency of phonation across a breath group. **Acoustic indicators:** Reduced `voice_clarity_hnr` from breathier, less complete phonation; altered `loudness_mean` from reduced respiratory drive; changes in `articulation_rate` from shorter breath groups; increased `pause_duration_mean` for breath replenishment. **Evidence:** 15–20 dedicated voice-based COPD studies; JMIR validation; large-scale respiratory biomarker validation (1.5M voice data points, mean AUC 0.899); replicated across independent research groups. **Relevant use cases:** [Chronic Respiratory Issues Screening](/guides/use-cases-all#chronic-respiratory-disease-screening) --- ### Depression `established` **Model ID:** `depression` **Detects:** Acoustic indicators of major depressive disorder — psychomotor slowing, reduced vocal energy, flattened prosody, and altered speech timing observable even in neutral speech. **Detection rationale:** Depression affects the limbic system and psychomotor pathways, producing psychomotor retardation that directly slows speech rate, lowers vocal energy output, flattens pitch variability, and increases pause frequency. Emotional blunting reduces prosodic expressiveness, producing a characteristic monotone quality. These changes are detectable from neutral speech content and do not require discussion of emotional topics, making voice analysis well suited for low-barrier screening. **Acoustic indicators:** Reduced `loudness_mean` from psychomotor slowing; decreased `speech_rate` from cognitive and motor retardation; lowered `pitch_variability` from emotional blunting; increased `pause_duration_mean`; reduced `articulation_rate`. MFCCs and formant structure further differentiate depressed from healthy speech. **Evidence:** A primary Amplifier research domain; multiple Amplifier peer-reviewed publications; JMIR validation with 14,898 subjects; systematic reviews confirming acoustic correlates; replicated across independent research groups. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening), [Substance Use Screening](/guides/use-cases-all#substance-use-screening), [General Wellness](/guides/use-cases-all#general-wellness-readiness), [Women's Health Screening](/guides/use-cases-all#womens-health-screening) --- ### Depression (Female) `established` **Model ID:** `depression-female` **Detects:** Acoustic indicators of major depressive disorder in female speakers — psychomotor slowing, reduced vocal energy, flattened prosody, and altered speech timing, using a gender-stratified model trained on female speech. **Detection rationale:** The same limbic and psychomotor pathways apply here as described in the `depression` model above. Gender-stratified modeling accounts for systematic differences in vocal tract anatomy, fundamental frequency range, and hormonal influences on acoustic baseline, improving detection accuracy for female populations where hormonal factors (menstrual cycle, perimenopause, PCOS) can influence acoustic parameters. **Acoustic indicators:** Reduced `loudness_mean` from psychomotor slowing; decreased `speech_rate` from cognitive and motor retardation; lowered `pitch_variability` from emotional blunting; increased `pause_duration_mean`; reduced `articulation_rate`. **Evidence:** Multiple Amplifier peer-reviewed publications with female-stratified analysis; JMIR validation including female subgroup; replicated across independent research groups. **Relevant use cases:** [Women's Health Screening](/guides/use-cases-all#womens-health-screening) --- ### Elevated Blood Pressure `established` **Model ID:** `elevated-blood-pressure` **Detects:** Acoustic indicators of undiagnosed elevated blood pressure — reflecting autonomic dysregulation and vascular state changes that influence laryngeal function and vocal tract tension. **Detection rationale:** Elevated blood pressure alters autonomic balance, affecting laryngeal blood flow, vocal tract tissue perfusion, and sympathetic regulation of phonation. The pathway is indirect: sustained autonomic dysregulation associated with elevated blood pressure produces measurable vocal changes that correlate with BP state. Validated BP-vocal studies, including the Klick Labs study reporting 77–84% accuracy, establish the indirect ANS pathway as reproducible. This model surfaces undiagnosed or subclinical blood pressure elevation as a supplementary signal, not as a replacement for clinical measurement. **Acoustic indicators:** Subtle changes in `loudness_mean`, `pitch_variability`, and `voice_jitter` reflecting altered autonomic state; spectral features from vocal tract tension related to vascular and autonomic changes. **Evidence:** Multiple voice-based blood pressure studies including large-cohort validation; indirect autonomic and vascular pathway confirmed across independent groups. **Relevant use cases:** [General Wellness](/guides/use-cases-all#general-wellness-readiness), [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening), [Women's Health Screening](/guides/use-cases-all#womens-health-screening), [Cardiometabolic Risk Screening](/guides/use-cases-all#cardiometabolic-risk-screening) --- ### Fatigue & Malaise `established` **Model ID:** `fatigue` **Detects:** Acoustic indicators of physical fatigue, mental exhaustion, and malaise — reduced respiratory support, lower laryngeal muscle tone, and impaired cognitive resources for speech production. **Detection rationale:** Fatigue reduces respiratory support for phonation, decreases laryngeal muscle tone, and impairs the cognitive resources required for fluent language production. The result is measurably lower vocal energy, slower articulation, more frequent pauses, and reduced voice quality. The link between fatigue and vocal change is well established across high-stakes domains: aviation and air traffic control research validated fatigue-related vocal change as a safety-critical signal, and COVID-19 prospective research further confirmed the acoustic signature. **Acoustic indicators:** Reduced `loudness_mean` from lower respiratory drive; decreased `speech_rate` from reduced motor and cognitive capacity; reduced `voice_clarity_hnr` reflecting reduced phonation quality; increased `pause_duration_mean` from impaired sustained speech production. **Evidence:** Amplifier peer-reviewed publication plus four or more independent peer-reviewed studies; prospective COVID-19 validation; aviation and ATC validation studies; replicated across independent research groups. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening), [Substance Use Screening](/guides/use-cases-all#substance-use-screening), [General Wellness](/guides/use-cases-all#general-wellness-readiness), [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening), [Women's Health Screening](/guides/use-cases-all#womens-health-screening), [Cardiometabolic Risk](/guides/use-cases-all#cardiometabolic-risk-screening) --- ### Traumatic Brain Injury `established` **Model ID:** `traumatic-brain-injury` **Detects:** Acoustic indicators of TBI — dysarthria, slowed neural processing, and impaired respiratory-phonatory-articulatory coordination. **Detection rationale:** TBI affects motor cortex function, neural signal timing, and the coordination of the respiratory, phonatory, and articulatory systems. Dysarthria — imprecise articulation from motor control damage — is a common sequela. Slowed cognitive processing produces longer response latencies and altered speech timing. Because these changes are present in the acute and post-acute phases, voice provides a non-invasive signal for clinical assessment of TBI-related speech and cognitive indicators. **Acoustic indicators:** Increased `voice_jitter` and `voice_shimmer` from impaired laryngeal motor control; reduced `speech_rate` from slowed neural processing; increased `pause_duration_mean`; changes in articulation precision. Multi-session analysis enables recovery tracking. Structured verbal prompts (verbal fluency tasks, picture description) improve signal quality for this model. **Evidence:** 8–12 studies with AUC 0.65–0.82; Amplifier peer-reviewed publications; validated in athletic and occupational populations. **Relevant use cases:** [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening) --- ## Emerging Emerging models have published peer-reviewed evidence and an active research pipeline. They are suitable for research partnerships, pilot deployments, and validation studies where newer voice-based evidence is appropriate. The tier summarizes the research base, not a separate product entitlement — see [Introduction](/guides/introduction). ### ADHD `emerging` **Model ID:** `adhd` **Detects:** Acoustic indicators of ADHD — speech rate variability, articulation instability, and intensity dysregulation reflecting executive dysfunction and impaired speech motor planning. **Detection rationale:** ADHD affects executive function and dopaminergic circuits in the basal ganglia responsible for timing and motor control. These deficits manifest in speech as increased variability in speech rate, less consistent articulation, and irregular prosodic intensity. **Acoustic indicators:** `speech_rate` variability from impaired motor timing; articulation consistency changes; `loudness_mean` irregularity from intensity dysregulation; prosodic rhythm disruptions from executive control deficits. **Evidence:** 8–15 studies with AUC 0.60–0.75; Scientific Reports 2025 external validation (AUC 0.76); ADHD subtype heterogeneity and pediatric/adult differences noted. Active research pipeline. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening) --- ### Alcohol Use Disorder `emerging` **Model ID:** `alcohol-use` **Detects:** Acoustic indicators of alcohol use disorder — effects of alcohol on the fine motor coordination of the vocal system, including impaired articulation, reduced vocal clarity, and altered speech timing. **Detection rationale:** Alcohol depresses CNS function and reduces fine motor coordination, including the precise laryngeal and articulatory control required for clear speech. Sustained alcohol use produces measurable changes in articulation precision, vocal clarity, and speech timing that are detectable from voice recordings. Voice provides an objective, non-invasive signal complementary to self-report in recovery monitoring and clinical assessment contexts. **Acoustic indicators:** Increased `voice_jitter` and `voice_shimmer` from impaired laryngeal motor control; reduced `voice_clarity_hnr` reflecting reduced phonation clarity; altered `speech_rate`; changes in articulation precision and timing consistency. **Evidence:** Multiple voice-based studies on alcohol and vocal change; laboratory intoxication studies reporting high classification accuracy; active research pipeline for chronic use disorder detection. **Relevant use cases:** [Substance Use Screening](/guides/use-cases-all#substance-use-screening) --- ### Allergy `emerging` **Model ID:** `allergy` **Detects:** Acoustic indicators associated with allergic rhinitis — nasal coupling to the vocal tract and upper airway inflammation altering resonance and vocal quality. **Detection rationale:** Nasal congestion and upper airway inflammation alter the nasal coupling to the vocal tract, affecting nasality and resonance characteristics. Inflammatory changes in the upper airway may also influence laryngeal function. Voice quality changes in allergic rhinitis are documented in the clinical voice literature, and treatment of allergic rhinitis has been shown to improve acoustic voice parameters. **Acoustic indicators:** Altered nasal resonance and upper airway inflammation may affect spectral balance and vocal quality, reflected in `voice_clarity_hnr` and `pitch_variability`; nasal obstruction can change intensity distribution and resonance in ways that overlap with these features. **Evidence:** Voice quality changes in allergic rhinitis documented in clinical voice literature, including studies showing acoustic improvements following treatment; dedicated voice-based detection studies are limited. **Relevant use cases:** [Chronic Respiratory Issues Screening](/guides/use-cases-all#chronic-respiratory-disease-screening) --- ### Hyperandrogenism (PCOS) `emerging` **Model ID:** `hyperandrogenism` **Detects:** Acoustic indicators of hyperandrogenism and elevated androgen levels — direct hormonal effects on vocal fold tissue that alter fundamental frequency and vocal fold dynamics. **Detection rationale:** Androgens directly affect vocal fold tissue through the same mechanism responsible for voice deepening during male puberty: androgen exposure increases vocal fold mass and alters tissue composition. Elevated androgens in women with PCOS produce measurable vocal fold thickening and lowering of fundamental frequency. This is among the most direct hormonal-to-acoustic pathways in voice biomarker research, reducing reliance on indirect autonomic or behavioral mediators. **Acoustic indicators:** Reduced fundamental frequency (lower pitch) from increased vocal fold mass; changes in `pitch_variability` from altered vocal fold tension characteristics; `voice_jitter` and `voice_shimmer` changes reflecting modified vocal fold mass and tissue properties; possible shifts in formant frequencies from vocal tract changes. **Evidence:** Direct hormonal pathway; four studies in meta-analysis; 85% classification accuracy reported. Prospective clinical replication threshold for Established not yet met. **Relevant use cases:** [Women's Health Screening](/guides/use-cases-all#womens-health-screening) --- ### Overweight & Obesity `emerging` **Model ID:** `overweight-obesity` **Detects:** Acoustic indicators associated with overweight and obesity — vocal tract resonance changes, respiratory dynamics, and autonomic function patterns related to elevated BMI. **Detection rationale:** Elevated BMI affects upper airway anatomy and respiratory mechanics. Increased soft tissue mass in the pharyngeal region alters resonance characteristics of the vocal tract. Reduced respiratory capacity from elevated BMI affects breath support and the consistency of subglottal pressure during phonation. The BMI–acoustic relationship is documented in published research. **Acoustic indicators:** Changes in resonance characteristics (formant frequencies) from altered upper airway anatomy; modified `voice_clarity_hnr` from respiratory and phonatory changes; changes in `loudness_mean`; breathing pattern indicators. **Evidence:** Published research on voice-based BMI prediction including a 2024 JMIR AI study; BMI–acoustic association documented across multiple studies. Prospective clinical-scale validation ongoing. **Relevant use cases:** [Cardiometabolic Risk Screening](/guides/use-cases-all#cardiometabolic-risk-screening) --- ### PTSD `emerging` **Model ID:** `ptsd` **Detects:** Acoustic indicators of PTSD — pitch flatness, breathy vocal quality, reduced spectral energy, and prosodic disruption reflecting HPA axis dysregulation and dorsal vagal inhibition. **Detection rationale:** Chronic PTSD is associated with HPA axis flattening that reduces vocal effort and laryngeal tone. The dorsal vagal response characteristic of PTSD produces laryngeal inhibition and dampened prosodic expressiveness. Dissociation further reduces vocal dynamism. These effects produce a characteristic pattern of reduced pitch variability, breathier phonation, and flattened prosody that is detectable in neutral speech. **Acoustic indicators:** Reduced `pitch_variability` from HPA flattening; increased breathiness reflected in `voice_clarity_hnr`; reduced `loudness_mean` from laryngeal inhibition; altered prosodic rhythm. eGeMAPS features (F0, HNR, breathiness markers) are well-matched to this mechanism. **Evidence:** 10–15 studies; replicated across independent groups including prospective clinical cohorts. Anchor studies include Marmar 2019 and subsequent replications. **Relevant use cases:** [Behavioral Health Screening](/guides/use-cases-all#behavioral-health-screening) --- ### Psychoactive Substance Use `emerging` **Model ID:** `substance-use` **Detects:** Acoustic indicators of psychoactive substance use — CNS effects on vocal motor control, cognitive function, and emotional state that vary in character by substance class. **Detection rationale:** Psychoactive substances alter CNS function, affecting motor coordination, cognitive processing speed, and emotional regulation in ways that produce measurable changes in the voice. **Acoustic indicators:** Substance use effects on the CNS produce changes in vocal motor control and prosodic patterns, reflected in `voice_jitter`, `voice_shimmer`, `voice_clarity_hnr`, `speech_rate`, and `loudness_mean`. Multi-session analysis improves detection of use patterns over time. **Evidence:** Multiple peer-reviewed studies on voice as an index of drug effects across substance classes. Not yet validated at clinical prospective scale for Established. **Relevant use cases:** [Substance Use Screening](/guides/use-cases-all#substance-use-screening) --- ## Investigational Investigational models are based on acoustically plausible mechanisms with physiological rationale. Investigational models are suited for exploratory research and supplementary data streams. ### Anemia `investigational` **Model ID:** `anemia` **Detects:** Potential acoustic changes associated with anemia — reduced aerobic capacity and fatigue effects on vocal energy and effort. **Plausible mechanism:** Anemia reduces oxygen-carrying capacity, which can produce fatigue and reduced aerobic endurance. These secondary effects may influence vocal energy and phonatory effort in ways that overlap with the fatigue/malaise acoustic signature. The physiological pathway from oxygen deficit to vocal change is indirect; no voice-specific anemia detection study has been published, and the pathway to a distinct clinical detection model remains to be established through prospective research. **Potential Acoustic Indicators:** Fatigue and reduced aerobic capacity may lower vocal effort and sustained phonation, potentially reflected in reduced `loudness_mean`, increased `pause_duration_mean`, and changes in `speech_rate` or `voice_clarity_hnr` consistent with the fatigue acoustic signature. **Emerging Evidence:** Voice and speech as biomarkers for physiological state and fatigue are documented in the literature; acoustic features have been studied in relation to exercise intensity, frailty, and cardiovascular treatment response. The anemia–voice pathway is indirect and would be supported by prospective voice-specific studies in anemic populations. **Relevant use cases:** [Women's Health Screening](/guides/use-cases-all#womens-health-screening), [Cardiometabolic Risk Screening](/guides/use-cases-all#cardiometabolic-risk-screening) --- ### Dehydration `investigational` **Model ID:** `dehydration` **Detects:** Potential acoustic changes associated with dehydration and metabolic volume depletion — vocal fold hydration and mucosal wave properties. **Plausible mechanism:** Dehydration affects vocal fold hydration and the properties of the mucosal wave that governs phonation. Reduced systemic hydration decreases the viscosity-reducing properties of the mucus layer on the vocal folds, potentially increasing phonatory effort and altering voice quality in measurable ways. The relationship between oral dryness and voice change is documented in the clinical voice literature; standardized detection models based on voice alone have not yet been published. **Potential Acoustic Indicators:** Reduced vocal fold hydration and mucosal wave changes may increase perturbation and phonatory effort, potentially reflected in elevated `voice_jitter` and `voice_shimmer`, reduced `voice_clarity_hnr`, and changes in `loudness_mean` when sustaining phonation. **Emerging Evidence:** Vocal fold hydration and its effect on voice quality are well documented; systematic reviews report that hydration status affects jitter, shimmer, and noise-to-harmonics ratio, and that rehydration can improve these measures. Prospective voice-specific detection models for dehydration or volume depletion have not yet been established. **Relevant use cases:** [General Wellness](/guides/use-cases-all#general-wellness-readiness), [Athletics & Occupational](/guides/use-cases-all#athletics-occupational-health-screening), [Women's Health Screening](/guides/use-cases-all#womens-health-screening), [Cardiometabolic Risk Screening](/guides/use-cases-all#cardiometabolic-risk-screening) --- ### Dry Mouth `investigational` **Model ID:** `dry-mouth` **Detects:** Potential acoustic changes associated with dry mouth — reduced mucous membrane lubrication and its effects on vocal fold vibration quality. **Plausible mechanism:** Dry mouth reduces the mucous membrane lubrication that facilitates smooth vocal fold vibration. Increased phonatory friction from reduced oral and laryngeal moisture may alter voice quality, increase jitter and shimmer, and require greater phonatory effort. Acoustic effects of reduced oral moisture are documented in voice science research; no diagnostic detection model derived from voice alone has been published. **Potential Acoustic Indicators:** Reduced lubrication and increased phonatory friction may elevate perturbation and effort, potentially reflected in increased `voice_jitter` and `voice_shimmer`, reduced `voice_clarity_hnr`, and changes in `loudness_mean` when phonatory effort rises to compensate. **Emerging Evidence:** Acute xerostomia and hyposalivation have been associated with measurable changes in jitter and shimmer in voice research; scoping reviews note that much of the evidence concerns xerostomia secondary to other conditions (e.g., radiotherapy, Sjögren's). Prospective voice-specific studies isolating dry mouth would help establish the pathway. **Relevant use cases:** [Cardiometabolic Risk Screening](/guides/use-cases-all#cardiometabolic-risk-screening) --- # Guides: Production Checklist URL: https://docs.amplifierhealth.com/guides/production-checklist Use this checklist before deploying an Amplifier Health integration to production. ## Audio Quality - [ ] Tested recording setup with sample audio in the target environment; `audio_quality.issues` is empty in test runs - [ ] Production recording pipeline uses 16 kHz mono WAV or FLAC (recommended; API also accepts MP3 and 8 kHz minimum) - [ ] Single-speaker capture confirmed. - [ ] Microphone placement follows guidelines in [Audio Requirements](/guides/audio-requirements#recording-environment-guidelines) ## Credential Management - [ ] `X-Account-ID` and `X-API-Key` are stored as environment variables or in a secrets manager — not in source code - [ ] Credentials are excluded from all logging pipelines - [ ] Access to credentials is restricted to the services that need them ## Error Handling - [ ] `401` (authentication failure) surfaces an alert to the integration team - [ ] `402` (no credits) surfaces a clear message and triggers a support notification - [ ] `400` / `422` errors (`AUDIO_TOO_SHORT`, `AUDIO_TOO_LONG`, `UNSUPPORTED_FORMAT`, `AUDIO_POOR_QUALITY`) return a user-facing prompt to re-record - [ ] `429` (rate limit) handled with exponential backoff; `Retry-After` header is read - [ ] `500` errors retried with exponential backoff (max 5 retries) - [ ] See [Error Reference](/api-reference/error-reference) for the complete error code list and retry guidance ## Display Rules - [ ] `score` values are not displayed to patients or end users - [ ] `summary.description` is not surfaced in automated alerts or patient-facing output — shown only after review by qualified care staff - [ ] `level` and `label` are used as the display primitives in user-facing views - [ ] `flagged: true` is used to filter which signals appear in user-facing views - [ ] Display labels follow the recommended mapping in [Levels & Actions](/api-reference/levels-actions#patient-and-employee-facing-display-mapping) ## Use Case Selection - [ ] The `use_case` ID matches the clinical or wellness context of your user population - [ ] If your use case includes Emerging or Investigational models, appropriate clinical oversight is in place - [ ] Your team understands how per-model evidence tiers relate to your workflows (see [Use Cases](/guides/use-cases) and [Models](/api-reference/models)) - [ ] If serving multiple population contexts, separate requests use the most specific `use_case` ID for each group ## Compliance - [ ] Data handling and retention requirements reviewed with your legal and compliance team - [ ] For `wellness`: individual employee results have appropriate privacy controls; aggregated team-level signals (not individual scores) are used for dashboards and manager views ## Webhooks (if applicable) Use webhooks to receive results via push instead of polling — useful when audio is submitted from a client device and results need to be delivered to a separate backend service, or when you want a persistent delivery mechanism for audit logging. - [ ] Webhook URL is HTTPS - [ ] Signature verification is implemented before processing any webhook payload — see [Account](/api-reference/v2-account#webhook) - [ ] Idempotency check on `job_id` is implemented to handle webhook retries - [ ] Webhook receiver responds within 30 seconds to avoid delivery timeout ## Final Verification - [ ] End-to-end test completed with a real recording in the target environment - [ ] `audio_quality.issues` verified as empty in the production environment test - [ ] `escalate` workflow tested with a simulated high-signal result - [ ] `consider` workflow tested to verify signals are surfaced and routed appropriately - [ ] `recommended_action` of `none` or `inconclusive` cases handled gracefully (no alert, log only) --- # Guides: MCP Server URL: https://docs.amplifierhealth.com/guides/mcp The Amplifier Health MCP server lets you connect AI assistants and agents to the voice biomarker API without writing custom integration code. Connect via the Claude Desktop Custom Connector UI (Option A) or configure any MCP client directly with your credentials (Option B). ## Option A — Claude Desktop (Custom Connector) Claude Desktop supports adding remote MCP servers directly through its integrations settings — no config file editing required. 1. Open Claude Desktop and go to **Settings → Integrations**. 2. Click **Add custom integration** (the **+** button). 3. Enter the server URL: `https://mcp.amplifierhealth.com/mcp` 4. Add the following request headers: - `X-Account-ID` — your Account ID - `X-API-Key` — your API Key 5. Save and restart Claude Desktop. Your Account ID and API Key are available in the Amplifier console under **Settings → API Keys**. ## Option B — Direct connection (any MCP client) Use this path when you want to connect a specific client manually, including Claude Desktop via its config file, the OpenAI Agents SDK, or any other MCP-compatible host. The server details: - **URL:** `https://mcp.amplifierhealth.com/mcp` - **Transport:** Streamable HTTP (stateless) - **Auth:** `X-Account-ID` and `X-API-Key` request headers These are the same credentials used for the REST API. See [Credentials](#credentials) below for where to find them. ### Claude Desktop (manual config) Add the following to your `claude_desktop_config.json` file: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "amplifier-health": { "type": "streamable-http", "url": "https://mcp.amplifierhealth.com/mcp", "headers": { "X-Account-ID": "your-account-id", "X-API-Key": "your-api-key" } } } } ``` Restart Claude Desktop after saving the file. The Amplifier Health server will appear in the integrations list. ### OpenAI Use the `openai-agents` package to connect from a Python agent: #### Python ```python import os from agents import Agent from agents.mcp import MCPServerStreamableHTTP mcp_server = MCPServerStreamableHTTP( url="https://mcp.amplifierhealth.com/mcp", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) agent = Agent( name="Amplifier Agent", instructions="Use the Amplifier Health tools to analyze voice recordings.", mcp_servers=[mcp_server], ) ``` ### Other MCP clients Any MCP client that supports remote Streamable-HTTP servers can connect using the URL `https://mcp.amplifierhealth.com/mcp` with `X-Account-ID` and `X-API-Key` passed as request headers. Consult your client's documentation for where to specify the server URL and custom headers. ## Credentials Your Account ID and API Key are available in the Amplifier console under **Settings → API Keys**. - **Account ID** — identifies your account; safe to include in server-side configs. - **API Key** — treat this as a secret; store it in an environment variable or secrets manager rather than committing it to source control. > **Note:** > > Keep your API Key out of client-side or publicly accessible configurations. Use environment variables or a secrets manager to inject credentials at runtime. ## What you can do Connect your AI assistant or agent to the Amplifier Health voice biomarker API to submit audio for analysis and retrieve results, without writing custom API integration code. The MCP server exposes the same capabilities as the REST API — use it from within Claude, an OpenAI agent, or any other MCP-compatible host. For full details on available use cases, models, result fields, and audio requirements, see the [Guides](/guides/introduction) and [API Reference](/api-reference/overview). --- # Guides: Wellness Metrics — Overview URL: https://docs.amplifierhealth.com/guides/wellness Wellness metrics describe emotional and behavioral dimensions of the voice — such as mood, stress, and energy — and are returned when you submit audio for analysis. There are 28 wellness metrics in five groups — **Mood & Affect**, **Arousal & Tension**, **Energy & Fatigue**, **Cognitive & Behavioral**, and **Personality & Social** — plus 3 VAD (Valence, Arousal, Dominance) dimensions. Score Interpretation Each score is a position on a continuous spectrum. The anchor words on each metric card describe the states at each end — a score of 0.0 sits at the low anchor, 1.0 at the high anchor, and scores in between reflect intermediate states. Use numeric scores for analytics and tracking over time; in staff-facing UIs, show the metric label and signal level rather than the raw score. Metric Summary All metrics, grouped by domain. | Metric | Metric ID | Domain | Score ≈ 0 | Score ≈ 1 | | ----------------------------------------------------------------------- | ------------------------ | ---------------------- | ------------------ | ------------- | | [Emotional Valence](/guides/wellness-all#vad-valence) | `vad-valence` | VAD Dimensions | negative | positive | | [Arousal](/guides/wellness-all#vad-arousal) | `vad-arousal` | VAD Dimensions | calm | activated | | [Sense of Dominance](/guides/wellness-all#vad-dominance) | `vad-dominance` | VAD Dimensions | submissive | dominant | | [Anhedonia](/guides/wellness-all#anhedonia) | `anhedonia` | Mood & Affect | engaged | disengaged | | [Depressed Mood](/guides/wellness-all#depressed-mood) | `depressed-mood` | Mood & Affect | optimistic | depressed | | [Outlook](/guides/wellness-all#outlook) | `outlook` | Mood & Affect | optimistic | hopeless | | [Self-Criticism](/guides/wellness-all#self-criticism) | `self-criticism` | Mood & Affect | self-compassionate | self-critical | | [Anxious Mood](/guides/wellness-all#anxious-mood) | `anxious-mood` | Arousal & Tension | tranquil | panicked | | [Apprehension & Fear](/guides/wellness-all#apprehension-fear) | `apprehension-fear` | Arousal & Tension | safe | panicked | | [Overwhelm](/guides/wellness-all#overwhelm) | `overwhelm` | Arousal & Tension | unfazed | overwhelmed | | [Perceived Safety](/guides/wellness-all#perceived-safety) | `perceived-safety` | Arousal & Tension | secure | threatened | | [Restlessness & Agitation](/guides/wellness-all#restlessness-agitation) | `restlessness-agitation` | Arousal & Tension | relaxed | frantic | | [Tension](/guides/wellness-all#tension) | `tension` | Arousal & Tension | peaceful | wound up | | [Worry & Rumination](/guides/wellness-all#worry-rumination) | `worry-rumination` | Arousal & Tension | relaxed | worried | | [Burnout](/guides/wellness-all#burnout) | `burnout` | Energy & Fatigue | engaged | burned out | | [Energy Level](/guides/wellness-all#energy-level) | `energy-level` | Energy & Fatigue | exuberant | spiritless | | [Fatigue](/guides/wellness-all#fatigue) | `fatigue` | Energy & Fatigue | invigorated | exhausted | | [Motivation](/guides/wellness-all#motivation) | `motivation` | Energy & Fatigue | driven | unmotivated | | [Psychomotor State](/guides/wellness-all#psychomotor-state) | `psychomotor-state` | Energy & Fatigue | calm | frantic | | [Stress Resilience](/guides/wellness-all#stress-resilience) | `stress-resilience` | Energy & Fatigue | resilient | overwhelmed | | [Concentration](/guides/wellness-all#concentration) | `concentration` | Cognitive & Behavioral | focused | inattentive | | [Irritability](/guides/wellness-all#irritability) | `irritability` | Cognitive & Behavioral | peaceful | enraged | | [Self-Worth](/guides/wellness-all#self-worth) | `self-worth` | Cognitive & Behavioral | confident | insecure | | [Sense of Control](/guides/wellness-all#sense-of-control) | `sense-of-control` | Cognitive & Behavioral | empowered | helpless | | [Sleep Disturbance](/guides/wellness-all#sleep-disturbance) | `sleep-disturbance` | Cognitive & Behavioral | rested | sluggish | | [Agreeableness](/guides/wellness-all#agreeableness) | `agreeableness` | Personality & Social | pleasant | irritable | | [Conscientiousness](/guides/wellness-all#conscientiousness) | `conscientiousness` | Personality & Social | disciplined | irresponsible | | [Extraversion](/guides/wellness-all#extraversion) | `extraversion` | Personality & Social | introverted | extraverted | | [Loneliness](/guides/wellness-all#loneliness) | `loneliness` | Personality & Social | connected | isolated | | [Neuroticism](/guides/wellness-all#neuroticism) | `neuroticism` | Personality & Social | unflappable | irritable | | [Openness](/guides/wellness-all#openness) | `openness` | Personality & Social | inspired | uninspired | For details on each metric, see [Wellness Metrics reference](/guides/wellness-all): [VAD Dimensions](/guides/wellness-all#vad-dimensions), [Mood & Affect](/guides/wellness-all#mood--affect), [Arousal & Tension](/guides/wellness-all#arousal--tension), [Energy & Fatigue](/guides/wellness-all#energy--fatigue), [Cognitive & Behavioral](/guides/wellness-all#cognitive--behavioral), and [Personality & Social](/guides/wellness-all#personality--social). --- # Guides: Wellness Metrics URL: https://docs.amplifierhealth.com/guides/wellness-all Wellness metrics describe emotional and behavioral dimensions of the voice. For VAD framework context, see [Wellness Overview](/guides/wellness). For what high and low scores mean, see [Score Interpretation](/guides/wellness#score-interpretation). VAD Dimensions These three dimensions describe the underlying emotional axes of the voice signal. They can be used alongside wellness metrics to understand the emotional texture of a recording. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | ------------------ | --------------- | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | Emotional Valence | `vad-valence` | negative | positive | The positive or negative quality of emotional tone in the voice signal. | | Arousal | `vad-arousal` | calm | activated | The level of activation or energy present in the voice signal — from calm and withdrawn to alert and agitated. | | Sense of Dominance | `vad-dominance` | submissive | dominant | The degree of control or agency expressed in the voice — from submissive or helpless to confident and assertive. | ## Mood & Affect Mood and affect metrics capture the emotional tone, hedonic state, and self-evaluative dimensions of the voice signal. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | -------------- | ---------------- | ------------------ | ------------- | ------------------------------------------------------------------------------- | | Anhedonia | `anhedonia` | engaged | disengaged | Reduced capacity for pleasure or positive emotional engagement. | | Depressed Mood | `depressed-mood` | optimistic | depressed | Persistent low mood state characterized by slower, lower-energy vocal delivery. | | Outlook | `outlook` | optimistic | hopeless | The tendency toward positive or negative expectation and appraisal. | | Self-Criticism | `self-criticism` | self-compassionate | self-critical | The tendency toward self-judgment and harsh self-evaluation. | ## Arousal & Tension Arousal and tension metrics capture states of elevated activation, physiological tension, and anticipatory or ruminative distress. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | ------------------------ | ------------------------ | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | Anxious Mood | `anxious-mood` | tranquil | panicked | Elevated physiological and psychological activation with a sense of unease. | | Apprehension & Fear | `apprehension-fear` | safe | panicked | Anticipatory dread or fearfulness, characterized by increased vocal tension and reduced fluency. | | Overwhelm | `overwhelm` | unfazed | overwhelmed | Cognitive and emotional overload with intrusive worry, reflected in accelerated or irregular speech. | | Perceived Safety | `perceived-safety` | secure | threatened | The felt sense of threat or safety in the environment. | | Restlessness & Agitation | `restlessness-agitation` | relaxed | frantic | Inner restlessness or physical agitation, characterized by fast speech, high energy, and erratic prosody. | | Tension | `tension` | peaceful | wound up | Persistent muscular and psychological tension preventing relaxation, reflected in tight voice quality and elevated pitch. | | Worry & Rumination | `worry-rumination` | relaxed | worried | Repetitive negative thought patterns, reflected in slower, effortful delivery and reduced prosodic range. | ## Energy & Fatigue Energy and fatigue metrics capture the voice's expression of vitality, exhaustion, and adaptive capacity. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | ----------------- | ------------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Burnout | `burnout` | engaged | burned out | Occupational exhaustion ranging from full engagement to burned-out depletion. | | Energy Level | `energy-level` | exuberant | spiritless | Overall vitality and physical energy as expressed in the voice. | | Fatigue | `fatigue` | invigorated | exhausted | Physical or mental tiredness, characterized by reduced speech rate, lower vocal energy, and flattened pitch. | | Motivation | `motivation` | driven | unmotivated | Goal-directed drive and initiative as expressed in the voice. | | Psychomotor State | `psychomotor-state` | calm | frantic | Changes in motor and cognitive speed, as seen in depression (retardation) or mania (acceleration), detected via speech rate and pause patterns. | | Stress Resilience | `stress-resilience` | resilient | overwhelmed | Experienced stress load relative to adaptive capacity. | ## Cognitive & Behavioral Cognitive and behavioral metrics capture the voice's expression of attentional capacity, goal-directedness, emotional reactivity, and the behavioral effects of disrupted sleep. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | ----------------- | ------------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Concentration | `concentration` | focused | inattentive | Capacity to sustain focused attention. A high score reflects difficulty concentrating; a low score reflects focused, attentive delivery. | | Irritability | `irritability` | peaceful | enraged | Short-fused emotional reactivity, characterized by increased vocal intensity and sharp prosodic contours. | | Self-Worth | `self-worth` | confident | insecure | Perceived sense of one's own value. A high score reflects insecurity; a low score reflects confident, assured delivery. | | Sense of Control | `sense-of-control` | empowered | helpless | Perceived control over outcomes. A high score reflects helplessness; a low score reflects agency and empowerment. | | Sleep Disturbance | `sleep-disturbance` | rested | sluggish | Disrupted sleep patterns affecting voice production, overlapping with fatigue markers such as slower rate and reduced voice clarity. | ## Personality & Social Personality and social metrics capture stable trait-level and social orientation dimensions of the voice signal. | Metric | Metric ID | Score ≈ 0 | Score ≈ 1 | Description | | ----------------- | ------------------- | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agreeableness | `agreeableness` | pleasant | irritable | Cooperative, warm, and accommodating interpersonal orientation. A high score reflects irritability or antagonism; a low score reflects pleasant, agreeable delivery. | | Conscientiousness | `conscientiousness` | disciplined | irresponsible | Organized, disciplined, and goal-directed behavior. A high score reflects disorganization; a low score reflects disciplined, methodical delivery. | | Extraversion | `extraversion` | introverted | extraverted | Outward social engagement, expressiveness, and energy. A high score reflects extraverted vocal dynamism; a low score reflects introverted, reserved delivery. | | Loneliness | `loneliness` | connected | isolated | The felt sense of social isolation or belonging. A high score reflects loneliness; a low score reflects connection and belonging. | | Neuroticism | `neuroticism` | unflappable | irritable | Emotional instability and tendency toward negative affect, characterized by high pitch variability and irregular prosody. | | Openness | `openness` | inspired | uninspired | Curiosity, creativity, and openness to new experiences. A high score reflects low openness; a low score reflects an open, exploratory vocal style. | ---