Medical Dictation API

The Nuxera Medical Dictation API converts dictated audio from healthcare providers into accurate, formatted text. This API is specifically optimized for post-operative notes, procedure documentation, and other medical dictations where a single speaker provides continuous clinical information.

Endpoint

URL: /api/dictate

Method: POST

Content-Type: multipart/form-data

Authentication

Include your bearer token in the Authorization header:

Authorization: Bearer <YOUR_TOKEN>

Request Parameters

Response

Success Response (200 OK)

{
  "dictation": "Patient is a 45-year-old male who presented for laparoscopic cholecystectomy due to symptomatic cholelithiasis. Under general anesthesia, four ports were placed in the standard fashion. The gallbladder was dissected free from the liver bed with good visualization of the cystic duct and artery. Both structures were clipped and divided. Hemostasis was achieved. The patient tolerated the procedure well and was transferred to recovery in stable condition.",
  "rawText": "Patient is a 45-year-old male who presented for laparoscopic cholecystectomy due to symptomatic cholelithiasis. Under general anesthesia, four ports were placed in the standard fashion. The gallbladder was dissected free from the liver bed with good visualization of the cystic duct and artery. Both structures were clipped and divided. Hemostasis was achieved. The patient tolerated the procedure well and was transferred to recovery in stable condition.",
  "timestamp": 1630000000000
}

Error Response (400 Bad Request)

{
  "error": "No audio provided"
}

Error Response (500 Internal Server Error)

{
  "error": "Failed to process dictation audio"
}

Response Structure

The API response contains the following components:

Example Usage

cURL

curl -X POST 'https://api.nuxera.ai/api/dictate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'audio=@dictation.wav' \
  -F 'doctorName=Dr. Smith' \
  -F 'patientName=John Doe'

JavaScript

// Function to process medical dictation
async function processDictation(token, audioFile, doctorName, patientName) {
  const formData = new FormData();
  formData.append('audio', audioFile);

  if (doctorName) {
    formData.append('doctorName', doctorName);
  }

  if (patientName) {
    formData.append('patientName', patientName);
  }

  try {
    const response = await fetch('https://api.nuxera.ai/api/dictate', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
      },
      body: formData,
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.error || 'Dictation processing failed');
    }

    return await response.json();
  } catch (error) {
    console.error('Dictation error:', error);
    throw error;
  }
}

// Example usage
document
  .getElementById('dictation-form')
  .addEventListener('submit', async (event) => {
    event.preventDefault();

    const audioFile = document.getElementById('audio-file').files[0];
    const doctorName = document.getElementById('doctor-name').value;
    const patientName = document.getElementById('patient-name').value;

    try {
      const result = await processDictation(
        localStorage.getItem('authToken'),
        audioFile,
        doctorName,
        patientName
      );

      // Display dictation text
      document.getElementById('dictation-text').textContent = result.dictation;

      // Store timestamp for reference
      document.getElementById('dictation-id').value = result.timestamp;
    } catch (error) {
      alert(`Error: ${error.message}`);
    }
  });

Python

import requests

def process_dictation(token, audio_file_path, doctor_name=None, patient_name=None):
    """
    Process medical dictation using the Nuxera API

    Args:
        token (str): Authentication token
        audio_file_path (str): Path to the audio file
        doctor_name (str, optional): Name of the doctor
        patient_name (str, optional): Name of the patient

    Returns:
        dict: API response containing processed dictation
    """
    url = 'https://api.nuxera.ai/api/dictate'

    # Prepare form data
    files = {
        'audio': open(audio_file_path, 'rb')
    }

    data = {}

    if doctor_name:
        data['doctorName'] = doctor_name

    if patient_name:
        data['patientName'] = patient_name

    # Set authorization header
    headers = {
        'Authorization': f'Bearer {token}'
    }

    # Make API request
    response = requests.post(url, headers=headers, files=files, data=data)

    # Check for errors
    if response.status_code != 200:
        error_data = response.json()
        raise Exception(error_data.get('error', 'Dictation processing failed'))

    return response.json()

