Whisper Web API

Use an active Developer account, an API key with read and write permissions, and API credits. Website Unlimited and Developer API use separate billing and records.

Set WHISPERWEB_API_KEY on your server. Replace the example URL with a direct audio or video file you are authorized to process. Python uses requests; Node.js uses built-in fetch. No Whisper Web SDK is required.

Each example prints a fresh Idempotency-Key before its first POST. Save it. Before rerunning after an uncertain POST response, set WHISPERWEB_REQUEST_ID to that printed value and keep the same request body.

The examples stop waiting after about ten minutes; they do not cancel the service job. Keep the task ID and poll it later. If a create request has an uncertain response, retry with its original Idempotency-Key and body.

Create a named key in Developer Console → API keys. The full value is shown once. Keep it in server-side secret storage; never put it in frontend code, URLs or public repositories.

Keys belong to one Developer account. Expired or revoked keys return 401; a suspended account returns 403. Create a replacement before revoking a key used by your application.

For a local file, follow the four steps below. Completing an upload checks its stored size; decoding and duration checks happen after you create the task. A successful PUT alone does not start transcription.

For a remote file, skip the upload steps and send source.audio_url to POST /transcriptions. Use a direct HTTP or HTTPS media URL. Web pages, private network addresses and unsafe redirects are rejected. Supply either upload_id or audio_url, never both.

One upload belongs to one logical task. To transcribe it again as a new task, create a new upload. The signed URL is valid for one hour; the upload session expires after 24 hours. Treat signed URLs as temporary credentials.

Both tasks cost $0.01 per minute, billed by the second. Use language: auto, or a supported source-language code such as en, es, fr, de, ja or zh. English translation always returns English, regardless of the source language.

Send an Idempotency-Key of 8–128 letters, numbers, dots, colons, underscores or hyphens. A new request returns 202 with duplicate: false; an identical retry returns the existing task with 200 and duplicate: true.

The create response contains status and metadata, not transcript text. HTTP 202 does not guarantee media validation or sufficient credits for the measured duration. Check the task until it reaches a terminal state.

GET /transcriptions/{id} reports status, error and usage. While waiting, use retry_after_ms and poll at least five seconds apart. usage.credits can represent a quoted or reserved amount; only usage.status = settled represents the final charge.

GET /transcriptions/{id}/result?format=json returns the shape below. Use format=txt, srt or vtt for a downloadable file. Segment times are milliseconds; these are speech segments, not word-level timings or speaker labels.

GET /transcriptions lists records with items and next_cursor. Pass next_cursor as cursor for the next page; limit is 1–200 (default 20), and status is an optional filter. DELETE /transcriptions/{id} removes a completed or failed result; active tasks return 409. Billing history remains.

One credit is one audio second. The measured duration is rounded up to the next whole second: 62.3 seconds uses 63 credits. Set max_cost_credits to cap a task's cost; a higher measured cost produces a failed task before transcription starts.

Credits are held before processing, charged after the result is saved, and released after confirmed failure. Status reads, result downloads and webhook delivery have no transcription charge. Retry the same task with its original Idempotency-Key to avoid creating another billable task.

Credit packs are one-time purchases, with no automatic recharge or overage charges. Credits appear after payment confirmation. Website Unlimited does not provide API credits; API purchases do not change your website subscription.

GET /usage returns account-wide balances, pricing, limits, items and next_cursor. Use cursor for older activity; before filters by timestamp and api_key_id filters task activity by key. Reserved and released entries are movements, not extra charges to add to settled usage.

An HTTP error returns error.code, message, request_id and retryable. The X-Request-Id response header also identifies the request. For an accepted task, GET can return HTTP 200 with status: failed and an error; this is a task failure, not a failed GET.

After an uncertain create response, send the same Idempotency-Key and identical body. Changing the body under the same key returns 409. Do not create a new task merely because polling or your client times out. Respect Retry-After on 429; fix permission, balance or validation errors before retrying.

Media limits are 5 GB decimal (5,000,000,000 bytes) and 10 hours. Each account can have 20 nonterminal tasks, 2 concurrent executions per processing phase, and 10 retained uploads totaling at most 10 GB.

Request limits are 120 GET requests and 30 write requests per minute, enforced for both the account and each key. GET /usage returns the configured limits.

Webhooks are optional; polling remains available. Events carry the task ID and status, not transcript content. Retrieve the result with your API key after a completion event.

Verify the untouched request body with the signing secret and Standard Webhooks headers. The Node.js standardwebhooks package provides Webhook.verify. Verification must happen before parsing or re-serializing the body; reject invalid signatures and stale timestamps.

Return 2xx after durably accepting the event. Deduplicate by event ID and handle out-of-order delivery. Automatic delivery retries are bounded to 10 attempts within a 24-hour window. A manual retry uses the same event ID and starts a new retry window. Delivery failure does not undo the result or charge again.

The remote MCP server at https://whisperweb.dev/mcp exposes the Developer API to AI agents over Streamable HTTP. Add the URL to your client and sign in with your Whisper Web account; OAuth discovery, PKCE and client registration are automatic, so there is no API key to copy.

MCP uses the same Developer account, credits and records as the REST API: $0.01 per audio minute, billed per second. MCP is available to Developer accounts that have bought API credits; uploads and transcription also need a positive balance. Status checks and reading results do not use credits. Agents are instructed to confirm before spending credits.

Agents can transcribe direct media URLs, single YouTube, Facebook and X (Twitter) video links, files uploaded through a signed URL (create_upload, then PUT with curl, then transcribe_upload), and files picked in the in-chat uploader on clients that support MCP Apps. Only transcribe media you own or are authorized to use.

Deleting transcriptions is a separate permission that is not granted by default. Disconnect any agent in Developer Console → AI agents (MCP); its next call is refused.

API keys can access only their own Developer account. Your website recordings and Unlimited benefits remain separate. Keep API keys, webhook secrets and signed storage URLs private.

An unused upload session expires after 24 hours. Its signed PUT URL expires sooner, as shown by upload_url_expires_in_seconds. Temporary source media is cleaned up after a confirmed terminal state; a new transcription requires a new input.

Task results expire 30 days after task creation, not completion. Download before expires_at. A result that is not ready returns 409; an expired result returns 410. Delete a completed or failed task early with a key that has deletion permission.

Request logs exclude media, transcript text, full source URLs and credentials. Deleting a transcript does not erase payment or usage history. Console logs, purchases and webhook deliveries show up to 100 recent records; their filters apply to the loaded records.