VocalNote API Reference
BASE URL: https://worker.vocalnote.app
🔐 Authentication Guide
To access the VocalNote API, authenticate your calls by appending a Bearer token inside the Authorization header. You can retrieve and refresh your keys directly from the Developer API Dashboard.
Never expose secret keys in public code repositories or client-side files. Always run operations in secure back-channel services.
Authorization: Bearer vn_your_api_key💳 Billing Logic & Pricing Rules
VocalNote bills strictly by the second based on the audio processed or text analyzed. Deductions occur in real-time directly from your wallet balance. There are no monthly fees, flat subscriptions, or hidden charges.
- No rounding up: A 15-second transcription is billed for exactly 15 seconds.
- Credits expiry: Deposited funds stay active in your account indefinitely and never expire.
- Auto-Recharge: Top up automatically when your balance drops below the $1 threshold.
- Cap limits: Set custom monthly caps to prevent unexpected volume spikes.
Transcribe / Note Process
Transcribe and rewrite audio files with high accuracy. Send raw base64 audio and select your desired formatting style.
/apiv1/process// Parameters
| Param | Type | Required |
|---|---|---|
| audio_base64 Base64 audio string. Max 25 MB. | string | ✅ Yes |
| mode Operation mode: "transcribe", "rewrite", or "combined" (default). | string | No |
| style Clean-up style. Supported values: "Casual", "Professional", "Journal", "List", "Tweet", "Email", "Academic", "Social Media", "Meeting", "Blog Post", "Executive Summaries", "Product Spec", "Agent Prompt", "Audio-to-MIDI", "Audio-to-Sheet Music". | string | No |
// Billing Rates
curl -X POST https://worker.vocalnote.app/apiv1/process \
-H "Authorization: Bearer vn_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"mode": "combined",
"audio_base64": "UklGRiQAA...",
"mime_type": "audio/webm",
"style": "Professional"
}'{
"success": true,
"status": "processing",
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Request is processing."
}Behavioural Analytics
Analyze conversation logs to detect empathy, soft skills, calculate listener-talk ratios, and scrub PII from transcripts.
/apiv1/analyze// Parameters
| Param | Type | Required |
|---|---|---|
| transcript Raw text transcription to analyze. | string | ✅ Yes |
| save_to_vocalnote Whether to persist analytics results to the dashboard. | boolean | No |
| metadata Custom tracking object, e.g. {"call_id": "12345"} | object | No |
| scrubbed_transcript Off by default. Set to true to redact PII (SSN, credit cards). | boolean | No |
// Billing Rates
curl -X POST https://worker.vocalnote.app/apiv1/analyze \
-H "Authorization: Bearer vn_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"transcript": "Agent: Hello! Customer: I need help.",
"save_to_vocalnote": true,
"metadata": {
"call_id": "12345"
},
"scrubbed_transcript": false
}'{
"success": true,
"status": "processing",
"job_id": "776e8400-e29b-41d4-a716-446655440000",
"message": "Request is processing."
}Job Status Query
Check the processing status of a queued transcription or behavioral analysis job.
/apiv1/status/{job_id}// Parameters
| Param | Type | Required |
|---|---|---|
| job_id The job tracking ID returned from process/analyze response payload. | string | ✅ Yes |
// Billing Rates
curl -X GET https://worker.vocalnote.app/apiv1/status/{job_id} \
-H "Authorization: Bearer vn_your_api_key"{
"success": true,
"status": "completed",
"result": {
"transcription": "Verbatim audio text...",
"rewritten_text": "Polished, styled output...",
"audio_duration_sec": 42,
"cost_charged": 0.000011667,
"request_id": "550e8400-e29b-41d4-a716-446655440000"
},
"error": null,
"created_at": "2024-03-22T12:00:00Z",
"updated_at": "2024-03-22T12:00:30Z"
}
