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

The model name is in the URL path — no additional form field is needed. See Model 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.

The response returns immediately with the job object. status is running and result is null until processing completes:

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "running",
  "created_at": "2026-02-22T09:14:00Z",
  "completed_at": null,
  "result": null,
  "audio_content_type": "audio/wav",
  "audio_size_bytes": 876032,
  "audio_duration_seconds": 27.4,
  "audio_sample_rate": 16000,
  "job_type": "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 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"

Result

Model job result with elevated stress and anxiety indicators:

{
  "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. Failed jobs (result, HTTP 200): Job Status: Failed.

audio_quality fields (issues, voice_percentage, audio_clarity) and issue codes: Response Schema — audio_quality.

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