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 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 fields: file (or url) and model. 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 "model=zero-indic" \
  -F "language_code=hi" \
  -F "response_format=verbose_json"

Request parameters (all optional except the audio and model):

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 enable_emotion_diarization=true.

Response (json: minimal, OpenAI-compatible):

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

3. WebSocket /ws

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, plus model, language, sample_rate, dtype (see Streaming for the exact fields)
3. Stream binary audio frames
4. Send "END" / {"type":"end"} / empty binary to finalize
5. Receive ready → speech_start → partial* → speech_end → final_segment → ... → end_of_transcript → done

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 full supported language list with ISO codes and script mappings.

Request:

curl https://asrv2prod.shunyalabs.ai/languages \
  -H "Authorization: Bearer $ACCESS_TOKEN"

6. Speaker APIs

Diarization produces SPEAKER_00-style labels. To map those to actual names, register voice profiles using these four endpoints.

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={"model": "zero-indic"},
                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

Every response includes request_id (and an X-Request-Id header). Log it, Shunya support uses it to trace issues. On WebSocket, the session_id in the ready event is the equivalent.