ASR API reference

Every endpoint under asrv2prod.shunyalabs.ai, their request fields, response shapes, and error codes.

export ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs…paste-here"

export ACCESS_TOKEN=$(curl -s -X POST https://app.shunyalabs.ai/api/auth/token \
  -H "api-key: $SHUNYALABS_API_KEY" | jq -r .token)

1. Authentication

All endpoints except /health and /languages require a bearer token in the Authorization header.

Authorization: Bearer $ACCESS_TOKEN

2. POST /v1/audio/transcriptions

Batch transcription of an audio file or URL. Returns the full transcript, per-segment timestamps, and any intelligence results you enabled.

Required: the audio, as file, audio_base64 or url. Content-Type: multipart/form-data. See Configuration for every parameter.

Request:

curl -X POST https://asrv2prod.shunyalabs.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@call.wav" \
  -F "language_code=hi" \
  -F "response_format=verbose_json"

Request parameters (all optional except the audio):

Response (verbose_json):

{
  "success": true,
  "request_id": "b3f1a2c4...",
  "text": "नमस्ते मोहम्मद जी, ये एक ज़रूरी कॉल है।",
  "detected_language": "hi",
  "detected_language_name": "Hindi",
  "segments": [
    {
      "start": 0.51, "end": 5.70,
      "text": "नमस्ते मोहम्मद जी...",
      "speaker": "SPEAKER_00",
      "confidence": 0.97,
      "emotion": "neu",
      "emotion_confidence": 0.68
    }
  ],
  "words": [
    { "word": "नमस्ते", "start": 0.51, "end": 0.94, "confidence": 0.99 }
  ],
  "speakers": ["SPEAKER_00"],
  "speaker_turns": [
    { "start": 0.51, "end": 5.70, "speaker": "SPEAKER_00" }
  ],
  "audio_duration": 5.7,
  "inference_time_ms": 812.3,
  "emotion": { "label": "neu", "score": 0.68 },
  "emotion_summary": {
    "dominant_emotion": "neu",
    "emotion_distribution": { "neu": 100.0 },
    "avg_confidence": 0.68
  },
  "nlp_analysis": {
    "intent": "Booking confirmation request",
    "sentiment": "neutral",
    "summary": "Caller greets Mohammad and flags an urgent call.",
    "keyterms": ["ज़रूरी कॉल"]
  }
}

detected_language is an ISO code; detected_language_name is the same value spelled out. The nlp_analysis, emotion/emotion_summary, and speakers/speaker_turns blocks appear only when you enable the matching parameter, and per-segment emotion/emotion_confidenceappear only with emotion=true.

Response (json: minimal, OpenAI-compatible):

{ "text": "नमस्ते मोहम्मद जी, ये एक ज़रूरी कॉल है।" }

3. WebSocket /v1/realtime

Full protocol documented in Streaming. Summary of the lifecycle:

1. Open wss://asrv2prod.shunyalabs.ai/v1/realtime
2. Send a JSON init frame carrying your access token as token (or api_key), plus language_code (alias language) and sample_rate. Also read: model, diarize, num_speakers, codeswitch, boost_phrases, boost_weight. Nothing else in the frame is read — fields like dtype or chunk_size_sec are ignored.
3. Wait for ready, then stream binary frames of 16-bit signed little-endian mono PCM at the sample_rate you declared. There is no format negotiation: G.711 µ-law or A-law sent raw is read as int16 and comes back as noise, so telephony callers decode to PCM their side and declare sample_rate 8000.
4. Send the text frame "commit" to finalize a turn and keep the socket open, or "end" to finalize and close. Keep reading until the last final arrives.
5. Events are ready, partial, final and error — plus final_refined when codeswitch is on. A single turn can emit more than one final, so concatenate them rather than assuming one per commit.

Errors are an error event — {"type":"error","error":"..."} — and close code 1008. The reason is the error string; there is no separate error-code vocabulary and no code or message field to switch on.

4. GET /health

Unauthenticated. Use for deployment smoke tests.

Request:

curl https://asrv2prod.shunyalabs.ai/health

Response:

{ "ok": true }

Returns ok: true when the service is healthy. No token required — use it for liveness and deployment smoke tests.

5. GET /languages

Returns the supported language list — 145 codes — alongside the model aliases the service accepts and its feature names. Unauthenticated, like /health.

Request:

curl https://asrv2prod.shunyalabs.ai/languages

6. Speaker APIs

Diarization produces SPEAKER_00-style labels. To map those to actual names, register voice profiles using these two endpoints, then send speaker_id=true with num_speakers.

6.1 POST /v1/speakers/register

Request:

curl -X POST https://asrv2prod.shunyalabs.ai/v1/speakers/register \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "name=Priya" \
  -F "file=@priya_sample.wav" \
  -F "project=support_team"

Response:

{ "success": true, "speaker": "Priya", "message": "Registered successfully" }

6.2 DELETE /v1/speakers/delete

Request:

curl -X DELETE https://asrv2prod.shunyalabs.ai/v1/speakers/delete \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "name=Priya" \
  -F "project=support_team"

Response:

{ "success": true }

7. HTTP error codes

8. Retry patterns

Safe to retry: 429, 500, 502, 503, 504. Not safe: 400, 401, 422: fix the request first.

Exponential backoff (Python)

import time, requests

def transcribe_with_retry(file_path, retries=3):
    for attempt in range(retries):
        with open(file_path, "rb") as f:
            r = requests.post(
                "https://asrv2prod.shunyalabs.ai/v1/audio/transcriptions",
                headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
                files={"file": f},
                data={"language_code": "hi"},
                timeout=120,
            )
        if r.status_code == 200:
            return r.json()
        if r.status_code in (429, 500, 502, 503, 504):
            time.sleep(2 ** attempt)  # 1s, 2s, 4s
            continue
        r.raise_for_status()
    raise RuntimeError("Max retries exceeded")

WebSocket reconnection

async def stream_with_reconnect(max_attempts=3):
    for attempt in range(max_attempts):
        try:
            async with websockets.connect("wss://asrv2prod.shunyalabs.ai/v1/realtime") as ws:
                await ws.send(json.dumps({...}))
                async for msg in ws:
                    yield json.loads(msg)
                return
        except websockets.ConnectionClosed:
            await asyncio.sleep(2 ** attempt)
    raise RuntimeError("Max reconnects exceeded")

9. Rate limits

10. Request IDs

Successful responses carry an X-Request-Id header, and a verbose_json body repeats it as request_id (a minimal json body is only { text }, so read the header there). Log it, Shunya support uses it to trace issues.