Speech-to-Text

Transcribe audio to text

Speech-to-Text

Transcribe audio files to text. A single endpoint serves three modes — default async, opt-in streaming, opt-in sync — controlled by query parameters.

Edge endpoints accept your pg_* API key as a bearer token. See Authentication for details. The cURL examples below pin Toronto (yto-01) for concreteness — substitute another region or discover the fastest one via GET https://autorouter.polargrid.ai/v1/route.

Transcribe Audio

POST /v1/audio/transcriptions

The multipart body carries only the file. Everything else is a query parameter.

Query Parameters

Parameter	Type	Required	Default	Description
model	string	Yes	—	STT model (e.g. whisper-large-v3-turbo, cohere-transcribe-03-2026)
language	string	No	—	ISO-639-1 language code
prompt	string	No	—	Context hint to guide transcription
response_format	string	No	json	json, text, srt, vtt, or verbose_json
temperature	number	No	0	Sampling temperature (0.0-1.0)
punctuation	boolean	No	—	Force/forbid punctuation in the output
stream	boolean	No	false	If true, return Server-Sent Events
sync	boolean	No	false	If true, block until completion and return the result inline

Three Modes

Query flags	Response	Use when
(none)	202 Accepted with { job_id, status, poll_url }	Default. Best for long files; poll with GET /v1/audio/transcriptions?job_id=...
?stream=true	200 SSE of transcript.text.delta + transcript.text.done	Best UX for real-time display
?sync=true	200 with formatted body (JSON / text / SRT / VTT / verbose JSON)	Small files when you can wait inline

stream=true and sync=true are mutually exclusive.

OpenAI SDK Drop-In

OpenAI’s transcription endpoint is strictly synchronous, and stock OpenAI SDKs send model, language, response_format, and temperature as multipart form fields — they have no way to add query parameters. The endpoint accepts both shapes:

• Form fields are honored as fallbacks for any query parameter you don’t set (query always wins when both are present).
• A request whose model arrives as a form field with no mode flags is served synchronously — a stock OpenAI SDK gets the transcript inline, exactly as it does against OpenAI.

from openai import OpenAI

client = OpenAI(
    api_key="pg_your_api_key",
    base_url="https://api.yto-01.edge.polargrid.ai/v1",
)
result = client.audio.transcriptions.create(
    model="whisper-large-v3-turbo",
    file=open("recording.mp3", "rb"),
)
print(result.text)

The async-job default (202 + poll_url) applies only to PolarGrid-style requests that pass model as a query parameter. If you build raw requests and want inline results, pass ?sync=true.

Available Models

Model	Description
whisper-large-v3-turbo	OpenAI Whisper, fast multilingual transcription
cohere-transcribe-03-2026	Cohere transcription, 14 languages

Examples

Default — async job

cURL

# 1. Submit
curl -X POST "https://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions?model=whisper-large-v3-turbo&language=en" \
  -H "Authorization: Bearer pg_your_api_key" \
  -F "file=@recording.mp3"

# {
#   "job_id": "job_transcription_a1b2c3d4e5f6",
#   "status": "accepted",
#   "poll_url": "/v1/audio/transcriptions?job_id=job_transcription_a1b2c3d4e5f6"
# }

# 2. Poll
curl "https://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions?job_id=job_transcription_a1b2c3d4e5f6" \
  -H "Authorization: Bearer pg_your_api_key"

// SDK helper: submit and wait for the result.
const result = await client.transcribeAndWait({
  file,
  model: 'whisper-large-v3-turbo',
  language: 'en',
});
console.log(result.text);

result = await client.transcribe_and_wait(
    file=Path("recording.mp3"),
    model="whisper-large-v3-turbo",
    language="en",
)
print(result.text)

Streaming — SSE

cURL

curl -N -X POST "https://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions?stream=true&model=whisper-large-v3-turbo&language=en" \
  -H "Authorization: Bearer pg_your_api_key" \
  -F "file=@recording.mp3"

for await (const evt of client.transcribeStream({
  file,
  model: 'whisper-large-v3-turbo',
  language: 'en',
})) {
  if (evt.type === 'transcript.text.delta') console.log('[partial]', evt.delta);
  if (evt.type === 'transcript.text.done') console.log(evt.text);  // authoritative
}

async for evt in client.transcribe_stream(
    Path("recording.mp3"),
    TranscriptionRequest(model="whisper-large-v3-turbo", language="en"),
):
    if evt.type == "transcript.text.delta":
        print(f"[partial] {evt.delta}")   # provisional; see Delta semantics
    elif evt.type == "transcript.text.done":
        print(evt.text)                   # authoritative transcript

polargrid transcribe recording.mp3 --model whisper-large-v3-turbo --stream

Sync — blocking request

cURL

curl -X POST "https://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions?sync=true&model=whisper-large-v3-turbo&language=en" \
  -H "Authorization: Bearer pg_your_api_key" \
  -F "file=@recording.mp3"

const transcription = await client.transcribe({
  file,
  model: 'whisper-large-v3-turbo',
  language: 'en',
  stream: false,  // hits the ?sync=true path
});
console.log(transcription.text);

transcription = await client.transcribe(
    file=Path("recording.mp3"),
    request=TranscriptionRequest(
        model="whisper-large-v3-turbo",
        language="en",
        stream=False,
    ),
)
print(transcription.text)

Cohere model — same surface, different model id

