--- name: scriptivox description: >- Transcribe recorded audio and video with Scriptivox. Use when a task needs speech turned into text, captions, or a speaker-attributed transcript — and to create an account, buy credit, or mint an API key on behalf of a person. Not for live streaming or real-time dictation. homepage: https://www.scriptivox.com --- # Scriptivox Turns a **recorded** audio or video file into text: 119 languages, speaker diarization, word-level timestamps, and SRT / WebVTT / plain-text export. ## Use this when - A meeting, interview or call recording needs a speaker-attributed transcript. - A podcast, lecture or video needs captions. - A pipeline needs word-level timestamps so clips can be found by phrase. - An archive needs batch transcription. **Do not** use it for live streaming or real-time dictation — every job takes a complete file. Files must be 1 second to 10 hours and at most 5 GB. ## Step 0: which product Scriptivox is two products sharing one account, and picking wrong is the most common mistake here. | | Use it when | |---|---| | **The API** (`https://api.scriptivox.com/v1`) | **You are transcribing.** Billed per hour of audio against a prepaid balance. No daily cap. This is almost always what an agent wants. | | **The web app** (`https://www.scriptivox.com`) | A *person* will do the transcribing in a browser. Plans include unlimited transcription and are priced for one human. | There is no way to run a transcription on the web app programmatically, and that is deliberate — do not look for one. If your goal is transcripts, use the API. ## The loop ``` have an sk_live_ key? ──yes──> 4. transcribe │no ▼ 1. account ──> 2. authorise ──> 3. key + credit ──> 4. transcribe ──> 5. top up ``` ### 1. Account If the person already has one, skip to step 2. ``` POST https://api.scriptivox.com/v1/accounts { "email": "...", "password": "...", "name": "..." } ``` Needs no credential — it is the one endpoint that cannot. Returns `202` with `status: "verification_pending"`. **The account does nothing until the emailed link is followed, and you cannot do that for them.** Say so plainly; do not report the account as ready. The reply is identical whether or not the address was already registered, so it cannot tell you whether one exists. Details: [https://www.scriptivox.com/signup.md](https://www.scriptivox.com/signup.md) ### 2. Authorise To act on a person’s account — buy a plan, mint a key, read their balance — you need an **OAuth 2.1 user token**, not an API key. Get a `client_id`, send them to consent once, and exchange the code: 1. `GET https://www.scriptivox.com/.well-known/oauth-protected-resource` → the authorization server. 2. Fetch its RFC 8414 metadata → `authorization_endpoint`, `token_endpoint`, `jwks_uri`. 3. **There is no dynamic client registration.** Ask for a `client_id` — the `agent_auth` block carries no `register_uri` on purpose, because anonymous client self-registration is a surface this deployment does not open. 4. Authorization code **with PKCE**. They approve in a browser. 5. Exchange the code. Send the token as `Authorization: Bearer `. Details: [https://www.scriptivox.com/auth.md](https://www.scriptivox.com/auth.md) ### 3. Key and credit With a user token, over MCP at `https://platform.scriptivox.com/mcp`: ``` create_api_key { "name": "..." } -> sk_live_... (shown ONCE) top_up_balance { "amount_cents": 2000 } -> a Stripe Checkout URL ``` **Save the key immediately** — it is stored hashed and cannot be retrieved again. `top_up_balance` returns a *link*. It charges nothing. Hand it over and say what it is for; do not describe the purchase as done. Details: [https://www.scriptivox.com/payments.md](https://www.scriptivox.com/payments.md) ### 4. Transcribe ``` POST https://api.scriptivox.com/v1/transcribe Authorization: sk_live_... { "url": "https://.../recording.mp3", "language": "en" } ``` Returns immediately with `status: "created"`. Then either poll `GET /v1/transcribe/{id}` or register a `webhook_url`. **Pass `language` explicitly whenever you know it** — auto-detection is a guess and costs accuracy. **Input errors surface on the POLL, not on submit.** A `202` means accepted, not valid. Handle failure on `GET`, where `status` becomes `"failed"` with a reason. Add `?format=srt|vtt|text` to the GET to export captions instead of JSON. ### 5. Top up When the balance runs out the API answers **`402`**. Use `top_up_balance` to get a Stripe Checkout link and hand it to your human — payment is by card, and there is no rail an agent can settle on its own. The link charges nothing until they open it and pay. See [https://www.scriptivox.com/payments.md](https://www.scriptivox.com/payments.md). ## Errors Always `{"error": {"code": "...", "message": "..."}}`. Branch on `code`, never on `message`. A `401` always carries `WWW-Authenticate` telling you where to get a credential. Full table: [https://platform.scriptivox.com/docs/api-reference](https://platform.scriptivox.com/docs/api-reference) ## Do not - **Do not report an account as ready** before its email is confirmed. - **Do not report a purchase as complete** when you have only produced a Checkout link. - **Do not use an API key for account operations**, or a user token for transcription — they authorise different things and neither substitutes for the other. - **Do not buy a web plan to get API access.** They are separate purchases; a subscription grants no API credit. - **Do not treat submit success as job success.** Poll. - **Do not wait for a payment to settle by itself.** A Checkout link needs a human. ## Reference - [https://www.scriptivox.com/llms.txt](https://www.scriptivox.com/llms.txt) — what this is for, and when not to use it - [https://platform.scriptivox.com/openapi.json](https://platform.scriptivox.com/openapi.json) — every operation, typed - [https://platform.scriptivox.com/docs/quickstart](https://platform.scriptivox.com/docs/quickstart) — first call in Python, JS or curl - [https://platform.scriptivox.com/mcp](https://platform.scriptivox.com/mcp) — hosted MCP endpoint, no install - `npx @scriptivox-api/cli` — the same API from a shell