# Example usage
try:
    token = "YOUR_AUTH_TOKEN"
    result = process_dictation(
        token=token,
        audio_file_path="./post_op_dictation.wav",
        doctor_name="Dr. Johnson"
    )

    # Print dictation
    print("DICTATION TEXT:")
    print(result['dictation'])
    print(f"\nDictation ID: {result['timestamp']}")

except Exception as e:
    print(f"Error: {str(e)}")

Advanced Features

Duplicate Removal

The dictation API automatically identifies and removes:

• Repeated words and phrases
• Duplicated sentences
• Stutters and false starts
• Unnecessary fillers

This cleaning process produces a polished final text while preserving all medically relevant information.

Format Detection

The API can detect and appropriately format common dictation elements:

• Numeric values and measurements
• Medication names and dosages
• Anatomical terms
• Procedure names and techniques
• Medical abbreviations

Session Management

Each dictation is assigned a unique timestamp that can be used to:

• Associate multiple dictations with the same patient encounter
• Reference the dictation in your electronic health record
• Track dictation history for auditing purposes

Use Cases

Post-Operative Notes

Surgeons can dictate procedure details immediately after surgery, receiving formatted documentation that can be directly incorporated into the patient record.

Example Input:

• Audio dictation by surgeon after completing a procedure

Example Output:

Patient is a 62-year-old female with a history of right breast cancer who underwent right mastectomy with sentinel lymph node biopsy. The procedure was performed under general anesthesia. A 6 cm incision was made... [detailed procedure description]... Estimated blood loss was minimal. All counts were correct. The patient tolerated the procedure well and was transferred to recovery in stable condition.

Procedure Documentation

Healthcare providers can document procedures in real-time using dictation.

Example Input:

• Audio dictation during or immediately after a medical procedure

Example Output:

Patient presented for colonoscopy due to positive fecal occult blood test. Under moderate sedation, the colonoscope was advanced to the cecum with good visualization. A 5mm polyp was identified in the sigmoid colon and removed with a hot snare. The specimen was sent to pathology. No other abnormalities were noted. The patient tolerated the procedure well.

Clinical Assessment Notes

Providers can rapidly document patient assessments, physical findings, and recommendations.

Example Input:

• Audio dictation of clinical assessment

Example Output:

Physical examination reveals a well-developed, well-nourished male in no apparent distress. Vital signs are within normal limits. Cardiovascular examination shows regular rate and rhythm without murmurs. Lungs are clear to auscultation bilaterally. Abdomen is soft, non-tender, and non-distended with normal bowel sounds. Assessment: Stable hypertension, well-controlled on current medication regimen. Plan: Continue current medications and follow up in 3 months.

Best Practices

1. Audio Quality

   • Dictate in a quiet environment with minimal background noise
   • Use a good quality microphone positioned 6-8 inches from your mouth
   • Speak clearly and at a moderate pace

2. Dictation Technique

   • Begin with patient identification and procedure type
   • Follow a consistent structure for your dictations
   • Clearly enunciate medical terms and measurements
   • Indicate punctuation when needed ("period," "new paragraph")

3. Post-Processing

   • Review the processed dictation for accuracy before incorporating into medical records
   • Pay special attention to medication names, dosages, and numeric values
   • Verify that the text accurately represents your intended documentation

4. File Handling

   • Keep audio files under 100MB for optimal processing
   • For longer dictations, consider splitting into logical segments
   • Save the timestamp returned by the API for reference

Error Handling

Limitations

• Maximum audio file size: 100MB
• Maximum dictation length: 15 minutes
• Primary language(s) support: English And Arabic(with medical terminology)
• Secondary language(s) support: Hindi, Urdu, (with medical terminology)
• Supported audio formats: WAV (others will be automatically converted)

Next Steps

Continue to the Audio Management documentation to learn how to manage audio files on the Nuxera platform.