This capability is granted by an API key scoped to the speech-api product (product face). See the product reference below.
Speech-to-text as a shared capability, in TWO modes. BATCH (REST, below): POST audio inline (audio_base64, sync) or by URL (audio_url, async enqueue); provider abstraction with ordered fallback (Deepgram→Whisper→Gemini), per-provider circuit-breaker, durable PG-backed queue, SSRF-guarded URL fetch. STREAMING (WebSocket /audio-stream, see x-streaming): real-time μ-law/PCM audio frames → Deepgram streaming → live transcript finals; the production voice-telephony path. Audio bytes are NEVER persisted; provider keys NEVER in body/DB/logs (resolved server-side, Infisical-rendered).
- Group: Voice & AI
- Contract:
contracts/stt/v1/openapi.yaml
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/speech/transcriptions
- Capability face (internal first-party — NOT customer-keyed):
https://api.vagarylabs.com/v1/transcribe
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/transcribe | Transcribe audio — sync (audio_base64) or async (audio_url). Exactly one of the two. |
GET | /v1/transcribe/{id} | Job status + transcript when done |
GET | /health | DB reachability gate (open) |
GET | /metrics | Prometheus text exposition (open) |
Product face
The external, paying-customer surface served by the edge at /product/v1/* (contracts/stt/product/v1/openapi.yaml).
| Method | Path | Summary |
|---|
POST | /transcriptions | Transcribe audio (managed, metered) — wraps the capability's batch transcribe |
Schemas
TranscribeRequest
exactly ONE of audio_url or audio_base64 is required
| Field | Type | Description |
|---|
organization_id | string | PRODUCT-TIER end-customer tenant (I6); defaults to service default_org |
audio_url | string | SSRF-guarded fetch (re-validated at fetch time); implies async |
audio_base64 | string | inline audio (sync); capped per config.audio.maxInlineBytes |
content_type | string | |
language | string | |
prompt | string | optional Whisper biasing prompt (proper nouns / domain vocabulary); applied only by the Whisper provider, ignored by others |
provider | string | request a specific provider; otherwise ordered fallback |
idempotency_key | string | |
async | boolean | force async even with inline audio |
max_attempts | integer | |
TranscriptionRecord
| Field | Type | Description |
|---|
transcription_id | string | |
organization_id | string | |
mode | string | |
status | object | |
attempts | integer | |
max_attempts | integer | |
provider_requested | string | |
provider_used | string | |
transcript | string | |
confidence | number | |
language | string | |
duration_seconds | number | |
segments | array | segment-level timestamps when the provider supplies them (Whisper verbose_json); null/absent for providers that don't emit segments (Deepgram, Gemini) |
last_error | string | |
created_at | string | |
updated_at | string | |
deduplicated | boolean | present on idempotent replay |
TranscriptSegment
| Field | Type | Description |
|---|
id | integer | |
start | number | segment start time in seconds |
end | number | segment end time in seconds |
text | string | |
TranscriptionStatus
Health
| Field | Type | Description |
|---|
status | string | |
db | boolean | |
providers | array | |
default_org | string | |
Error
| Field | Type | Description |
|---|
error | string | |
Generated by scripts/gen-capability-docs.py from contracts/stt/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.