getting started

Credits and metering

What a call costs and when it is charged.

One credit is $0.0001, so $1 is 10,000 credits. Every charge is a whole number of credits, recorded against an append-only ledger. Current rates are on the pricing page.

The order of events

The key is checked and the rate limit applied.
The upload is read and validated: multipart, a file, not empty, under the size limit.
The balance is checked, before any compute. If balance plus overdraft is zero or less, the call is refused with a 402 and nothing runs.
If you sent an Idempotency-Key that was already billed, the call is refused with a 409 and nothing runs.
The audio is transcribed.
Only now is the call billed, on the duration the decoder actually measured, and the result is returned with the cost.

When you are not charged

Any failure before or during transcription. These are recorded for diagnostics with zero units and zero credits.
A client that disconnects before the result is ready. The server skips the charge, so your retry runs and bills once.
A billing outage. The server withholds the transcript rather than delivering it unbilled, and returns a 503 metering_unavailable that is safe to retry with the same key.

How a charge is computed

units is duration_seconds rounded up to a whole second.
Free units for the month are applied first. Whatever remains is billable.
The billable units are multiplied by the rate and rounded up to a whole credit, so a charge is never rounded down to nothing.
A minimum charge applies only when something is billable. A call fully covered by the free allowance costs 0 credits.

text

# 4.32 s of audio, free allowance already used up
units    = ceil(4.32)          # 5
credits  = ceil(5 * 2.5)       # 13 at 2.5 credits per second

The free allowance resets at the first instant of each calendar month, UTC. Free units are always spent before paid credits, so the amount left is simply the allowance minus the units delivered this month. Failed calls delivered nothing and do not count. GET /v1/usage reports what remains and when it resets.

The overdraft

The true cost is only known once the audio is decoded, so the balance check asks whether any headroom is left, not whether the balance covers this exact call. The last call may overshoot zero into the overdraft. Once balance plus overdraft is zero or less, calls are refused with a 402 whose details carry balance and overdraftLimit.

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to run this request. Add credits in the dashboard.",
    "request_id": "req_0Nq8c1xWv3kR",
    "details": { "balance": -1200, "overdraftLimit": 1000 }
  }
}

Idempotency

Send an Idempotency-Key header: 1 to 128 characters, letters, digits and . _ : - only. Keys are scoped to your organization, so they cannot collide with anyone else's. The key is recorded with the charge, and a second call with the same key is refused with a 409 rather than billed again.

json

{
  "error": {
    "code": "idempotency_key_used",
    "message": "A request with this Idempotency-Key was already processed and billed. Use a new key to run the audio again.",
    "request_id": "req_0Nq8c1xWv3kR",
    "details": {
      "usage_event_id": "ue_0Nq8c1xWv3kR",
      "units": 5,
      "credits_charged": 0,
      "quantities": {
        "audio_seconds": 4.32,
        "characters": 32,
        "words": 6
      },
      "processed_at": "2026-10-15T09:12:44.081Z"
    }
  }
}

While a call with a key is still running, a second call with the same key gets a 409 request_in_progress. Wait and retry. Idempotency is not a cache: it prevents a double charge, and it does not return the first transcript a second time.

Prices are versioned

The rate used for a call is read before transcription starts and carried through to the charge, and the usage event records which price row produced the number. A change of price adds a new row and closes the old one.

All documentation