Automating Transcriptions with the API: Practical Examples
Automation recipes with the VoxScriber API: send recordings by URL, choose engine and formats, use idempotency_key and metadata, and receive everything via webhook.
With the API, you turn any source of recordings — phone systems, meeting recorders, internal systems — into searchable text, with no manual intervention. This article walks you through the recommended flow and ready-to-use recipes. First, check the prerequisites in Transcription API (Profissional+ plan and vpt_live_ key).
The recommended flow
- Send the audio via URL with a
webhook_url. - Receive the callback when it finishes (success or failure).
- Download the exported files from the result links — they're valid for 7 days.
No polling: with a limit of 60 requests/minute per key, looping to check status wastes your quota. The webhook delivers the outcome on its own, with up to 6 redeliveries if your server is down.
Recipe 1 — transcribe every new recording
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer $VPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://storage.suaempresa.com/calls/2026-08-02-0931.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/vpt",
"formats": ["txt", "docx"],
"metadata": { "call_id": "0931", "agente": "maria" },
"idempotency_key": "call-2026-08-02-0931"
}'
metadatais returned in the webhook — use it to correlate the result with the record in your system.idempotency_keyensures accidental resends (your side's retry, a deploy in the middle of a job) don't process or bill the same audio twice.
Recipe 2 — choose the engine by cost
The engine field accepts ASSEMBLYAI (Premium, default), WHISPER (Standard), and ELEVENLABS (Ultra). For high volume where cost matters more than polish, use Whisper — 1 cycle/min vs. 4 for Premium:
-d '{ "audio_url": "...", "webhook_url": "...", "engine": "WHISPER" }'
Rule of thumb: Premium for important meetings and interviews; Standard (Whisper) for high volume and noisy audio; Ultra when speaker separation needs to be flawless (available on Profissional+).
Recipe 3 — automatic captions
Request formats: ["srt", "vtt"] and receive captions ready for YouTube or web players right in the webhook. See details of each format in Export to other tools.
Limits that affect automations
| Item | Rule |
|---|---|
| Rate limit | 60 req/min per key |
audio_url | https only, public, up to 500 MB (download) or 5 GB via passthrough with the Premium engine |
| Formats | follow your plan's gate; unallowed ones come back in exports_skipped |
| Download links | expire in 7 days (the transcription stays in your library) |
| Cycles | same costs as the website, deducted from the same balance |
Monitor your cycle balance: there's currently no spending cap per key. An automation with an uncontrolled loop consumes real balance. idempotency_key is your first line of defense.
FAQ
How do I get the final text — via webhook or do I need to download it?
The webhook brings the outcome and the links to the exported files in the requested formats. Download the files within 7 days; after that, the content remains available in the site's library.
Can I set the audio language?
Yes, via the language field. Without it, the account default applies; automatic detection is also supported by the engines.
What if two systems send the same audio?
Use the same idempotency_key in both — only the first one processes and charges.
Does automation work for organization members?
Yes — and usage follows the company plan's rules. For call auditing at scale, see the dedicated API.
Related articles
Still stuck? Open a ticket — our team replies fast.