Blackbird ASR

Speech recognition for 27 Indian languages. Send a file and get a transcript, or stream audio over a WebSocket and get words as they are spoken. Output comes in the speaker's own script, transliterated into Latin, or code-mixed the way people actually talk.

Quickstart

Every request needs an API key in the Authorization header. Replace $BLACKBIRD_KEY below with yours.

# a Hindi file, native script
curl -X POST https://your-host/v1/transcribe \
  -H "Authorization: Bearer $BLACKBIRD_KEY" \
  -F "file=@call.wav" \
  -F "language=hi"

# response
{
  "id": "req_936519b3205b4330bdfcc155",
  "model": "blackbird-indic-v1",
  "text": "मैंने कल पाँच बजे तीन फ़ाइलें अपलोड कीं",
  "language": "hi",
  "language_name": "Hindi",
  "language_source": "explicit",
  "mode": "native",
  "duration_ms": 3408,
  "segments": [{"start_ms": 0, "end_ms": 3408, "text": "मैंने कल…"}],
  "processing_ms": 116,
  "queue_ms": 0
}

Authentication

Keys look like bb_live_… (production) or bb_test_…. Pass one as a bearer token:

Authorization: Bearer bb_live_t31F8uwonghgx8dWn8dB…

The header X-API-Key: <key> is accepted as an alternative. For WebSockets — where browsers cannot set headers — pass the key as the api_key field of the config frame, or as ?api_key= in the URL.

Languages

Pass a code as language. Omit it to have the language identified from the audio. GET /v1/models returns this table at runtime.

Output modes

The same utterance, three renderings. Set mode to pick one.

Language detection

Omit language and the model identifies it first, then transcribes — one extra decoder step, not a second pass over the audio. The response always reports which happened:

Audio

Transcribe a file synchronous

POST/v1/transcribe

Transcribes and waits. Long audio is split at natural pauses internally and returned as timestamped segments. For anything over a few minutes prefer async jobs, so you are not holding a connection open.

Response

Async jobs long audio

POST/v1/transcriptions

Accepts the same fields as /v1/transcribe, returns 202 with a job id immediately, and processes in the background.

# submit
curl -X POST https://your-host/v1/transcriptions \
  -H "Authorization: Bearer $BLACKBIRD_KEY" \
  -F "file=@hour-long-call.mp3" -F "language=hi"
# -> {"id": "job_7c82399e…", "status": "queued", …}

# poll
curl https://your-host/v1/transcriptions/job_7c82399e… \
  -H "Authorization: Bearer $BLACKBIRD_KEY"

GET/v1/transcriptions/{id} — status is queued, processing, completed or failed. When completed, result holds the same object /v1/transcribe returns.

GET/v1/transcriptions — list recent jobs. DELETE/v1/transcriptions/{id} — delete a job and its stored audio.

Streaming over WebSocket realtime

WS/v1/stream

Connect, send one JSON config frame, then send raw PCM as binary frames. Interim text arrives as partial events and is replaced as more audio arrives; each sentence settles into a final event at the pause that ends it.

1 — Config frame

{
  "api_key": "bb_live_…",
  "language": "hi",          // omit or null to auto-detect
  "mode": "native",
  "sample_rate": 16000,     // 8000–96000; resampled if not 16k
  "encoding": "pcm_s16le",   // or "pcm_f32le"
  "interim_results": true
}

2 — Audio frames

Send binary frames of raw mono PCM — no container, no header. Frames of roughly 100 ms are a good default. There is no minimum; the server buffers.

3 — Finish

Send {"type":"finalize"}. The server flushes whatever is still open, emits a last final, then a done summary, then closes.

Full example

import asyncio, json, websockets

async def transcribe(pcm_frames):
    url = "wss://your-host/v1/stream"
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({
            "api_key": "bb_live_…",
            "language": "hi",
            "mode": "native",
            "sample_rate": 16000,
            "encoding": "pcm_s16le",
        }))

        async def receive():
            async for msg in ws:
                ev = json.loads(msg)
                if ev["type"] == "partial":
                    print("~", ev["text"], end="\r")
                elif ev["type"] == "final":
                    print("#", ev["text"])
                elif ev["type"] == "done":
                    return ev["text"]

        task = asyncio.create_task(receive())
        for frame in pcm_frames:      # ~100 ms of int16 PCM each
            await ws.send(frame)
        await ws.send(json.dumps({"type": "finalize"}))
        return await task

Event reference

Latency and behaviour

The model transcribes a whole clip at once rather than token by token, so streaming works by re-decoding the open sentence on a timer and closing it at a pause. Three consequences are worth designing around:

• Finals land shortly after a pause. A sentence is closed once about 250 ms of silence follows it, and the final text arrives a few hundred milliseconds later.
• Interim updates are paced by cost, and dropped under load. Refresh interval adapts to how long the last decode took, and interim work is skipped entirely when the GPU is busy with finals. Final results are never delayed by interim ones.
• Very long sentences are cut. A speaker who never pauses is force-segmented at 25 seconds, at the quietest point available.

Silence is never transcribed: audio below the speech threshold is discarded rather than decoded, so background noise does not produce invented words.

Limits and concurrency

Three independent limits apply, checked in this order:

Requests that exceed service-wide capacity queue briefly rather than failing outright; only a saturated queue or a timed-out wait returns 503. Retry on 429 and 503 with exponential backoff, honouring Retry-After where present.

Usage and quotas

GET/v1/usage/me — what the calling key has spent this month and what remains.

GET/v1/usage — usage across the project, bucketed by grain=hour|day|month, with optional since and until.

Usage is metered in seconds of audio submitted, for both batch and streaming. Failed requests are not billed.

Errors

Every error uses one shape, with a stable code to branch on and a request_id to quote in a support request.

{
  "error": {
    "code": "invalid_language",
    "message": "'zz' is not supported. See GET /v1/models.",
    "request_id": "req_044045f1af0241b58beb"
  }
}

Key administration admin token

These routes need the deployment's admin token, not a customer key. A leaked customer key cannot mint more keys.

curl -X POST https://your-host/v1/keys \
  -H "Authorization: Bearer $BLACKBIRD_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Acme Support Desk",
    "name": "production",
    "max_concurrency": 4,
    "rate_limit_rpm": 240,
    "monthly_seconds_quota": 360000,
    "allowed_languages": ["hi", "en", "mr"],
    "allowed_modes": ["native", "mixed"]
  }'

Health and metrics