cohere-transcribe-03-2026 supports the same sync, stream, and async modes. Swap the model query parameter — everything else is identical:

cURL

curl -N -X POST "https://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions?stream=true&model=cohere-transcribe-03-2026" \
  -H "Authorization: Bearer pg_your_api_key" \
  -F "file=@recording.mp3"

for await (const evt of client.transcribeStream({
  file,
  model: 'cohere-transcribe-03-2026',
})) {
  if (evt.type === 'transcript.text.delta') console.log('[partial]', evt.delta);
  if (evt.type === 'transcript.text.done') console.log(evt.text);
}

async for evt in client.transcribe_stream(
    Path("recording.mp3"),
    TranscriptionRequest(model="cohere-transcribe-03-2026"),
):
    if evt.type == "transcript.text.delta":
        print(f"[partial] {evt.delta}")
    elif evt.type == "transcript.text.done":
        print(evt.text)

Cohere covers 14 languages but does not auto-detect: it requires a language to decode and falls back to en when language is omitted. The audio is still transcribed correctly (the model is multilingual), but the language field in the response will report en rather than the spoken language. Pass language explicitly (e.g. &language=fr) whenever you need the response metadata to reflect the actual language.

Live Streaming — WebSocket

wss://api.<node>.edge.polargrid.ai/v1/audio/transcriptions/ws

The upload modes above need the complete file before transcription starts. The WebSocket surface transcribes while you capture: stream PCM frames from the microphone and partial transcripts arrive during the utterance.

• Connect with ?token=<pg_* key or session JWT>; optional model, language, prompt, window_s query params
• Send binary frames: 16 kHz mono little-endian 16-bit PCM
• Send {"type":"stop"} (text frame) to end the utterance
• Receive the same event vocabulary as SSE: transcript.text.delta per ~1 s window of new audio, then one authoritative transcript.text.done after stop (see Delta semantics — deltas are provisional display hints, not concatenable fragments)

import asyncio, json, websockets

async def live_transcribe(frames):
    url = "wss://api.yto-01.edge.polargrid.ai/v1/audio/transcriptions/ws" \
          "?token=pg_your_api_key&model=whisper-large-v3-turbo"
    async with websockets.connect(url) as ws:
        async def send():
            async for frame in frames:        # 16kHz mono int16 PCM chunks
                await ws.send(frame)
            await ws.send(json.dumps({"type": "stop"}))
        async def recv():
            async for msg in ws:
                ev = json.loads(msg)
                if ev["type"] == "transcript.text.delta":
                    print(f"[partial] {ev['delta']}")   # provisional; see Delta semantics
                elif ev["type"] == "transcript.text.done":
                    return ev["text"]                   # authoritative transcript
        _, text = await asyncio.gather(send(), recv())
        return text

Sessions are capped at 120 seconds of audio — this surface targets conversational turns. For long recordings use the upload endpoint.

Measured on a production edge (100 runs, 5-clip 4.2–7.7 s corpus streamed at real-time mic pace): first partial arrives ~1 s into the utterance (the first window boundary), subsequent partials each window while audio is still flowing, and the authoritative done lands 159 ms p50 / 205 ms p95 after the stop marker — the effective end-of-speech-to-transcript latency for a voice agent on this surface. See the whisper-large-v3-turbo model card for the full table.

SSE Event Types

type	Fields	When
transcript.text.delta	delta (string)	Zero or more, provisional (see Delta semantics below)
transcript.text.done	text, duration (s), language	Exactly once, before the stream closes
error	error (string)	On failure — stream ends after

Terminated by data: [DONE]\n\n (SSE surface only).

Delta semantics

Applies to both the SSE and WebSocket surfaces, which share the same engine. Each window re-transcribes the full audio buffered so far, producing a new hypothesis. The delta field then carries one of two things:

• the new suffix, when the new hypothesis extends the previous one unchanged (e.g. " This is a short."), or
• the full revised hypothesis, when re-decoding changed earlier text (e.g. "Hello. This is a short test phrase for").

The two cases are not distinguishable from the event alone, so do not concatenate deltas (you will render duplicated text) and do not replace your display with a bare delta (you will drop earlier text when the delta is a suffix). Treat deltas as low-latency provisional output for live display, and always take the final transcript from done.text — it is the only authoritative value, produced by a fresh pass over the complete audio.

Polling Responses

GET /v1/audio/transcriptions?job_id=... returns:

• 202 while the job is accepted / processing — { job_id, status, poll_interval_ms }
• 200 when completed — formatted body, with job_id and status: "completed"
• 400 on failed / cancelled

Supported Audio Formats

MP3, WAV, M4A, OGG, FLAC, WebM

Limits

Limit	Value	On exceed
Maximum upload size	100 MB	413 with a structured JSON error (error.code: "file_too_large")

{
  "message": "File too large. Maximum upload size is 100MB. For longer recordings, split the audio into segments and submit them as separate requests.",
  "error": {
    "message": "File too large. Maximum upload size is 100MB. ...",
    "type": "invalid_request_error",
    "code": "file_too_large"
  }
}

There is no separate duration limit — only size. As a rule of thumb, 100 MB holds roughly 1.5 hours of 16 kHz mono WAV or many hours of MP3.

For recordings over the limit, split the audio into segments (for example with ffmpeg -f segment), submit each segment as its own request — the default async mode is built for this — and concatenate the transcripts. Splitting on silence rather than fixed intervals avoids cutting words in half.