Audio_Resolver_V1 — Spoken-Number Recognition API

Audio_Resolver_V1 v1 live

Download as Markdownthe full page as a single .md file — for offline reading or as context for an AI assistant

Authentication

Every request must carry your API key in the X-API-Key header. Your key is issued to you separately by ops and is never shown in this document.

X-API-Key: <your-key>

Base URL

All endpoints are served through the gateway:

https://api.pehchaantech.com

Endpoints

POST /audio/v1/resolve

URL	`https://api.pehchaantech.com/audio/v1/resolve`
Timeout	20000 ms
Rate limit	60 req/min · 100000 req/day

Overview

Turn a short audio clip of a spoken number into the digits it contains. Built for voice-OTP and audio-CAPTCHA flows, where a number is read aloud and you need it back as text.

Recognition is synchronous: one call in, the answer out — no id to redeem, nothing to poll. Send ONE audio file as the multipart form field audio.

Typical clips resolve in about 2.7 seconds; a clip the recognizer finds hard takes up to about 6 seconds, because it retries internally rather than returning a doubtful answer. Set your client timeout to 15 s.

LIMITS: 200 KB and 30 seconds per clip. The size limit is generous for compressed audio and tight for raw — a 3-second clip is ~52 KB as 128 kbps MP3 but ~568 KB as 44.1 kHz stereo WAV, which is what a browser MediaRecorder or phone recording produces. Send MP3/OGG, or downsample to 16 kHz mono, or you will get a 413.

ACCURACY: 90.4% exact match on a 500-clip labelled benchmark. The residual ~10% is dominated by clips where one digit is misheard while the length still looks plausible — those return completed with a wrong digit and are indistinguishable from a correct answer at request time. For anything security-sensitive, check the number against the value you issued.

Numbers are normally 4 or 6 digits. Any other length is treated as unreliable and returned as no_data rather than a wrong answer. Audio is processed in memory and never retained; recognition is self-hosted, so no third party sees your audio.

Request example

{
  "_curl": "curl -X POST https://api.pehchaantech.com/audio/v1/resolve -H \"X-API-Key: $API_KEY\" -F \"audio=@otp.wav\"",
  "_form": "multipart/form-data",
  "audio": "<binary audio file — WAV / MP3 / FLAC / OGG, max 200 KB, max 30 s>"
}

Response example

{
  "result": {
    "digits": [
      2,
      0,
      2,
      7,
      4,
      3
    ],
    "length": 6,
    "number": "202743",
    "confidence": 0.7135
  },
  "status": "completed",
  "success": true,
  "description": "Number recognized"
}

Fields

Field Description

status Branch on this, not on HTTP alone. completed = number recognized; no_data = nothing usable in the clip (re-record, a retry of the same bytes will not help); busy / failed = transient, retry with backoff.

success true only on `completed`, i.e. only when a usable number is present.

result.number The recognized digits as a STRING, in spoken order. Use this rather than `digits` — it preserves leading zeros, which an integer cast destroys.

result.digits The same number as individual integers.

result.length How many digits were recognized. Always 4 or 6 on a `completed`.

result.confidence Mean decoder confidence, 0–1. ADVISORY ONLY and not calibrated: correct answers average 0.81 and incorrect ones 0.74, so the distributions overlap far too much to threshold on. Do not gate acceptance on it.

Field	Description
`status`	Branch on this, not on HTTP alone. completed = number recognized; no_data = nothing usable in the clip (re-record, a retry of the same bytes will not help); busy / failed = transient, retry with backoff.
`success`	true only on `completed`, i.e. only when a usable number is present.
`result.number`	The recognized digits as a STRING, in spoken order. Use this rather than `digits` — it preserves leading zeros, which an integer cast destroys.
`result.digits`	The same number as individual integers.
`result.length`	How many digits were recognized. Always 4 or 6 on a `completed`.
`result.confidence`	Mean decoder confidence, 0–1. ADVISORY ONLY and not calibrated: correct answers average 0.81 and incorrect ones 0.74, so the distributions overlap far too much to threshold on. Do not gate acceptance on it.

Errors

Code Meaning

200 completed Number recognized. `result` is present.

200 no_data Decoded fine, but nothing usable: silence, non-speech, speech with no digits, an implausible digit count, or very low confidence (which guards against invented digits — a noisy clip can otherwise produce a confident fabricated number). Not an error; re-record rather than retry.

413 Clip exceeds 200 KB — almost always uncompressed audio. Compress to MP3/OGG or downsample to 16 kHz mono. Returns {"detail": "…"}.

422 Missing `audio` field, empty file, undecodable audio, or longer than 30 seconds. Returns {"detail": "…"}, not the status envelope.

502 failed Recognizer unavailable. Retry with backoff.

503 busy At capacity. Honour the Retry-After header (~1 s).

401 / 403 / 404 / 429 Added by the gateway: missing or invalid key / key not granted this API / wrong environment for the key / rate limited. These use the gateway shape {"error_code","message","request_id"}, not this API’s envelope.

Code	Meaning
`200 completed`	Number recognized. `result` is present.
`200 no_data`	Decoded fine, but nothing usable: silence, non-speech, speech with no digits, an implausible digit count, or very low confidence (which guards against invented digits — a noisy clip can otherwise produce a confident fabricated number). Not an error; re-record rather than retry.
`413`	Clip exceeds 200 KB — almost always uncompressed audio. Compress to MP3/OGG or downsample to 16 kHz mono. Returns {"detail": "…"}.
`422`	Missing `audio` field, empty file, undecodable audio, or longer than 30 seconds. Returns {"detail": "…"}, not the status envelope.
`502 failed`	Recognizer unavailable. Retry with backoff.
`503 busy`	At capacity. Honour the Retry-After header (~1 s).
`401 / 403 / 404 / 429`	Added by the gateway: missing or invalid key / key not granted this API / wrong environment for the key / rate limited. These use the gateway shape {"error_code","message","request_id"}, not this API’s envelope.

Changelog

2026-07-21 v1 launch — POST /audio/v1/resolve.