Skip to main content

Voice Notes

Manage voice note recordings and transcriptions.

List Voice Notes​

GET /v1/voicenotes

Retrieve a paginated list of voice notes.

Query Parameters​
ParameterTypeRequiredDescriptionDefault
pageintegerNoPage number (0-indexed). See Pagination0
limitintegerNoResults per page (max: 100). See Pagination50
statusstringNoFilter by status: transcribed, processing, failed-
date_fromstringNoFilter by start date (ISO 8601), e.g. 2025-10-01-
date_tostringNoFilter by end date (ISO 8601), e.g. 2025-10-31-

See also: Filtering best practices

Request​
import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

# List all voicenotes
voicenotes = client.voicenotes.list(limit=10)

for record in voicenotes:
    print(record.id)
Response​
{
  "voicenotes": [
    {
      "id": "3d219a45-af16-4e2f-b018-dd8e44b4cf12",
      "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
      "user_id": null,
      "original_filename": "voicenote-2025-10-06T17-33-30-532Z.webm",
      "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/3d219a45-af16-4e2f-b018-dd8e44b4cf12.webm",
      "s3_bucket": "async-api-audio-dev-227647310470",
      "duration_seconds": 16.45,
      "file_size_bytes": 252287,
      "audio_format": "webm",
      "sample_rate": null,
      "channels": 1,
      "bit_rate": null,
      "audio_codec": null,
      "status": "transcribed",
      "features": null,
      "client_ip": null,
      "user_agent": null,
      "upload_source": null,
      "custom_tags": null,
      "created_at": "2025-10-06T17:33:31",
      "updated_at": "2025-10-06T17:33:45",
      "processed_at": null,
      "uri": "/v1/voicenotes/3d219a45-af16-4e2f-b018-dd8e44b4cf12"
    }
  ],
  "uri": "/v1/voicenotes?page=0&limit=10",
  "first_page_uri": "/v1/voicenotes?page=0&limit=10",
  "next_page_uri": "/v1/voicenotes?page=1&limit=10",
  "previous_page_uri": null,
  "page": 0,
  "page_size": 10,
  "total": 10
}

The response includes pagination metadata for navigating through results.

Response Fields​
FieldTypeDescription
idstringUnique voice note identifier
tenant_idstringYour VocaFuse account identifier
user_idstringEnd user identifier (from JWT token identity)
original_filenamestringOriginal file name from upload
duration_secondsnumberRecording duration in seconds
file_size_bytesintegerFile size in bytes
audio_formatstringAudio format (webm, mp3, ogg, wav)
statusstringProcessing status (see below)
created_atstringISO 8601 timestamp when created
updated_atstringISO 8601 timestamp of last update
uristringAPI endpoint for this voice note
Status Values​
StatusDescription
processingVoice note is being transcribed
transcribedTranscription completed successfully
failedProcessing failed

Get Voice Note​

GET /v1/voicenotes/{voicenote_id}

Retrieve details of a specific voice note.

Path Parameters​
ParameterTypeDescription
voicenote_idstringThe voicenote ID (e.g., rec_abc123)
Request​
import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

voicenote = client.voicenotes.get('rec_123')
Response​
{
  "id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "user_id": null,
  "original_filename": "voicenote.mp3",
  "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/606cf8f5-b294-4b9c-ad0e-3afeb99c6804.mp3",
  "s3_bucket": "async-api-audio-dev-227647310470",
  "duration_seconds": 5.0,
  "file_size_bytes": 235790,
  "audio_format": "mp3",
  "sample_rate": null,
  "channels": 1,
  "bit_rate": null,
  "audio_codec": null,
  "status": "transcribed",
  "features": null,
  "client_ip": null,
  "user_agent": null,
  "upload_source": null,
  "custom_tags": null,
  "created_at": "2025-08-28T15:54:31",
  "updated_at": "2025-08-28T15:54:34",
  "processed_at": null,
  "uri": "/v1/voicenotes/606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "subresource_uris": {
    "transcription": "/v1/voicenotes/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
  }
}

Get Transcription​

GET /v1/voicenotes/{voicenote_id}/transcription

Retrieve the transcription for a completed voice note.

Request​
import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

transcription = client.voicenotes(
  'rec_123'
).transcription.get()
Response​
{
  "id": "b585a2af-56b3-435d-a51c-024d4cccfe0f",
  "voicenote_id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "text": "This is an audio voicenote test to be uploaded to my API. I'm playing some music in the background which might provide a more thorough test.",
  "confidence": 0.95,
  "language": "english",
  "provider": "openai",
  "model": "whisper-1",
  "processing_duration_ms": 1367,
  "words": "[]",
  "created_at": "2025-08-28T15:54:34",
  "updated_at": "2025-08-28T15:54:34",
  "uri": "/v1/voicenotes/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
}
warning

Not Ready Error: Returns 404 with error code TRANSCRIPTION_NOT_READY if transcription is still processing. Use webhooks instead of polling.

Delete Voice Note​

DELETE /v1/voicenotes/{voicenote_id}

Delete a voice note and its transcription.

Request​
import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

client.voicenotes('rec_123').delete()
Response:​
Status Code: 204 No Content

No response body is returned for successful deletions.