From recording to transcript.

API reference

Base URL: https://api.getaira.io. Use the same routes from any client.

HTTP 402 returns native payment challenges or browser checkout instructions. HTTP 202 means the job is pending or held. The OpenAPI contract describes every request and response field.

1. Save a retry key and upload

Download the local-file helper from the documentation links below. Use Node.js 22 or later. Install the payment SDK once in the same directory as the helper. The payment example below uses test mode. For development, pass --api with your test API origin and --development-key-env with its access-key variable on every command. The saved receipt binds recovery to that same origin. Your client reads a local recording and uploads its bytes. The API cannot read a path on your computer.

npm install mppx@0.10.1
node transcript.mjs quote ./recording.mp3 --native --receipt ./job.json
node transcript.mjs quote ./large-video.mp4 --native --prepare-audio --receipt ./job.json

The helper saves a random Idempotency-Key before uploading. If the response is interrupted, repeat the same command with the same file and receipt. Audio preparation requires local FFmpeg. A supported direct media URL can replace the file path. Signed URLs must remain available during ingestion. Redirects and ordinary website/watch URLs are rejected.

2. Save the payment-required response

HTTP 402
WWW-Authenticate: Payment ...
{
  "job_id": "job_ followed by 32 lowercase hex characters",
  "access_token": "a private 43-character access key",
  "state": "quoted",
  "quote": {
    "amount_cents": 50,
    "currency": "usd",
    "price_version": "the returned price version",
    "expires_at": "the returned ISO deadline"
  },
  "result_expires_at": "the returned result deadline",
  "status": "payment_required",
  "payment": {
    "method": "the returned native method",
    "mode": "test",
    "continuation_path": "/v1/transcriptions/jobs/{job_id}/pay",
    "retry": "continue this same job without another upload"
  }
}

This is a shape example. The exact price, mode and deadlines come from your accepted quote. The helper saves private access and the payment challenge in an owner-only receipt. Keep that file private. Never put an access token or payment credential in a URL, public log or shared transcript.

3. Authorize payment on the same job

Obtain a payment token from your authorized wallet for the merchant and quoted amount. Provide it through an environment variable. The client does not need the service's secret key. Set the maximum you approve in integer cents and require the returned payment mode. The client checks the API realm, job, currency, amount and expiry before using the token.

node transcript.mjs pay ./job.json \
  --payment-token-env TRANSCRIPT_AGENT_PAYMENT_TOKEN \
  --max-cents 50 --payment-mode test

Use test mode against an isolated development API. For a live quote, choose live mode only with explicit spending authorization. Do not send a test-mode command to a live quote. A spending limit below the quote refuses payment. The client saves its signed authorization before sending it. No payment token or private access key is printed.

POST /v1/transcriptions/jobs/{job_id}/pay
X-Job-Token: {access_token}
Authorization: Payment {signed credential}

Payment-Receipt: {settlement receipt}

If the payment response is interrupted, repeat node transcript.mjs pay ./job.json. The client reads the same job first. It retains and reuses a submitted credential while settlement is unknown. It does not obtain another token or upload the recording again. A known paid job resumes its existing processing.

4. Poll or recover the private job

node transcript.mjs status ./job.json
node transcript.mjs wait ./job.json --output ./transcript.txt

GET /v1/transcriptions/jobs/{job_id}
Authorization: Bearer {access_token}

Poll no more than once every 15 seconds. The states provider_started and provider_pending mean processing is underway. A result is ready only at completed. After a timeout or process restart, use the same receipt. The helper rejects simultaneous writers and recovers its lock only when the owning process is confirmed absent.

For reconciliation_required or refund_required, retain the job reference and contact support before another purchase. These states do not authorize another payment. The state refunded means the full payment was returned and no transcript was delivered.

5. Retrieve the text

GET /v1/transcriptions/jobs/{job_id}/result
Authorization: Bearer {access_token}

{ "job_id": "your job ID", "text": "Your spoken words…" }

The wait command saves the text to a new owner-only file. Download before the returned result_expires_at. The seven-day window begins when the quote is created. Results contain plain text. Speaker names, timestamps, summaries and translations are not included.

Browser checkout fallback

To request a browser payment link, omit --native when quoting, then run node transcript.mjs checkout ./job.json. Complete that checkout and resume the saved job. Choose the payment path before uploading. A checkout return URL does not prove settlement. Keep an unresolved purchase separate from a new request.

Raw HTTP intake

request_id="$(openssl rand -hex 16)"
curl -X POST https://api.getaira.io/v1/transcriptions \
  -H "Idempotency-Key: $request_id" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @recording.mp3

This unnegotiated request returns browser payment instructions. Native clients use the payment negotiation header provided by their SDK or the helper's --native option. For an eligible object-storage URL, the same route accepts JSON {"media_url":"https://bucket.s3.amazonaws.com/recording.mp3"}.

Limits and errors

English only. Maximum 24,000,000 bytes and 120 minutes including encoding padding. PCM16 WAV supports mono/stereo at 8 to 48 kHz. MP3 requires MPEG Layer III frames. MP4/M4A requires a nonfragmented file with one AAC-LC audio track. Prepare other videos locally with the helper.

Structured errors use {"error":{"code":"…"}}. HTTP 402 requests payment. HTTP 202 identifies a pending or held job. Wrong access, invalid credentials, expired quotes/results and unsupported input return errors. An unknown payment outcome must keep the same saved receipt and credential. Never retry it as a new purchase.

Agent-readable documentation

Read the same guide as Markdown. OpenAPI contract. Local-file helper. Keep the accepted quote and private job access before authorizing payment. Resume that same job if your connection is interrupted.