Transcription Documentation
Medical Transcription API
The Nuxera Medical Transcription API converts audio recordings of medical consultations into accurate text transcripts with structured clinical information. This API uses a chunked processing approach, allowing you to send audio in segments and receive a comprehensive AI Medical Note customized for your medical specialty upon completion.
Format Support
Nuxera AI supports multiple response/request formats to accommodate different healthcare system requirements:
- JSON (default): Standard API responses/requests
- HL7: Healthcare interoperability standard
- FHIR: Fast Healthcare Interoperability Resources standard
To request a specific format, include the x-response-format header in your request:
x-response-format: hl7
x-response-format: fhir
Note: If no format header is specified, responses default to JSON format.
To send request in a specific format, include the x-request-format header in your request:
x-request-format: hl7
x-request-format: fhir
Note: If the x-request-format header is not provided, the request will be processed as JSON by default.
Key Features
- Chunked Processing: Send audio in multiple chunks for real-time processing
- Specialty-Specific Notes: AI Medical Notes tailored to your medical specialty
- Stateless & Scalable: Each session is tracked but the system remains stateless for easy scaling
- Privacy-First: No audio data stored, only metadata is retained for accounting
- HTTPS Required: All data transmission must be over secure HTTPS connections
Endpoint
URL: /api/transcribe
Method: POST
Content-Type: multipart/form-data
Protocol: HTTPS (Required)
Authentication
Include your API key in the x-api-key header:
x-api-key: YOUR_API_KEY
Important: A valid API key is required for all requests. Missing or invalid API keys will return a 401 Unauthorized error.
Processing Flow
- First Chunk: Send your initial audio chunk with required parameters
- Subsequent Chunks: Send additional audio chunks
- Final Chunk: Mark the last chunk with
isFinalChunk: trueto receive the complete AI Medical Note
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| audio | File | Yes | Audio file chunk in WAV or MP3 format (WAV recommended) |
| speciality | string | Yes | Medical specialty (see /api/specialities/supported for valid options) |
| userId | string | No | Unique identifier for the user |
| doctorName | string | No | Name of the doctor conducting the consultation |
| patientName | string | No | Name of the patient (improves accuracy) |
| patientId | string | No | Unique identifier for the patient |
| model | string | No | Transcription model to use (default: "new-large") |
| skipDiarization | string | No | Set to "true" to skip speaker separation (recommended) |
| removeSilence | string | No | Set to "true" to remove silence from audio (recommended) |
| sessionId | string | No | Empty for first chunk only. Will be sent for all subsequent chunks. |
| isFinalChunk | string | No | Set to "true" for the last chunk to trigger AI Medical Note generation |
Request Example:
Supported Specialities
Get the list of supported specialities and their internal names:
Endpoint: /api/specialities/supported
Method: GET
Authentication
Include your API key in the x-api-key header:
x-api-key: YOUR_API_KEY
Response Example:
Medical Note Generation
Get medical note for transcribed text:
Endpoint: /api/transcribe/medical-note
Method: POST
Content-Type: application/json
Authentication: Include your API key in the x-api-key header:
x-api-key: YOUR_API_KEY
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| transcribedText | string | Yes | Transcribed text which needs medical note. |
| userId | string | Yes | Unique identifier for the user |
| speciality | string | Yes | Medical specialty (see /api/specialities/supported for valid options) |
| patientName | string | No | Name of the patient (improves accuracy) |
| doctorName | string | No | Name of the doctor conducting the consultation |
| skipDiarization | string | No | Set to "true" to skip speaker separation (recommended) |
Request Example
Response Example
ICD-10 Code Lookup
Get ICD-10 codes for specific diagnoses or symptoms:
Endpoint: /api/medical-codes/icd-10
Method: POST
Content-Type: application/json
Authentication: Include your API key in the x-api-key header:
x-api-key: YOUR_API_KEY
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| diagnosis | string | Yes | The diagnosis or symptom to get ICD-10 code for |
Request Example
Response Example
Response Formats
Intermediate Chunks Response
For non-final chunks, you receive a simple transcription:
Final Chunk Response (Complete AI Medical Note)
When isFinalChunk is set to true, you receive the complete AI Medical Note:
Response Structure
Processing Times
The final response includes detailed processing metrics:
- transcriptionMs: Time spent on transcription processing
- finalChunkProcessingMs: Time spent on final AI analysis
- totalProcessingMs: Total processing time for the session
Classified Information Structure
| Field | Description | Example |
|---|---|---|
| ICD-10 Code | Standard diagnostic codes | ["F48.0"] |
| Chief Complaint | Primary reasons for visit | ["Constant fatigue", "Light sleep"] |
| History Of Present Illness | Detailed symptom history | ["Patient reports developing symptoms 3 days ago..."] |
| Current Medications | Active medications | ["Zithromax", "Multivitamins"] |
| Imaging Results | Findings from any imaging | ["Chest X-ray shows no acute abnormalities"] |
| Assessment | Clinical evaluation | ["Possible iron deficiency", "Possible thyroid problem"] |
| Diagnosis | Medical diagnoses | ["Acute asthma exacerbation"] |
| Prescriptions | New medications prescribed | ["Vitamin B", "Panadol"] |
| Plan | Treatment and next steps | ["Increase intake of iron-rich foods", "Take adequate rest"] |
| Follow-up | Recommended follow-up timing | ["1 week after blood test"] |
Example Usage
Privacy & Security
- HTTPS Required: All API calls must be made over HTTPS
- No Data Storage: Audio data is not stored on our servers
- Metadata Only: Only session metadata is retained for accounting purposes
- Stateless Design: Each session is independent, allowing for easy scaling
- Session Tracking: Every chunk and session is accounted for billing and monitoring
Best Practices
-
Audio Quality
- Record in a quiet environment with minimal background noise
- Use good quality microphone positioned close to speakers
- Aim for clear speech with minimal overlapping conversation
- Prefer WAV format over MP3 for best transcription accuracy (lossless vs. compressed)
-
Chunking Strategy
- Send audio in logical segments (e.g., every 30-60 seconds)
- Ensure chunks contain complete sentences when possible
- Mark the final chunk accurately to trigger AI Medical Note generation
-
Specialty Selection
- Always check
/api/specialities/supportedfor current options - Use the correct
valuefor the specialty parameter - Choose the most specific specialty for best results
- Always check
-
Error Handling
- Always check for 401 errors indicating invalid API keys
- Implement retry logic for network failures
- Validate API responses before processing
Error Handling
| Error Code | Description | Resolution |
|---|---|---|
| 401 | Invalid API key | Check that x-api-key header contains valid API key |
| 400 | Missing required fields | Ensure all required parameters are included |
| 400 | Invalid audio format | Upload audio in WAV or MP3 format |
| 400 | Invalid specialty | Check /api/specialities/supported for valid options |
| 413 | Audio file too large | Reduce chunk size or split recording further |
| 500 | Transcription failed | Check audio quality and try again |
Limitations
- Maximum audio chunk size: 25MB per request
- Maximum session length: 120 minutes total
- Supported languages: English and Arabic, with Urdu and Hindi in development
- Supported audio formats: WAV and MP3 (WAV recommended for lossless quality and wide compatibility)
- API rate limits apply (contact support for details)
Next Steps
Continue to the Dictation API documentation to learn about specialized medical dictation processing.