--- # 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 | | `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, MP3, or M4A. | 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: 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: Model API URL: https://docs.amplifierhealth.com/api-reference/models-api Models are named multi-sign analysis packages — each model bundles a fixed set of signs and runs them against submitted audio in a single call. Submit audio via `POST /v2/models/{model_name}/analyze` to receive a multi-sign result: `summary`, `signals[]`, `audio_quality`, and `extended_metrics`. Use the Model API when you want a pre-defined multi-sign result without composing individual sign calls. For individual sign analysis, see [Sign API](/api-reference/signs-api). --- ## GET /v2/models ### GET /v2/models Return the list of all available named models and the signs each one includes. ### Response | Field | Type | Description | | -------- | ----- | ---------------------- | | `models` | array | List of model objects. | Each object in `models`: | Field | Type | Description | | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Named model identifier (e.g. `"apex"`). Use as the `model_name` path parameter on detail and analyze endpoints. | | `signs` | string\[] | Signs included in this model. Some entries are model-internal and are not available via `POST /v2/signs/{sign_name}/analyze` — see [Sign API — model-internal signs](/api-reference/signs-api#model-internal-signs). | ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/models" \ -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/models", { 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/models", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Example response ```json { "models": [ { "name": "apex", "signs": ["head-impact","cognitive-load","fatigue","dehydration","stress","anxiety","cardiovascular-strain"] }, { "name": "aria", "signs": ["elevated-androgens","iron-deficiency","dehydration","mood-disruption","fatigue","anxiety","elevated-blood-pressure"] }, { "name": "breath", "signs": ["airway-obstruction-pattern","allergy"] }, { "name": "clarity", "signs": ["cognitive-impairment"] }, { "name": "harbor", "signs": ["alcohol-use-pattern","substance-use-pattern","emotional-destabilization","anxiety","stress","fatigue"] }, { "name": "haven", "signs": ["mood-disruption","anxiety","stress","hypervigilance","attention-dysregulation","fatigue"] }, { "name": "pulse", "signs": ["mood-disruption","anxiety","stress","fatigue","dehydration","elevated-blood-pressure"] }, { "name": "tide", "signs": ["elevated-blood-pressure","metabolic-load","dehydration","iron-deficiency","fatigue","dry-mouth"] } ] } ``` ### Errors For authentication errors (401) and other codes, see [Error Reference](/api-reference/error-reference). --- ## GET /v2/models/{model\_name} ### GET /v2/models/{model\_name} Return the details for a single named model, including the signs it includes. ### Path Parameters | Parameter | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------- | | `model_name` | string | The name of the model to retrieve. See [Valid model names](#valid-model-names) below. | ### Response | Field | Type | Description | | ------- | --------- | ----------------------------- | | `name` | string | Named model identifier. | | `signs` | string\[] | Signs included in this model. | ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/models/apex" \ -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/models/apex", { 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/models/apex", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Example response ```json { "name": "apex", "signs": ["head-impact","cognitive-load","fatigue","dehydration","stress","anxiety","cardiovascular-strain"] } ``` ### Errors | HTTP | Code | Condition | | ---- | ----------- | ------------------------------------------------------------------------------------------------------- | | 404 | `NOT_FOUND` | `model_name` is not a recognized model. Check the name against [Valid model names](#valid-model-names). | For other codes, see [Error Reference](/api-reference/error-reference). --- ## POST /v2/models/{model\_name}/analyze ### POST /v2/models/{model\_name}/analyze Submit audio for analysis using a named model. Returns a job object immediately; poll GET /v2/jobs/{job\_id} or use a webhook for the completed result. Requests use `Content-Type: multipart/form-data`. The job object is returned immediately with `status: "queued"` and `result: null`. When analysis completes, the `result` contains multi-sign output: a `summary` wrapper, a `signals[]` array (one entry per sign in the bundle), `audio_quality`, and `extended_metrics`. ### Path Parameters | Parameter | Description | | ------------ | -------------------------------------------------------------------- | | `model_name` | The named model to run. See [Valid model names](#valid-model-names). | ### Request Body Requests use `Content-Type: multipart/form-data`. | Field | Type | Required | Description | | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio` | file | Yes | Audio file (WAV, FLAC, MP3, or M4A). Max 32 MB per file. For longer recordings, MP3, M4A, or FLAC usually keep the file under the limit. See [Audio Requirements](/guides/audio-requirements#file-size). | | `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. | ### Valid model names | Model | Signs included | Sign count | | --------- | ------------------------------------------------------------------------------------------------------------ | ---------- | | `apex` | head-impact, cognitive-load, fatigue, dehydration, stress, anxiety, cardiovascular-strain | 7 | | `aria` | elevated-androgens, iron-deficiency, dehydration, mood-disruption, fatigue, anxiety, elevated-blood-pressure | 7 | | `breath` | airway-obstruction-pattern, allergy | 2 | | `clarity` | cognitive-impairment | 1 | | `harbor` | alcohol-use-pattern, substance-use-pattern, emotional-destabilization, anxiety, stress, fatigue | 6 | | `haven` | mood-disruption, anxiety, stress, hypervigilance, attention-dysregulation, fatigue | 6 | | `pulse` | mood-disruption, anxiety, stress, fatigue, dehydration, elevated-blood-pressure | 6 | | `tide` | elevated-blood-pressure, metabolic-load, dehydration, iron-deficiency, fatigue, dry-mouth | 6 | Some signs listed above (e.g. `cognitive-load`, `cardiovascular-strain`, `emotional-destabilization`, `dry-mouth`) are model-internal and are not available as standalone targets via `POST /v2/signs/{sign_name}/analyze`. They appear in the model's sign list but are not returned by `GET /v2/signs`. See [Sign API — model-internal signs](/api-reference/signs-api#model-internal-signs). ## Code Examples ### Submit #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/models/apex/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/models/apex/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/models/apex/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")}, ) job_id = submit_response.json()["job_id"] ``` ### Example response The API returns immediately with the job object. `status` is `queued` and `result` is `null` until processing completes: ```json { "job_id": "7c3d91fa-b04e-4a18-832d-dc4f6e2a9b5c", "status": "queued", "created_at": "2026-05-22T10:30: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": "model", "api_version": "v2", "model_name": "apex" } ``` ### Poll job #### cURL ```bash curl https://api.amplifierhealth.com/v2/jobs/7c3d91fa-b04e-4a18-832d-dc4f6e2a9b5c \ -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. When `status` is `done`, the `result` contains `summary` + `signals[]` + `audio_quality` + `extended_metrics` — see [Response Schema — Model Response](/api-reference/schema#model-response). ### Errors | HTTP | Code | Condition | | ---- | -------------------- | ------------------------------------------------------------------------------------------------------- | | 404 | `NOT_FOUND` | `model_name` is not a recognized model. Check the name against [Valid model names](#valid-model-names). | | 400 | `AUDIO_TOO_SHORT` | Recording is under 15 seconds. | | 400 | `AUDIO_TOO_LONG` | Recording exceeds 20 minutes. | | 400 | `UNSUPPORTED_FORMAT` | Audio format is not WAV, FLAC, MP3, or M4A. | | 422 | `AUDIO_POOR_QUALITY` | Recording conditions below the threshold used for analysis. | 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 codes and retry guidance, see [Error Reference](/api-reference/error-reference). --- # API Reference: Model IDs Reference URL: https://docs.amplifierhealth.com/api-reference/models All signs 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 sign IDs and their evidence tiers. For full descriptions and per-bundle sign lists, see [Models reference](/guides/models). For the **as-is** disclaimer and how tiers fit together, see [Introduction](/guides/introduction). ## Available Signs Each `name` in the table appears in the `signals` array of a model job result. Most are also available as the `signal` object of a sign job result — except the three model-internal signs noted below. For example: ```json {"name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true} ``` See [Response Schema](/api-reference/schema#signals-array) for the full `signals` field reference. | `name` | Label | Tier | | ---------------------------- | -------------------------- | ----------------- | | `airway-obstruction-pattern` | Airway Obstruction Pattern | `established` | | `alcohol-use-pattern` | Alcohol Use Pattern | `emerging` | | `allergy` | Allergy | `emerging` | | `anxiety` | Anxiety | `established` | | `attention-dysregulation` | Attention Dysregulation | `emerging` | | `cardiovascular-strain` | Cardiovascular Strain | `established` | | `cognitive-impairment` | Cognitive Impairment | `established` | | `cognitive-load` | Cognitive Load | `established` | | `dehydration` | Dehydration | `investigational` | | `dry-mouth` | Dry Mouth | `investigational` | | `elevated-androgens` | Elevated Androgens | `emerging` | | `elevated-blood-pressure` | Elevated Blood Pressure | `established` | | `emotional-destabilization` | Emotional Destabilization | `established` | | `fatigue` | Fatigue | `established` | | `head-impact` | Head Impact | `established` | | `hypervigilance` | Hypervigilance | `emerging` | | `iron-deficiency` | Iron Deficiency | `investigational` | | `metabolic-load` | Metabolic Load | `emerging` | | `mood-disruption` | Mood Disruption | `established` | | `stress` | Stress | `established` | | `substance-use-pattern` | Substance Use Pattern | `emerging` | > **Note:** > > `cardiovascular-strain`, `cognitive-load`, `dry-mouth`, and `emotional-destabilization` are **model-internal** signs: they appear in named-model results but are not available for standalone analysis via `POST /v2/signs/{sign_name}/analyze`, and are not returned by `GET /v2/signs`. To get these signals, use the named model that includes them. See [Sign API — model-internal signs](/api-reference/signs-api#model-internal-signs). ## Named Model Sign Composition Each named model bundles a specific set of signs. The `name` values returned in `signals[]` correspond to the signs in the bundle for that model. | Model | Signs | | --------- | -------------------------------------------------------------------------------------------------------------------------- | | `apex` | `head-impact`, `cognitive-load`, `fatigue`, `dehydration`, `stress`, `anxiety`, `cardiovascular-strain` | | `aria` | `elevated-androgens`, `iron-deficiency`, `dehydration`, `mood-disruption`, `fatigue`, `anxiety`, `elevated-blood-pressure` | | `breath` | `airway-obstruction-pattern`, `allergy` | | `clarity` | `cognitive-impairment` | | `harbor` | `alcohol-use-pattern`, `substance-use-pattern`, `emotional-destabilization`, `anxiety`, `stress`, `fatigue` | | `haven` | `mood-disruption`, `anxiety`, `stress`, `hypervigilance`, `attention-dysregulation`, `fatigue` | | `pulse` | `mood-disruption`, `anxiety`, `stress`, `fatigue`, `dehydration`, `elevated-blood-pressure` | | `tide` | `elevated-blood-pressure`, `metabolic-load`, `dehydration`, `iron-deficiency`, `fatigue`, `dry-mouth` | Discover a model's current sign composition at runtime with [`GET /v2/models/{model_name}`](/api-reference/models-api). --- # 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 interfaces: - **Model API** (`POST /v2/models/{model_name}/analyze`) — Submit audio against a named multi-sign model bundle. Returns a `summary`, `signals[]` array, and `audio_quality`. See [Model API](/api-reference/models-api). - **Sign API** (`POST /v2/signs/{sign_name}/analyze`) — Analyze a single sign. Returns a single `signal` object and `audio_quality`. See [Sign API](/api-reference/signs-api). 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 **API Keys** — enter a label in the **New Key** field and click **Create key**. 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, M4A | 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/models/{model_name}/analyze`, `POST /v2/signs/{sign_name}/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 <sales@amplifierhealth.com>. --- # API Reference: Quick Start URL: https://docs.amplifierhealth.com/api-reference/quick-start This example covers the complete request-response cycle using the `apex` model. All models follow the same structure — only the model name in the URL and the `signals` array contents differ. ## Step 1 — Submit audio #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/models/apex/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/models/apex/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/models/apex/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")}, ) job_id = submit_response.json()["job_id"] ``` The model name is in the URL path — no additional form field is needed. See [Model API](/api-reference/models-api) for the full list of valid model names and optional fields (diarization, per-request webhooks). Requests use `Content-Type: multipart/form-data`. The `audio` field accepts a binary file upload. 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 `queued` and `result` is `null` until processing completes: ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "queued", "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": "model", "api_version": "v2", "model_name": "apex" } ``` ## 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 Model job result with elevated stress and anxiety 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": "model", "api_version": "v2", "model_name": "apex", "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": ["stress", "anxiety", "fatigue"], "description": { "summary": "Voice patterns suggest elevated indicators for stress 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": [ {"name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true}, {"name": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true}, {"name": "fatigue", "label": "Fatigue", "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: `stress`, `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 model bundle. --- # 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: `queued` \| `running` \| `done` \| `failed` \| `timed-out`. | | `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 queued/running, succeeded (`done`), or ended without a result (`failed` or `timed-out`) — these outcomes are expressed in the body, not only via HTTP error codes (see [Job Status: Failed or Timed-out](#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 a v2 analyze endpoint (`POST /v2/models/{model_name}/analyze` or `POST /v2/signs/{sign_name}/analyze`). | ### Response | Field | Type | Description | | ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `job_id` | string | Unique job identifier. | | `status` | string | Job status: `queued` \| `running` \| `done` \| `failed` \| `timed-out`. | | `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 | `"model"` \| `"sign"`. | | `api_version` | string | `"v2"`. | | `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` or `timed-out`, typically `null`. [Job Status: Failed or Timed-out](/api-reference/schema#job-status-failed); [Result Object](#result-object) below. | Each response also includes exactly one **discriminator field**, selected by `job_type`: `model` jobs include `model_name`, and `sign` jobs include `sign_name`. The other discriminator field is omitted. See [Response Schema — Discriminator fields by `job_type`](/api-reference/schema#job-response). ### Job Status: Failed or Timed-out `status: "failed"` or `status: "timed-out"` means processing ended without a result. For a valid `job_id`, the API returns `200 OK` with the job object — these outcomes are expressed in `status`, not only via HTTP codes. `result` is usually `null`; poll until `done`, `failed`, or `timed-out`, then branch. Full contract: [Response Schema — Job Status: Failed or Timed-out](/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": "model", "api_version": "v2", "model_name": "apex", "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 analyze response and verify your `X-Account-ID` header. --- # API Reference: Response Schema URL: https://docs.amplifierhealth.com/api-reference/schema The Amplifier API produces two response shapes: - **Model jobs** (`POST /v2/models/{model_name}/analyze`) — multi-sign result with a `summary` wrapper, a `signals[]` array, `audio_quality`, and `extended_metrics`. See [Model API](/api-reference/models-api). - **Sign jobs** (`POST /v2/signs/{sign_name}/analyze`) — single-signal result with a singular `signal` object and `audio_quality`. See [Sign API](/api-reference/signs-api). Both endpoints return 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**. - **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). --- ## Model Response ### Submit Response `POST /v2/models/{model_name}/analyze` returns the job object immediately. `status` is `queued` 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: `queued` 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 | `"model"` for model jobs. | | `api_version` | string | `"v2"`. | | `model_name` | string | Named model (e.g. `"apex"`). Included for model jobs. | ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "queued", "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": "model", "api_version": "v2", "model_name": "apex" } ``` ### 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: `queued` \| `running` \| `done` \| `failed` \| `timed-out`. | | `created_at` | string | ISO 8601; fractional seconds and timezone designator vary. See [Timestamps](#timestamps). | | `completed_at` | string or null | ISO 8601; null while `queued`/`running`. Semantics for `done` vs `failed`/`timed-out`: [Timestamps](#timestamps), [Job Status: Failed](#job-status-failed). | | `job_type` | string | `"model"` \| `"sign"`. | | `api_version` | string | `"v2"`. | | `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` or `timed-out`, typically `null`. See [Job Status: Failed or Timed-out](#job-status-failed). | Each response includes exactly one **discriminator field**, selected by `job_type`: | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------- | | `model_name` | string | Named model (e.g. `"apex"`). Included for `model` jobs. | | `sign_name` | string | Named sign (e.g. `"stress"`). Included for `sign` jobs. | > **Discriminator fields by `job_type`.** A V2 job response includes only the discriminator field that matches its `job_type`: `model` jobs include `model_name`; `sign` jobs include `sign_name`. The other discriminator field is omitted. The shared fields above are always present (the nullable ones — `completed_at`, `result`, `audio_sample_rate` — may be `null`). `result` contains: | Field | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------------------------- | | `summary` | object | Aggregated result across all signals. | | `signals` | array | Per-sign results, one entry per sign in the model bundle. | | `audio_quality` | object | Recording quality scores and detected issue codes. | | `extended_metrics` | array | Per-metric wellness scores for the model. 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", "job_type": "model", "api_version": "v2", "model_name": "apex", "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 or Timed-out When `status` is `"failed"` or `"timed-out"`, processing ended without a result. For a valid `job_id` on your account, `GET /v2/jobs/{job_id}` still returns `200 OK` with a job object — these outcomes are expressed in `status`, not via a 4xx HTTP code. Poll until `status` is `done`, `failed`, or `timed-out`, 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. - **`timed-out`:** processing did not complete in time; `result` and `completed_at` are `null`. Submit a new job to retry. `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 `name` values by score, descending (matches `signals[].name`). | | `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": ["stress", "anxiety", "fatigue"], "description": { "summary": "Voice patterns suggest elevated indicators for stress and anxiety...", "vocal_features": [ ... ] } } ``` ### signals Array `signals` contains one entry per sign in the model bundle. | Field | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | External sign name. | | `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 [ {"name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true}, {"name": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true}, {"name": "fatigue", "label": "Fatigue", "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 model. For metric definitions, see [Wellness](/guides/wellness). | 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" } ] ``` --- ## Sign Response `POST /v2/signs/{sign_name}/analyze` returns the same **job object** envelope (see [Job Response](#job-response) above), but with `job_type: "sign"`, the `sign_name` discriminator field, and the **`result` interior is structurally different**. (`model_name` is omitted for sign jobs — see [Discriminator fields by `job_type`](#job-response).) The `result` object uses a singular `signal` object instead of `summary` + `signals[]`: ```json { "job_id": "4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f", "status": "done", "job_type": "sign", "api_version": "v2", "sign_name": "stress", "result": { "signal": { ... }, "audio_quality": { ... }, "extended_metrics": [ ... ] } } ``` ### signal Object `signal` is a single object (not an array) containing the full result for the requested sign. Unlike the model response — where `description` and `recommended_action` live on the `summary` wrapper — the sign response places them directly on `signal`. | Field | Type | Description | | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | External sign name. | | `label` | string | Human-readable sign 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 sign: `none` \| `monitor` \| `consider` \| `review` \| `escalate` \| `inconclusive`. | | `description` | object | Narrative `summary` plus `vocal_features`. Same schema as the [description Object](#description-object). | `recommended_action` is derived from this sign'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 { "name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true, "recommended_action": "escalate", "description": { "summary": "Voice patterns suggest elevated stress indicators...", "vocal_features": [ { "feature": "speech_rate", "label": "Speech Rate", "value": 3.2, "unit": "syllables/s", "value_interpretation": "reduced" } ] } } ``` Use `job_type` to select the correct result parser: | `job_type` | Result shape | | ---------- | -------------------------------------- | | `model` | `summary` + `signals[]` (model bundle) | | `sign` | singular `signal` object | For display rules, see [Interpreting Results — Display Guidelines](/guides/interpreting-results#display-guidelines). --- # API Reference: Sign API URL: https://docs.amplifierhealth.com/api-reference/signs-api Signs are individual biomarker signals detected from voice. Each sign represents a specific health dimension. Use `GET /v2/signs` to discover available signs, `GET /v2/signs/{sign_name}` to get details on one, and `POST /v2/signs/{sign_name}/analyze` to analyze a single sign against submitted audio. For pre-built multi-sign bundles, use [Model API](/api-reference/models-api). --- ## GET /v2/signs ### GET /v2/signs Return the list of all signs available for individual analysis. ### Response | Field | Type | Description | | ------- | ----- | --------------------- | | `signs` | array | List of sign objects. | Each object in `signs`: | Field | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------------- | | `name` | string | Sign identifier. Use as the `sign_name` path parameter on detail and analyze endpoints. | | `label` | string | Human-readable sign name for display. | ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/signs" \ -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/signs", { 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/signs", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Example response ```json { "signs": [ { "name": "airway-obstruction-pattern", "label": "Airway Obstruction Pattern" }, { "name": "alcohol-use-pattern", "label": "Alcohol Use Pattern" }, { "name": "allergy", "label": "Allergy" }, { "name": "anxiety", "label": "Anxiety" }, { "name": "attention-dysregulation", "label": "Attention Dysregulation" }, { "name": "cognitive-impairment", "label": "Cognitive Impairment" }, { "name": "dehydration", "label": "Dehydration" }, { "name": "elevated-androgens", "label": "Elevated Androgens" }, { "name": "elevated-blood-pressure", "label": "Elevated Blood Pressure" }, { "name": "fatigue", "label": "Fatigue" }, { "name": "head-impact", "label": "Head Impact" }, { "name": "hypervigilance", "label": "Hypervigilance" }, { "name": "iron-deficiency", "label": "Iron Deficiency" }, { "name": "metabolic-load", "label": "Metabolic Load" }, { "name": "mood-disruption", "label": "Mood Disruption" }, { "name": "stress", "label": "Stress" }, { "name": "substance-use-pattern", "label": "Substance Use Pattern" } ] } ``` ### Errors For authentication errors (401) and other codes, see [Error Reference](/api-reference/error-reference). --- ## GET /v2/signs/{sign\_name} ### GET /v2/signs/{sign\_name} Return details for a single sign, including its display label and condition back-reference. ### Path Parameters | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------------------------------------------------- | | `sign_name` | string | The name of the sign to retrieve. See [Valid sign names](#valid-sign-names) below. | ### Response | Field | Type | Description | | ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sign identifier. | | `label` | string | Human-readable sign name. | | `condition` | string or null | Back-reference to the corresponding legacy condition model ID (e.g. `"acute-stress"`). Populated when the sign has a mapped legacy identifier; null otherwise. | ### Example #### cURL ```bash curl -X GET "https://api.amplifierhealth.com/v2/signs/stress" \ -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/signs/stress", { 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/signs/stress", headers={ "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"], "X-API-Key": os.environ["AMPLIFIER_API_KEY"], }, ) data = response.json() ``` ### Example response ```json { "name": "stress", "label": "Stress", "condition": "acute-stress" } ``` ### Errors | HTTP | Code | Condition | | ---- | ----------- | --------------------------------------------------------------------------------------------------- | | 404 | `NOT_FOUND` | `sign_name` is not a recognized sign. Check the name against [Valid sign names](#valid-sign-names). | For other codes, see [Error Reference](/api-reference/error-reference). --- ## POST /v2/signs/{sign\_name}/analyze ### POST /v2/signs/{sign\_name}/analyze Submit audio to analyze a single sign. Returns a job object immediately; poll GET /v2/jobs/{job\_id} or use a webhook for the completed result. Requests use `Content-Type: multipart/form-data`. The job object is returned immediately with `status: "queued"` and `result: null`. When analysis completes, the `result` contains a singular `signal` object plus `audio_quality`. ### Path Parameters | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `sign_name` | The sign to analyze. Must be a sign available for standalone analysis — see [Valid sign names](#valid-sign-names). | ### Request Body Requests use `Content-Type: multipart/form-data`. | Field | Type | Required | Description | | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio` | file | Yes | Audio file (WAV, FLAC, MP3, or M4A). Max 32 MB per file. For longer recordings, MP3, M4A, or FLAC usually keep the file under the limit. See [Audio Requirements](/guides/audio-requirements#file-size). | | `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. | ### Valid sign names The following signs are available for individual analysis via this endpoint: | Sign name | Label | | ---------------------------- | -------------------------- | | `airway-obstruction-pattern` | Airway Obstruction Pattern | | `alcohol-use-pattern` | Alcohol Use Pattern | | `allergy` | Allergy | | `anxiety` | Anxiety | | `attention-dysregulation` | Attention Dysregulation | | `cognitive-impairment` | Cognitive Impairment | | `dehydration` | Dehydration | | `elevated-androgens` | Elevated Androgens | | `elevated-blood-pressure` | Elevated Blood Pressure | | `fatigue` | Fatigue | | `head-impact` | Head Impact | | `hypervigilance` | Hypervigilance | | `iron-deficiency` | Iron Deficiency | | `metabolic-load` | Metabolic Load | | `mood-disruption` | Mood Disruption | | `stress` | Stress | | `substance-use-pattern` | Substance Use Pattern | ## Code Examples ### Submit #### cURL ```bash curl -X POST https://api.amplifierhealth.com/v2/signs/stress/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -F "audio=@recording.wav;type=audio/wav" ``` #### JavaScript ```javascript const fs = require("fs"); const form = new FormData(); form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav"); const submitResponse = await fetch("https://api.amplifierhealth.com/v2/signs/stress/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/signs/stress/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")}, ) job_id = submit_response.json()["job_id"] ``` ### Example response The API returns immediately with the job object. `status` is `queued` and `result` is `null` until processing completes: ```json { "job_id": "a2e4c7f1-3d9b-4e6a-b8c2-1f5d8e3a7b9c", "status": "queued", "created_at": "2026-05-22T10:30: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": "sign", "api_version": "v2", "sign_name": "stress" } ``` ### Poll job #### cURL ```bash curl https://api.amplifierhealth.com/v2/jobs/a2e4c7f1-3d9b-4e6a-b8c2-1f5d8e3a7b9c \ -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. When `status` is `done`, the `result` contains a singular `signal` object plus `audio_quality` — see [Response Schema — Sign Response](/api-reference/schema#sign-response). ### Errors | HTTP | Code | Condition | | ---- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 404 | `NOT_FOUND` | `sign_name` is not a recognized sign or is not available for standalone analysis. Check the name against [Valid sign names](#valid-sign-names). | | 400 | `AUDIO_TOO_SHORT` | Recording is under 15 seconds. | | 400 | `AUDIO_TOO_LONG` | Recording exceeds 20 minutes. | | 400 | `UNSUPPORTED_FORMAT` | Audio format is not WAV, FLAC, MP3, or M4A. | | 422 | `AUDIO_POOR_QUALITY` | Recording conditions below the threshold used for analysis. | 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 codes and retry guidance, see [Error Reference](/api-reference/error-reference). --- ## Model-internal signs Some signs appear in the `signs` list of named models returned by `GET /v2/models/{model_name}` but are **not** available for standalone analysis via this endpoint. These model-internal signs are not returned by `GET /v2/signs` and cannot be used as a `sign_name` here. Examples of model-internal signs: `cognitive-load`, `cardiovascular-strain`, `emotional-destabilization`, `dry-mouth`. If you need results for these signals, use the named model that includes them via [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api#post-v2modelsmodel_nameanalyze). --- # 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 object: `job_id`, `status`, `model_name` or `sign_name`, and `result`. For a model job, `result` contains `summary`, `signals`, `audio_quality`, and `extended_metrics`; for a sign job, `result` contains a singular `signal` plus `audio_quality`. 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: 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 | | `m4a` | Accepted; common from mobile devices; often smaller than WAV | 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**, **M4A**, 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 scenarios. - **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/models/{model_name}/analyze` or `POST /v2/signs/{sign_name}/analyze`. ```bash curl -X POST https://api.amplifierhealth.com/v2/models/apex/analyze \ -H "X-Account-ID: your-account-id" \ -H "X-API-Key: your-api-key" \ -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 [Model API](/api-reference/models-api). ## 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 models 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 <support@amplifierhealth.com> 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: 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 | | ------------------------------------------------- | :----: | :--------------: | | **Model API** (`/v2/models/{model_name}/analyze`) | 75 | 125 | | **Sign API** (`/v2/signs/{sign_name}/analyze`) | 50 | 100 | 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 | | ----------------------------------- | ------ | ----- | | `apex` model bundle, no diarization | 75 | $0.15 | | `stress` sign, no diarization | 50 | $0.10 | | `apex` model bundle + diarization | 125 | $0.25 | | Sign 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: 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`**, **`failed`**, or **`timed-out`**. - **Model analyze** — [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api). When `status` is **`done`**, `result` contains `summary`, `signals[]`, `audio_quality`, and `extended_metrics`. See [Model API job results](#model-api-job-results). - **Sign analyze** — [`POST /v2/signs/{sign_name}/analyze`](/api-reference/signs-api). When `status` is **`done`**, `result` contains a single `signal` and `audio_quality`. See [Sign API job results](#sign-api-job-results). When `status` is **`failed`** or **`timed-out`**, `result` is usually `null`; see [Job status: failed or timed-out](/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). Named model bundles combine models with different **evidence tiers** (Established, Emerging, Investigational). Interpret each signal using its model’s tier — see [Model Overview](/guides/models) 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 — queued | running | done | failed | timed-out (poll until done | failed | timed-out) ├── job_type — "model" | "sign" ├── model_name — Set when job_type is "model"; null otherwise ├── sign_name — Set when job_type is "sign"; null otherwise ├── created_at — ISO 8601; format varies — see Response Schema → Timestamps ├── completed_at — null while queued/running; when done vs failed/timed-out 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/timed-out ├── summary — Aggregate view; primary routing object (model jobs only) │ ├── 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-sign results (model jobs only) ├── signal — Single signal object (sign jobs only) ├── audio_quality — Recording quality scores and issue codes └── extended_metrics[] — model jobs only ``` ## Model API job results If you use [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api), send multipart **`audio`** with the model name in the URL path. The API returns a **job object** right away (`job_id`, `status: queued`, `result: null` until processing finishes). Poll [`GET /v2/jobs/{job_id}`](/api-reference/results) or use a **webhook** until `status` is **`done`**, **`failed`**, or **`timed-out`**. On the outer job object, `job_type` is `"model"`, `model_name` is the name you requested, and `sign_name` is `null`. When `status` is `done`, **`result`** contains: **`summary`** (with `overall_level`, `recommended_action`, `flagged_count`, `primary_signals`, and `description`), **`signals[]`** (one entry per sign in the bundle), **`audio_quality`**, and **`extended_metrics`**. Read `result.summary.recommended_action` for routing, then `result.signals[]` for per-sign detail. When `status` is `failed` or `timed-out`, `result` is usually `null`; see [Job status: failed or timed-out](/api-reference/schema#job-status-failed). Field-level detail: [Model API](/api-reference/models-api). The same [display and compliance rules](/api-reference/schema#display-and-compliance) apply when presenting outputs. ## Sign API job results If you use [`POST /v2/signs/{sign_name}/analyze`](/api-reference/signs-api), send multipart **`audio`** with the sign name in the URL path. The API returns a **job object** right away (`job_id`, `status: queued`, `result: null` until processing finishes). Poll [`GET /v2/jobs/{job_id}`](/api-reference/results) or use a **webhook** until `status` is **`done`**, **`failed`**, or **`timed-out`**. On the outer job object, `job_type` is `"sign"`, `sign_name` is the name you requested, and `model_name` is `null`. When `status` is `done`, **`result`** contains one **`signal`** object (`recommended_action`, `level`, `flagged`, `description`, and scores) and **`audio_quality`**. There is no top-level **`summary`** and no **`signals[]`** array; use **`result.signal`** for routing and UI. Read `result.signal.recommended_action`, `result.signal.level`, and `result.signal.flagged` for routing. When `status` is `failed` or `timed-out`, `result` is usually `null`; see [Job status: failed or timed-out](/api-reference/schema#job-status-failed). Field-level detail: [Sign API](/api-reference/signs-api). 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 sign in the model bundle. Each entry describes the sign'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 model responses, `signal.description.summary` in sign responses. - `name` — Stable external sign identifier; safe to use in application logic (e.g. `signal.name === "stress"`). `label` is the human-readable display name derived from it. 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: Introduction URL: https://docs.amplifierhealth.com/guides/introduction The **Amplifier Health API** analyzes voice recordings (WAV, FLAC, MP3, or M4A, up to **32 MB** per file) and returns structured health signals—scores, levels, and workflow-oriented fields—for behavioral, cognitive, and metabolic models. ## Analyze endpoints All 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/models/{model_name}/analyze`](/api-reference/models-api) | `model_name` in URL | Named multi-sign bundles; returns summary + `signals[]` + `audio_quality`. | | [`POST /v2/signs/{sign_name}/analyze`](/api-reference/signs-api) | `sign_name` in URL | Single sign; returns one `signal` object + `audio_quality`. | Details, optional fields (e.g. diarization, per-request webhooks), and examples: [Model API](/api-reference/models-api), [Sign API](/api-reference/signs-api). ## 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). 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 under **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. For model jobs, read `result.summary.recommended_action` first; for sign jobs, read `result.signal.recommended_action`. Narrative text under `description` 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 named model bundles combine those models. They are not a separate commercial tier, contract, or entitlement. --- # 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. Follow the on-screen instructions in Claude to authenticate to Amplifier and finish connecting. ## 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 **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 models, signs, result fields, and audio requirements, see the [Guides](/guides/introduction) and [API Reference](/api-reference/overview). --- # Guides: Signs URL: https://docs.amplifierhealth.com/guides/models-all Signs below are listed by evidence tier. For how signs run in the API, tier definitions, speech features, and the acoustic-indicators disclaimer, see [Sign Overview](/guides/models). The acoustic indicators listed for each sign 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 signs) or physiological rationale (Investigational signs) for each sign — not a description of how every individual recording is evaluated. Sign outputs reflect a broad acoustic analysis; no single indicator solely determines a result. ## Established Established signs 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 signs — use it with clinical judgment in the context of each model’s sign mix; see [Introduction](/guides/introduction) for the product disclaimer. ### Stress `established` **Model ID:** `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. --- ### 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. --- ### 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. --- ### Airway Obstruction Pattern `established` **Model ID:** `airway-obstruction-pattern` **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. --- ### Mood Disruption `established` **Model ID:** `mood-disruption` **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. --- ### 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. --- ### Fatigue `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. --- ### Head Impact `established` **Model ID:** `head-impact` **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. --- ## Emerging Emerging signs 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). ### Attention Dysregulation `emerging` **Model ID:** `attention-dysregulation` **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. --- ### Alcohol Use Pattern `emerging` **Model ID:** `alcohol-use-pattern` **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. --- ### 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. --- ### Elevated Androgens `emerging` **Model ID:** `elevated-androgens` **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. --- ### Metabolic Load `emerging` **Model ID:** `metabolic-load` **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. --- ### Hypervigilance `emerging` **Model ID:** `hypervigilance` **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. --- ### Substance Use Pattern `emerging` **Model ID:** `substance-use-pattern` **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. --- ## Investigational Investigational signs are based on acoustically plausible mechanisms with physiological rationale. Investigational signs are suited for exploratory research and supplementary data streams. ### Iron Deficiency `investigational` **Model ID:** `iron-deficiency` **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. --- ### 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. --- # Guides: Signs — Overview URL: https://docs.amplifierhealth.com/guides/models Voice biomarker signs are the acoustic analysis units that underlie both the Model API and the Sign API. Submit audio via [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api) to run a named bundle of signs together, or via [`POST /v2/signs/{sign_name}/analyze`](/api-reference/signs-api) to analyze a single sign individually. Each sign 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 sign carries an evidence tier that reflects the **depth of published academic and scientific research** behind that voice biomarker. The acoustic indicators listed for each sign 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 sign — not a description of how every individual recording is evaluated. Sign outputs reflect a broad acoustic analysis; no single indicator solely determines a result. ## Named Models (Model API) Submit audio to [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api) using one of these eight named model bundles. Each bundle runs a set of signs and returns `summary` + `signals[]` + `audio_quality`. See [Model API](/api-reference/models-api) for request shape, response fields, and examples. Discover available models and their sign composition with [`GET /v2/models`](/api-reference/models-api) or [`GET /v2/models/{model_name}`](/api-reference/models-api). ## 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 signal scores, wellness metrics, and extended metrics returned per model job, 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 [Signs reference](/guides/models-all): [Established](/guides/models-all#established), [Emerging](/guides/models-all#emerging), and [Investigational](/guides/models-all#investigational). --- # 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, M4A, 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 or correct the request - [ ] `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) ## Analysis Selection - [ ] If using the Model API, the `model_name` matches the health context for your user population - [ ] If using the Sign API, the `sign_name` targets the specific signal relevant to your workflow - [ ] If your model or sign includes Emerging or Investigational signals, appropriate clinical oversight is in place - [ ] Your team understands how per-signal evidence tiers relate to your workflows (see [Models](/guides/models) and [Model API](/api-reference/models-api)) ## 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: Models URL: https://docs.amplifierhealth.com/guides/use-cases-all Named models are pre-configured sign bundles tuned for specific health contexts. For model overview and how to choose, see [Models Overview](/guides/use-cases). For individual sign evidence tiers and acoustic indicators, see [Signs reference](/guides/models-all). ### Clinical Behavioral Health **Model:** `haven` Clinical behavioral health screening for telehealth, primary care, and employee assistance contexts. Covers mood disruption, anxiety, stress, hypervigilance, attention dysregulation, and fatigue as primary signs. #### Common Scenarios - **Pre-visit screening:** Collect a short recording before an appointment and surface flagged signs to the care team for review. - **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. #### Signs | name | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ------------- | | `mood-disruption` | [Mood Disruption](/guides/models-all#mood-disruption) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `stress` | [Stress](/guides/models-all#stress) | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `hypervigilance` | [Hypervigilance](/guides/models-all#hypervigilance) | `emerging` | | `attention-dysregulation` | [Attention Dysregulation](/guides/models-all#attention-dysregulation) | `emerging` | --- ### General Wellness **Model:** `pulse` General wellness and readiness monitoring for employer-sponsored wellness programs and employee assistance platforms. Exposes mood disruption, anxiety, stress, fatigue, dehydration, and elevated blood pressure as primary signs. #### 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. #### Signs | name | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `mood-disruption` | [Mood Disruption](/guides/models-all#mood-disruption) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `stress` | [Stress](/guides/models-all#stress) | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | --- ### Cognitive Health **Model:** `clarity` Cognitive health screening for neurology practices, brain health platforms, and cognitive assessment programs. Exposes cognitive impairment as the primary sign. #### Common Scenarios - **Cognitive screening:** Use as a pre-assessment tool before neuropsychological evaluation to triage referral urgency. - **Post-TBI monitoring:** Collect recordings at scheduled clinical assessments during recovery and surface cognitive signals to the clinical team for review. - **Ongoing monitoring:** Track cognitive signals between clinical appointments to inform care decisions. #### Signs | name | Label | Evidence tier | | ---------------------- | --------------------------------------------------------------- | ------------- | | `cognitive-impairment` | [Cognitive Impairment](/guides/models-all#cognitive-impairment) | `established` | --- ### Women's Health **Model:** `aria` Women's health screening for OB/GYN practices, hormonal health platforms, and women's wellness programs. Exposes elevated androgens, iron deficiency, dehydration, mood disruption, fatigue, anxiety, and elevated blood pressure as primary signs. Gender-stratified models 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. #### Signs | name | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `mood-disruption` | [Mood Disruption](/guides/models-all#mood-disruption) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `elevated-androgens` | [Elevated Androgens](/guides/models-all#elevated-androgens) | `emerging` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `iron-deficiency` | [Iron Deficiency](/guides/models-all#iron-deficiency) | `investigational` | --- ### Sports & Human Performance **Model:** `apex` Sports medicine, athletic training, and occupational health screening. Exposes head impact, cognitive load, fatigue, dehydration, stress, anxiety, and cardiovascular strain as primary signs. #### Common Scenarios - **Pre-competition screening:** Collect a short recording before training or competition and surface fatigue or cognitive signs for review by a performance coach or athletic trainer. - **Post-impact screening:** For contact sports, collect recordings after potential head impacts; elevated head-impact 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. #### Signs | name | Label | Evidence tier | | ----------------------- | --------------------------------------------- | ----------------- | | `stress` | [Stress](/guides/models-all#stress) | `established` | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `head-impact` | [Head Impact](/guides/models-all#head-impact) | `established` | | `cognitive-load` | Cognitive Load | `established` | | `cardiovascular-strain` | Cardiovascular Strain | `established` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | --- ### Recovery & Substance Use **Model:** `harbor` Recovery and substance use programs, behavioral health practices, and outpatient treatment. Exposes alcohol use pattern, substance use pattern, emotional destabilization, anxiety, stress, and fatigue as primary signs. #### Common Scenarios - **Intake assessment:** Screen new participants for co-occurring indicators 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 pattern or substance use pattern identify when outreach or clinical follow-up is warranted. #### Signs | name | Label | Evidence tier | | --------------------------- | ----------------------------------------------------------------- | ------------- | | `anxiety` | [Anxiety](/guides/models-all#anxiety) | `established` | | `stress` | [Stress](/guides/models-all#stress) | `established` | | `emotional-destabilization` | Emotional Destabilization | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `alcohol-use-pattern` | [Alcohol Use Pattern](/guides/models-all#alcohol-use-pattern) | `emerging` | | `substance-use-pattern` | [Substance Use Pattern](/guides/models-all#substance-use-pattern) | `emerging` | --- ### Cardiometabolic & Body Baseline **Model:** `tide` Cardiometabolic and body baseline monitoring. Exposes elevated blood pressure, metabolic load, dehydration, iron deficiency, fatigue, and dry mouth as primary signs. Combines signs 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. #### Signs | name | Label | Evidence tier | | ------------------------- | --------------------------------------------------------------------- | ----------------- | | `elevated-blood-pressure` | [Elevated Blood Pressure](/guides/models-all#elevated-blood-pressure) | `established` | | `fatigue` | [Fatigue](/guides/models-all#fatigue) | `established` | | `metabolic-load` | [Metabolic Load](/guides/models-all#metabolic-load) | `emerging` | | `dehydration` | [Dehydration](/guides/models-all#dehydration) | `investigational` | | `iron-deficiency` | [Iron Deficiency](/guides/models-all#iron-deficiency) | `investigational` | | `dry-mouth` | Dry Mouth | `investigational` | --- ### Respiratory Health **Model:** `breath` Respiratory health screening for respiratory conditions with detectable acoustic signatures. Exposes airway obstruction pattern and allergy as primary signs. #### 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 airway obstruction 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. #### Signs | name | Label | Evidence tier | | ---------------------------- | --------------------------------------------------------------------------- | ------------- | | `airway-obstruction-pattern` | [Airway Obstruction Pattern](/guides/models-all#airway-obstruction-pattern) | `established` | | `allergy` | [Allergy](/guides/models-all#allergy) | `emerging` | --- # Guides: Models — Overview URL: https://docs.amplifierhealth.com/guides/use-cases Named models are pre-configured sign bundles tuned for specific health contexts. Submit audio to [`POST /v2/models/{model_name}/analyze`](/api-reference/models-api) with the model name that best matches your deployment context. For detailed sign composition and usage scenarios for each model, see [Models reference](/guides/use-cases-all). ## Available models | Model | Domain | Signs | | --------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `haven` | Clinical Behavioral Health | mood-disruption, anxiety, stress, hypervigilance, attention-dysregulation, fatigue | | `pulse` | General Wellness | mood-disruption, anxiety, stress, fatigue, elevated-blood-pressure, dehydration | | `clarity` | Cognitive Health | cognitive-impairment | | `aria` | Women's Health | mood-disruption, anxiety, fatigue, elevated-blood-pressure, elevated-androgens, dehydration, iron-deficiency | | `apex` | Sports & Human Performance | stress, anxiety, fatigue, head-impact, cognitive-load, cardiovascular-strain, dehydration | | `harbor` | Recovery & Substance Use | anxiety, stress, emotional-destabilization, alcohol-use-pattern, substance-use-pattern, fatigue | | `tide` | Cardiometabolic & Body Baseline | elevated-blood-pressure, fatigue, metabolic-load, dehydration, iron-deficiency, dry-mouth | | `breath` | Respiratory Health | airway-obstruction-pattern, allergy | ## How to choose a model Choose the model that best matches the clinical or wellness context in which you are deploying. The right model is determined primarily by who your end users are and what signals are most clinically relevant for that population. If your platform serves a general behavioral health population — primary care, teletherapy, employee wellness — start with `haven` or `pulse`. If your context is specialized — substance use recovery, cognitive assessment, sports medicine — use the corresponding specialized model, which is configured with the signs most validated for that population. If your platform serves multiple population contexts, submit separate requests with the most specific model name for each participant group. This ensures each group's signals are evaluated with the signs most validated for that context. Discover available models and their current sign composition at runtime with [`GET /v2/models`](/api-reference/models-api) or [`GET /v2/models/{model_name}`](/api-reference/models-api). See [Models reference](/guides/use-cases-all) for full detail on each model. If no existing model fits your deployment context, contact <support@amplifierhealth.com> to discuss your requirements. --- # 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. | --- # 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). ---