# How does an AI agent create a WhipScribe API key and keep it topped up?

Signed in to an account with API access (the $24 pack or Workspace), open https://whipscribe.com/apis/keys, choose “Sign in & create a key”, name the key and press “Create key”. The key is shown once: store it as WHIPSCRIBE_API_KEY. Send it in the X-API-Key header. GET /v1/credits returns the hours left; when a job comes back locked, add credit and fetch it again.

Checked 5 October 2026. HTML version: https://whipscribe.com/agents/api-key

## Steps

1. **Have API access on the account.** API access comes with the 5,000-minute pack ($24) or the Workspace plan ($19/month). The smaller packs work on the website and do not include API keys. See https://whipscribe.com/agents/buy-credits.
2. **Create the key.** Open https://whipscribe.com/apis/keys and choose “Sign in & create a key”. In the workspace's “Business APIs” panel, type a name (for example production, staging or ci) and press “Create key”.
3. **Store it immediately.** The key is displayed once. Put it in an environment variable or a secret store, never in a repository, a web page or a chat transcript.

```
export WHIPSCRIBE_API_KEY="paste-the-key"
```

4. **Check the balance.** payg_hours_remaining is the pack credit left, in hours.

```
curl -s https://whipscribe.com/api/v1/credits -H "X-API-Key: $WHIPSCRIBE_API_KEY"
```

5. **Transcribe something.** Submit a link, poll the job, fetch the result.

```
export WHIPSCRIBE_API_KEY="paste-the-key"

# 1. Balance: hours of transcription left on the account
curl -s https://whipscribe.com/api/v1/credits \
  -H "X-API-Key: $WHIPSCRIBE_API_KEY"

# 2. Send a link; a job_id comes back straight away
curl -s https://whipscribe.com/api/v1/transcribe/url \
  -H "X-API-Key: $WHIPSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.archive.org/download/testmp3testfile/mpthreetest.mp3"}'

# 3. Poll every few seconds until "status" is "done"
curl -s https://whipscribe.com/api/v1/jobs/$JOB_ID \
  -H "X-API-Key: $WHIPSCRIBE_API_KEY"

# 4. Fetch the transcript (format=txt | json | srt | vtt | docx)
curl -s "https://whipscribe.com/api/v1/jobs/$JOB_ID/result?format=txt" \
  -H "X-API-Key: $WHIPSCRIBE_API_KEY"
```


## What we checked

On 5 October 2026 an automated browser created a key this way with no person involved, and the key then worked from curl: the balance call returned the account's hours, a submitted link came back as a job, the job reached done in seconds and the transcript downloaded as text. The balance fell by the length of the audio.

## When the balance runs out

A job that finishes with no credit left is kept, not lost. Its status carries "locked": true and an unlock_url. format=json still returns the opening part as a preview; other formats and the summary answer 402 with the code transcript_locked until the account has credit.

What an agent should do: stop submitting, tell the person the balance is empty and give them the pack link (https://whipscribe.com/credits?sku=mini-4 for the smallest), then poll GET /v1/credits every minute or so. When the balance is positive, fetch the same job again; it opens in full. Nothing needs to be re-uploaded.

```
# 402 on a locked transcript (main fields)
{"error": "This transcript is locked. Add credits to download it.",
 "code": "transcript_locked",
 "upgrade_url": "https://whipscribe.com/pricing?src=locked-transcript"}
```

## Rules worth encoding in the agent

- One header on every request: X-API-Key. Base URL https://whipscribe.com/api/v1.
- Call from a server or a script. Browsers are blocked from calling the API directly.
- 60 requests a minute per account, shared by its keys; 429 carries Retry-After.
- Poll a job every 3 seconds or slower. Send an Idempotency-Key on submits so a retry cannot start a second job.
- Files up to 10 hours or 5 GB. Failed jobs and recordings with no speech are not charged.
- Up to 10 active keys per account. Rotating a key keeps the old one working for 24 hours; revoking stops it at once.
- Branch on the error code, show the error sentence to people.

## The full reference

Every endpoint, field and error code: https://whipscribe.com/docs. Machine-readable: https://whipscribe.com/openapi.json (OpenAPI 3.0, 12 operations).

## Questions

**Can an agent create an API key through the API?**
No. Keys are created in the signed-in workspace, at https://whipscribe.com/apis/keys. A browser agent can do it; an agent that only makes HTTP calls needs the person to create the key and hand it over.

**How does an agent check how much credit is left?**
GET https://whipscribe.com/api/v1/credits with the X-API-Key header. payg_hours_remaining is pack credit in hours; the workspace object says whether the unlimited plan is active.

**What does a 402 from the WhipScribe API mean?**
The transcript exists but the account had no credit when it finished, so it is locked (code transcript_locked). Add credit to the account and request it again; it opens in full.

**Is there a free API tier?**
No. API access comes with the 5,000-minute pack ($24) or the Workspace plan ($19/month), and usage comes out of the same balance as the website.

**What if the key leaks?**
Revoke it in the same panel; it stops working immediately. Create a new one. Anyone holding a key can spend the account's balance, so treat it like a password.

## Related

- Overview: https://whipscribe.com/agents/index.md
- Instructions for agents: https://whipscribe.com/agents/instructions.md
- How does an AI agent create a WhipScribe account?: https://whipscribe.com/agents/sign-up.md
- How does an AI agent buy WhipScribe credit?: https://whipscribe.com/agents/buy-credits.md
- How do I get Claude or Claude Code to transcribe with WhipScribe?: https://whipscribe.com/agents/claude.md
- How do I get ChatGPT to transcribe with WhipScribe?: https://whipscribe.com/agents/chatgpt.md
- How do I get Cursor or a coding agent to use the WhipScribe API?: https://whipscribe.com/agents/cursor.md
- How do I get an n8n, Make or Zapier agent to transcribe with WhipScribe?: https://whipscribe.com/agents/n8n-make-zapier.md
- How do I transcribe from an Apify Actor or an Apify-based agent?: https://whipscribe.com/agents/apify.md
- API docs: https://whipscribe.com/docs
- OpenAPI: https://whipscribe.com/openapi.json
- Pricing: https://whipscribe.com/pricing