# verbi — synchronous speech-to-text API

> verbi transcribes English audio and returns the transcript in the same HTTP
> response — no job queue, no polling. Word-level timestamps + confidence and
> speaker diarization are included free. Built for agents and scripts.

Base URL: https://verbi.services
Auth: `Authorization: Bearer <api_key>` (mint one with `POST /v1/signup`).

## Pricing
Pay-as-you-go, graduated by monthly volume (USD per audio-hour):
- $0.07/hour up to 1,000 hours per month
- $0.05/hour from 1,000 to 10,000 hours per month
- $0.03/hour beyond 10,000 hours per month

Diarization is included free. Card top-ups go live when our Stripe account is
ready (`billing_live` is `false` until then; ask for credit meanwhile).

## Free tier
- Anonymous key: 2 free audio-hours per month.
- Email key: 10 free audio-hours per month + a one-time 20-hour welcome bonus
  (so 30 hours in your first month).

Your balance draws down monthly allowance → welcome bonus → paid credit. The
monthly allowance resets every 30 days; the welcome bonus is one-time.

## Limits
- Per-file cap: 60 minutes per synchronous call (longer files use the async
  batch path, coming soon).
- Concurrency: 1 in-flight transcription for anonymous keys, 2 for email keys.
- Free keys per network: 3 per month — verify an email for more hours per key.

## Endpoints
- `GET /health` — liveness + capacity.
- `GET /v1/pricing` — public price list, limits, free-tier policy (no auth).
- `POST /v1/signup` — mint an api key; optional JSON body `{"email": "..."}`.
- `GET /v1/billing` — your account: plan, balances, remaining hours (auth).
- `POST /v1/transcribe` — body is the raw audio bytes; returns transcript JSON
  with per-word speaker labels + a `speakers` summary (diarization on by default;
  `?diarize=false` to skip).
- `POST /v1/billing/topup` — buy hours (coming soon until billing is live).
- `POST /v1/billing/stripe-webhook` — Stripe events (no-op until configured).

The response to `/v1/transcribe` keep-alive-streams whitespace while a long
file decodes, so a 60-minute file finishes past proxy idle timeouts; the body
is still a single JSON object (leading whitespace is ignorable).

## Errors
JSON `{"error_code", "error_message"}` with an HTTP status:
- 401 UNAUTHORIZED — missing or invalid Bearer key.
- 403 ACCOUNT_SUSPENDED — the account has been suspended (contact us).
- 400 EMPTY_AUDIO — no decodable audio in the request body.
- 413 FILE_TOO_LONG — file exceeds the 60-minute single-call cap.
- 402 QUOTA_EXCEEDED — free balance exhausted (includes a `payment` block).
- 429 TOO_MANY_CONCURRENT — concurrency limit hit (includes `retry_after_sec`).
- 429 SIGNUP_LIMIT — this network reached the free-key signup cap.

## More
- OpenAPI: https://verbi.services/api/openapi.yaml
- Contact: hello@verbi.services