POST /verify - VoiceMark

Verifies a voice recording. Returns an ephemeral JWT token (60s TTL) and both VoiceMark visual outputs. The token is the credential — pass it to your backend for authorisation decisions.

Request

POST /v1/verify Content-Type: multipart/form-data

Field	Type	Required	Notes
`audio`	File	Yes	WAV, WebM, MP3 or M4A
`voiceprint_id`	string	No	Enables identity check against enrolled embedding
`challenge_id`	string	No	Enables anti-replay check; expires 120s after issue

Omitting voiceprint_id runs liveness-only verification. Omitting challenge_id skips anti-replay. For highest security, always pass both.

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_id": "tok_9a2b3c4d5e6f",
  "authorized": true,
  "liveness_score": 0.91,
  "transcription": "Wild roses grew beside the wooden fence.",
  "pii": null,
  "expires_in": 60,
  "cloud_data": {
    "words": [
      { "word": "Wild", "f0": 142.3, "rms": 0.08, "bands": [0.4, 0.6, 0.3, 0.2] },
      { "word": "roses", "f0": 128.1, "rms": 0.11, "bands": [0.5, 0.7, 0.4, 0.3] }
    ],
    "glyph_params": {
      "hue": 0.61,
      "shapeStretch": 0.44,
      "shellDensity": 0.73
    }
  }
}

Field	Description
`token`	60s JWT — pass to your backend via header
`token_id`	Use with `/v1/token/{id}/validate`
`authorized`	Whether voice matched. Do not trust this alone — validate the token server-side for privileged actions.
`liveness_score`	0–1 liveness confidence (f0 variation analysis)
`transcription`	Whisper transcription of the recording
`pii`	Always null — no personal data returned
`cloud_data.words`	Per-word acoustic data for Cloud VoiceMark rendering
`cloud_data.glyph_params`	Stable identity params for Glyph VoiceMark rendering

Error codes

Code	Status	Cause
`VOICE_MISMATCH`	400	Speaker match score below threshold
`CHALLENGE_EXPIRED`	400	`challenge_id` unknown or expired
`AUDIO_TOO_SHORT`	400	Clip too short
`UNAUTHORIZED`	401	Missing or invalid API key

⌘I