# Audio_Resolver_V1 — Spoken-Number Recognition API

**Audio_Resolver_V1** · version `v1` · status `live`

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

| Method | Path | Full URL | Timeout |
| --- | --- | --- | --- |
| `POST` | `/audio/v1/resolve` | `https://api.pehchaantech.com/audio/v1/resolve` | 20000 ms |

Rate limit: **60 requests/minute** · **100000 requests/day**, counted per API key.

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

```json
{
  "_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

```json
{
  "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. |

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

## Changelog

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

---

_Generated from the pehchaantech developer portal · canonical page: https://docs.pehchaantech.com/docs/audio-resolver-v1 · last updated: 2026-07-21T15:00:56.931Z._